@felixdotgo/aidlc-kit 0.0.1 → 0.1.1

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

@@ -0,0 +1,284 @@
+/**
+ * Git handoff helpers: create lead/worker/isolated worktrees, sync the
+ * integration branch, and produce scoped change reports.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readlinkSync, rmSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { isLoopProvider } from "./loop-drivers.mjs";
+import { createWorkerSnapshot, inspectWorkerSnapshot } from "./loop-worker-snapshot.mjs";
+
+const SHA = /^[0-9a-f]{40,64}$/;
+const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const BRANCH = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,240}$/;
+
+function git(root, ...args) {
+  return execFileSync("git", args, { cwd: root, encoding: "utf8", timeout: 30_000, maxBuffer: 4 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+function validId(value, label) {
+  if (typeof value !== "string" || !ID.test(value)) throw new Error(`Invalid ${label}`);
+  return value;
+}
+function validSha(value, label) {
+  if (typeof value !== "string" || !SHA.test(value)) throw new Error(`Invalid ${label}`);
+  return value;
+}
+function validBranch(value) {
+  if (typeof value !== "string" || !BRANCH.test(value) || value.includes("..") || value.includes("//") || value.endsWith("/") || value.split("/").some((part) => part.startsWith("."))) throw new Error("Invalid Git branch");
+  return value;
+}
+function validPath(value, label = "path") {
+  if (typeof value !== "string" || !value || value.startsWith("/") || value.includes("\\") || value.includes("\0") || value.split("/").some((part, index, parts) => (!part && index !== parts.length - 1) || part === "." || part === "..") || value === ".git" || value.startsWith(".git/")) throw new Error(`Invalid ${label}: ${value}`);
+  return value;
+}
+function scopes(input) {
+  if (!Array.isArray(input) || input.length === 0) throw new Error("Assignment requires nonempty ownedPaths");
+  return [...new Set(input.map((path) => validPath(path, "owned path").replace(/\/+$/, "")))].filter(Boolean).sort();
+}
+function inScope(path, ownedPaths) { return ownedPaths.some((scope) => path === scope || path.startsWith(`${scope}/`)); }
+function changedPaths(root, base, head) {
+  const raw = execFileSync("git", ["diff", "--no-renames", "--name-only", "-z", base, head], { cwd: root, encoding: "buffer", timeout: 30_000, maxBuffer: 4 * 1024 * 1024 });
+  return raw.toString("utf8").split("\0").filter(Boolean).map((path) => validPath(path, "changed path")).sort();
+}
+function worktreePaths(root) {
+  const unstaged = execFileSync("git", ["diff", "--no-ext-diff", "--no-renames", "--name-only", "-z"], { cwd: root, encoding: "buffer", timeout: 30_000, maxBuffer: 4 * 1024 * 1024 });
+  const staged = execFileSync("git", ["diff", "--cached", "--no-ext-diff", "--no-renames", "--name-only", "-z", "HEAD"], { cwd: root, encoding: "buffer", timeout: 30_000, maxBuffer: 4 * 1024 * 1024 });
+  const untracked = execFileSync("git", ["ls-files", "--others", "--exclude-standard", "-z"], { cwd: root, encoding: "buffer", timeout: 30_000, maxBuffer: 4 * 1024 * 1024 });
+  return [...new Set(Buffer.concat([unstaged, staged, untracked]).toString("utf8").split("\0").filter(Boolean).map((path) => validPath(path, "changed path")))].sort();
+}
+function worktreeFingerprint(root, paths) {
+  // Hash the index as well as the worktree: a staged edit may differ from both
+  // HEAD and the current file, even when the latter has been restored to HEAD.
+  const index = execFileSync("git", ["ls-files", "--stage", "-z"], { cwd: root, encoding: "buffer", timeout: 30_000, maxBuffer: 4 * 1024 * 1024 });
+  const files = paths.map((path) => {
+    try {
+      const target = join(root, path);
+      const stat = lstatSync(target);
+      if (stat.isSymbolicLink()) return [path, "symlink", stat.mode, createHash("sha256").update(readlinkSync(target)).digest("hex")];
+      if (!stat.isFile()) throw new Error(`Unsupported changed path type: ${path}`);
+      return [path, "file", stat.mode, createHash("sha256").update(readFileSync(target)).digest("hex")];
+    } catch (error) {
+      if (error?.code === "ENOENT" || error?.code === "ENOTDIR") return [path, "deleted"];
+      throw error;
+    }
+  });
+  return createHash("sha256").update(git(root, "rev-parse", "HEAD")).update(index).update(JSON.stringify(files)).digest("hex");
+}
+function checkScope(paths, ownedPaths) {
+  const outside = paths.filter((path) => !inScope(path, ownedPaths));
+  if (outside.length) throw new Error(`Worker changed paths outside assignment: ${outside.join(", ")}`);
+}
+function remoteRef(remote, branch) { return `refs/remotes/${remote}/${branch}`; }
+function fetchBranch(root, remote, branch) {
+  validBranch(branch);
+  git(root, "fetch", "--no-tags", remote, `refs/heads/${branch}:${remoteRef(remote, branch)}`);
+  return git(root, "rev-parse", remoteRef(remote, branch));
+}
+function ancestor(root, base, head) {
+  try { git(root, "merge-base", "--is-ancestor", base, head); return true; } catch { return false; } /* intentional: non-git/non-worktree is treated as not clean */
+}
+function assertClean(root) {
+  if (git(root, "status", "--porcelain=v1", "--untracked-files=all")) throw new Error("Git worktree must be clean before handoff or integration");
+}
+function normaliseReport(job) {
+  const report = job.report ?? job;
+  const commitSha = validSha(report.commitSha, "reported commit SHA");
+  const changed = Array.isArray(report.changedPaths) ? [...new Set(report.changedPaths.map((path) => validPath(path, "reported path")))].sort() : null;
+  if (!changed) throw new Error("Report lacks changedPaths");
+  return { commitSha, changed };
+}
+
+/** The coordinator calls this from its protected integration checkout. */
+export function createLeadGitHandoff({ root: inputRoot, integrationBranch, remote = "origin", agent = "codex" }) {
+  // --- Validate inputs and resolve the integration checkout ------------------
+  const root = resolve(inputRoot);
+  validBranch(integrationBranch); validId(remote, "remote");
+  if (!isLoopProvider(agent)) throw new Error("Invalid worker agent");
+  const current = () => { const branch = git(root, "symbolic-ref", "--short", "HEAD"); if (branch !== integrationBranch) throw new Error(`Expected integration branch ${integrationBranch}, found ${branch}`); return git(root, "rev-parse", "HEAD"); };
+  const syncCurrent = () => {
+    assertClean(root);
+    const localHead = current();
+    const remoteHead = fetchBranch(root, remote, integrationBranch);
+    if (localHead === remoteHead || ancestor(root, remoteHead, localHead)) return localHead;
+    if (!ancestor(root, localHead, remoteHead)) throw new Error("Integration branch diverged from remote; reconcile before dispatch");
+    git(root, "merge", "--ff-only", remoteHead);
+    return current();
+  };
+  return {
+    async currentCommit() {
+      const localHead = syncCurrent();
+      const remoteHead = fetchBranch(root, remote, integrationBranch);
+      if (localHead !== remoteHead) throw new Error("Integration commit is not published to the remote branch");
+      return localHead;
+    },
+    async prepare({ taskId, item }) {
+      validId(taskId, "task ID"); validId(item?.id, "item ID");
+      const ownedPaths = scopes(item.ownedPaths);
+      const baseCommit = syncCurrent();
+      const branch = validBranch(`aidlc/${taskId}/${item.id}/${randomUUID()}`);
+      return { baseCommit, branch, ownedPaths, agent: item.agent ?? agent };
+    },
+    async verify({ job }) {
+      try {
+        const branch = validBranch(job.branch);
+        const baseCommit = validSha(job.baseCommit, "base commit");
+        const ownedPaths = scopes(job.ownedPaths);
+        const { commitSha, changed } = normaliseReport(job);
+        const fetched = fetchBranch(root, remote, branch);
+        if (fetched !== commitSha) throw new Error("Reported commit does not match remote worker branch");
+        git(root, "cat-file", "-e", `${baseCommit}^{commit}`);
+        if (!ancestor(root, baseCommit, commitSha) || baseCommit === commitSha) throw new Error("Worker commit is not descended from assigned base");
+        const actualPaths = changedPaths(root, baseCommit, commitSha);
+        checkScope(actualPaths, ownedPaths);
+        if (JSON.stringify(actualPaths) !== JSON.stringify(changed)) throw new Error("Reported changed paths do not match Git commit");
+        const currentHead = syncCurrent();
+        if (!ancestor(root, baseCommit, currentHead)) throw new Error("Integration branch no longer contains assigned base");
+        return { valid: true, commitSha, baseCommit, branch, changedPaths: actualPaths, ownedPaths, alreadyIntegrated: ancestor(root, commitSha, currentHead) };
+      } catch (error) { return { valid: false, reason: error.message }; }
+    },
+    async recover({ job }) {
+      try {
+        const branch = validBranch(job.branch);
+        const baseCommit = validSha(job.baseCommit, "base commit");
+        const ownedPaths = scopes(job.ownedPaths);
+        try { git(root, "ls-remote", "--exit-code", remote, `refs/heads/${branch}`); }
+        catch (error) {
+          if (error?.status === 2) return { recovered: false, retryable: true, reason: "Assigned remote branch has no pushed commit" };
+          throw error;
+        }
+        const commitSha = fetchBranch(root, remote, branch);
+        git(root, "cat-file", "-e", `${baseCommit}^{commit}`);
+        if (baseCommit === commitSha) return { recovered: false, retryable: true, reason: "Assigned remote branch remains at base commit" };
+        if (!ancestor(root, baseCommit, commitSha)) throw new Error("Worker branch is not descended from assigned base");
+        const changed = changedPaths(root, baseCommit, commitSha);
+        if (!changed.length) throw new Error("Worker branch has no changed paths");
+        checkScope(changed, ownedPaths);
+        const report = { commitSha, changedPaths: changed };
+        const verified = await this.verify({ job: { ...job, report } });
+        if (!verified.valid) throw new Error(verified.reason);
+        return { recovered: true, report, ...verified };
+      } catch (error) { return { recovered: false, reason: error.message }; }
+    },
+    async integrate({ job }) {
+      // A prior verification result is advisory: re-fetch the ref at integration
+      // time so a rewritten worker branch or stale report cannot be trusted.
+      const verified = await this.verify({ job });
+      if (!verified.valid) throw new Error(`Git artifact verification failed: ${verified.reason}`);
+      const before = syncCurrent();
+      if (ancestor(root, verified.commitSha, before)) {
+        try { git(root, "push", remote, `HEAD:refs/heads/${integrationBranch}`); }
+        catch (error) { throw new Error(`Integrated locally at ${before}, but remote push failed: ${error.message}`); }
+        return { integrated: false, alreadyIntegrated: true, commitSha: verified.commitSha, integrationCommit: before, changedPaths: verified.changedPaths };
+      }
+      try {
+        git(root, "-c", "user.name=AI-DLC lead", "-c", "user.email=aidlc-lead@localhost", "merge", "--no-ff", "--no-edit", verified.commitSha);
+      } catch (error) {
+        try { git(root, "merge", "--abort"); } catch { /* The original merge error is authoritative. */ }
+        throw new Error(`Git integration conflict or failure: ${error.message}`);
+      }
+      const integrationCommit = current();
+      try { git(root, "push", remote, `HEAD:refs/heads/${integrationBranch}`); }
+      catch (error) { throw new Error(`Integrated locally at ${integrationCommit}, but remote push failed: ${error.message}`); }
+      return { integrated: true, alreadyIntegrated: false, commitSha: verified.commitSha, integrationCommit, changedPaths: verified.changedPaths };
+    }
+  };
+}
+
+/** Workers receive only assignment metadata and never write the integration branch. */
+export function createWorkerGitHandoff({ root: inputRoot, worktreesRoot: inputWorktreesRoot, remote = "origin" }) {
+  const root = resolve(inputRoot);
+  const worktreesRoot = resolve(inputWorktreesRoot);
+  validId(remote, "remote");
+  if (worktreesRoot === root || worktreesRoot.startsWith(`${root}/`)) throw new Error("Worker worktree directory must be outside the source checkout");
+  return {
+    async prepare(job) {
+      validId(job.assignmentId, "assignment ID");
+      const base = validSha(job.baseCommit, "base commit");
+      const branch = validBranch(job.branch);
+      scopes(job.ownedPaths);
+      mkdirSync(worktreesRoot, { recursive: true });
+      const workspace = join(worktreesRoot, job.assignmentId);
+      if (existsSync(workspace)) {
+        const actualBranch = git(workspace, "symbolic-ref", "--short", "HEAD");
+        if (actualBranch !== branch || !ancestor(workspace, base, "HEAD")) throw new Error("Existing worker worktree does not match assignment");
+        return { root: workspace, branch };
+      }
+      git(root, "fetch", "--no-tags", remote, base);
+      git(root, "worktree", "add", "-b", branch, workspace, base);
+      return { root: workspace, branch };
+    },
+    async observe({ job, workspace, result }) {
+      const changed = worktreePaths(workspace.root);
+      checkScope(changed, scopes(job.ownedPaths));
+      const done = typeof result?.resultText === "string" && result.resultText.split(/\r?\n/).some((line) => line.trim() === "AI-DLC-ITEM-COMPLETE");
+      return { done, fingerprint: worktreeFingerprint(workspace.root, changed) };
+    },
+    async finish({ job, workspace }) {
+      const branch = validBranch(job.branch);
+      if (git(workspace.root, "symbolic-ref", "--short", "HEAD") !== branch) throw new Error("Worker switched away from assigned branch");
+      const ownedPaths = scopes(job.ownedPaths);
+      const dirty = worktreePaths(workspace.root);
+      checkScope(dirty, ownedPaths);
+      if (dirty.length) {
+        git(workspace.root, "add", "-A", "--", ...dirty);
+        git(workspace.root, "-c", "user.name=AI-DLC worker", "-c", "user.email=aidlc-worker@localhost", "commit", "-m", `AI-DLC ${validId(job.taskId, "task ID")}/${validId(job.itemId, "item ID")} ${validId(job.assignmentId, "assignment ID")}`);
+      }
+      const commitSha = git(workspace.root, "rev-parse", "HEAD");
+      const base = validSha(job.baseCommit, "base commit");
+      if (commitSha === base) throw new Error("Worker produced no commit");
+      const changed = changedPaths(workspace.root, base, commitSha);
+      checkScope(changed, ownedPaths);
+      git(workspace.root, "push", remote, `HEAD:refs/heads/${branch}`);
+      return { commitSha, changedPaths: changed };
+    },
+    async discard({ workspace }) {
+      const path = resolve(workspace.root);
+      if (!path.startsWith(`${worktreesRoot}/`)) throw new Error("Invalid worker worktree path");
+      git(root, "worktree", "remove", "--force", path);
+      rmSync(path, { recursive: true, force: true });
+    }
+  };
+}
+
+/** Worker sees only a checked source snapshot. Git and credentials remain on host. */
+export function createIsolatedWorkerGitHandoff(options) {
+  const host = createWorkerGitHandoff(options);
+  return {
+    async prepare(job) {
+      const checkout = await host.prepare(job);
+      if (worktreePaths(checkout.root).length || git(checkout.root, "rev-parse", "HEAD") !== job.baseCommit) throw new Error("Existing worker checkout requires reconciliation");
+      const tracked = execFileSync("git", ["ls-files", "-z"], { cwd: checkout.root, encoding: "utf8", timeout: 30000 }).split("\0").filter((path) => path && path !== ".agents/data" && !path.startsWith(".agents/data/"));
+      const snapshot = mkdtempSync(join(resolve(options.worktreesRoot), "snapshot-"));
+      try { const baseline = createWorkerSnapshot(checkout.root, snapshot, tracked); return { root: snapshot, checkout, baseline }; }
+      catch (error) { rmSync(snapshot, {recursive:true,force:true}); throw error; }
+    },
+    async observe({job, workspace, result}) {
+      const changed = inspectWorkerSnapshot(workspace.root, workspace.baseline, job.ownedPaths);
+      const fingerprint = createHash("sha256").update(JSON.stringify(changed.map((path) => { const full=join(workspace.root,path); return existsSync(full) ? [path,createHash("sha256").update(readFileSync(full)).digest("hex"),lstatSync(full).mode] : [path,null]; }))).digest("hex");
+      const done = typeof result?.resultText === "string" && result.resultText.split(/\r?\n/).some((line) => line.trim() === "AI-DLC-ITEM-COMPLETE");
+      return {done, fingerprint};
+    },
+    async finish({job, workspace}) {
+      const changed=inspectWorkerSnapshot(workspace.root, workspace.baseline, job.ownedPaths);
+      if (!changed.length) throw new Error("Worker produced no changes");
+      if (worktreePaths(workspace.checkout.root).length || git(workspace.checkout.root,"rev-parse","HEAD") !== job.baseCommit) throw new Error("Host checkout changed during worker run");
+      for (const path of changed) {
+        const source=join(workspace.root,path), target=join(workspace.checkout.root,path);
+        let parent = workspace.checkout.root;
+        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(target); if (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1) throw new Error("Unsafe integration target"); }
+        catch(error) { if (error.code !== "ENOENT") throw error; }
+        if (!existsSync(source)) { rmSync(target,{force:true}); continue; }
+        copyFileSync(source,target); chmodSync(target,lstatSync(source).mode & 0o777);
+      }
+      const result=await host.finish({job,workspace:workspace.checkout});
+      rmSync(workspace.root,{recursive:true,force:true}); return result;
+    },
+    async discard({workspace}) { rmSync(workspace.root,{recursive:true,force:true}); return host.discard({workspace:workspace.checkout}); }
+  };
+}

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; }
+      }
+    }
+  });
+}