@felixdotgo/aidlc-kit 0.1.1 → 0.2.0

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

@@ -1,19 +1,27 @@
 import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
 import { requireLocalAuthority } from "./authority.mjs";
 import { runAgentTurn, isLoopProvider, LOOP_PROVIDER_LIST } from "./loop-drivers.mjs";
 import { readLoopRecord, runLoop, validateRoot } from "./loop-runtime.mjs";
 import { runSupervisor } from "./loop-supervisor.mjs";
 import { createLocalSupervisorAdapter } from "./loop-supervisor-local.mjs";
+import { pathsOverlap, readyTaskItems, selectBuildBatch } from "./store.mjs";
+import { runLocalWorkerBatch } from "./loop-local-workers.mjs";
+import { reconcileLocalAssignments } from "./assignment-store.mjs";
+import { ensureWorkerImage, defaultWorkerImageTag } from "./loop-worker-image.mjs";
+import { workerCredentialKeys } from "./loop-worker-docker.mjs";
 
 const digest = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
 
 /**
  * Bind the canonical local store, distinct supervisor lease and the existing
  * leased runner. The caller owns process supervision and human gate approval.
- * Abort stops polling or the next turn; the current runLoop call is bounded by
- * its existing timeouts and is not cancelled by this wrapper.
+ * `signal` stops polling and asks runLoop to stop at its next turn boundary;
+ * `cancelSignal` also cancels the in-flight agent turn. Both end as `stopped`.
  */
-export function createLocalLoopSupervisor({ root: rootInput, taskId, agent, limits, driver = runAgentTurn, preflight = true, pollMs, signal, onEvent = () => {}, runner = runLoop } = {}) {
+export function createLocalLoopSupervisor({ root: rootInput, taskId, agent, limits, driver = runAgentTurn, preflight = true, pollMs, signal, cancelSignal, untilStop = false, onEvent = () => {}, runner = runLoop } = {}) {
   requireLocalAuthority();
   const root = validateRoot(rootInput);
   if (!isLoopProvider(agent)) throw new Error(`local lead agent must be ${LOOP_PROVIDER_LIST}`);
@@ -27,7 +35,7 @@ export function createLocalLoopSupervisor({ root: rootInput, taskId, agent, limi
     if (mode === "resume" && !record) throw new Error("Local loop record missing; use start");
     if (record && record.agent !== agent) throw new Error("Resume must use the recorded lead agent");
     let nextMode = mode;
-    return runSupervisor({ taskId, authority: "local", ...adapter, pollMs, signal, onEvent,
+    return runSupervisor({ taskId, authority: "local", ...adapter, pollMs, signal, untilStop, onEvent,
       runTurn: async ({ precondition }) => {
         if (signal?.aborted) return { status: "stopped", taskId };
         requireLocalAuthority();
@@ -37,7 +45,136 @@ export function createLocalLoopSupervisor({ root: rootInput, taskId, agent, limi
           if (snapshot.task.status !== "active" || snapshot.nextAction.classification !== "run_phase") return { status: "blocked", taskId, reason: "Canonical state changed before runner acquired lease" };
           expected = { taskId, phase: snapshot.task.phase, taskHash: digest(snapshot.task), evidenceHash: digest(snapshot.task.evidence), evidenceCount: snapshot.task.evidence.length };
         }
-        const result = await runner({ root, taskId, agent, mode: nextMode, limits, driver, preflight, precondition: expected, onEvent });
+        const result = await runner({ root, taskId, agent, mode: nextMode, limits, driver, preflight, precondition: expected, onEvent, signal, cancelSignal });
+        nextMode = "resume";
+        return result;
+      }
+    });
+  };
+  return {
+    start: () => execute("run"),
+    resume: () => execute("resume"),
+    async status() {
+      requireLocalAuthority();
+      const snapshot = await adapter.readTask({ taskId });
+      return { taskId, authority: "local", record: getRecord(), nextAction: snapshot.nextAction };
+    }
+  };
+}
+
+
+const itemPrompt = (root, taskId, itemId) => {
+  const packet = JSON.parse(execFileSync(process.execPath, [join(root, ".agents/aidlc/scripts/context.mjs"), taskId, "--phase", "build", "--item", itemId, "--format", "json", "--root", root], { cwd: root, encoding: "utf8", timeout: 30000, maxBuffer: 2 * 1024 * 1024 }));
+  if (typeof packet?.content !== "string" || !packet.content.trim()) throw new Error(`Context packet for ${itemId} was empty or invalid`);
+  return `${packet.content}\n\nOnly modify the assigned owned paths. Do not modify AI-DLC lifecycle state or approve gates. End with a Conventional Commits message on its own line as AI-DLC-COMMIT: type(scope): subject (for example AI-DLC-COMMIT: docs(ui): add web UI improvement proposal), followed by AI-DLC-ITEM-COMPLETE on its own line.`;
+};
+
+const ACTIVE_ASSIGNMENT_STATES = new Set(["leased", "reported", "uncertain"]);
+const UNRESOLVED_ASSIGNMENT_STATES = new Set(["reported", "uncertain"]);
+
+/**
+ * Pure batch planner for local build dispatch. Selects at most one item per
+ * worker from the dependency-ready items, skipping (deferring) items whose
+ * owned paths overlap each other or an active assignment, and items whose own
+ * prior assignment is unresolved. Overlap never throws: an overlapping item
+ * simply waits for a later batch. Throws only for a plan error (ready item
+ * without owned paths) or when every ready item is blocked by an active
+ * assignment, naming those assignments so a human can inspect them.
+ */
+export function planLocalBuildBatch({ taskId, task, workers, assignments = [] }) {
+  const ready = readyTaskItems(task).ready;
+  if (!ready.length) return { jobs: [], deferred: [] };
+  const providers = Object.entries(workers ?? {});
+  if (!providers.length) throw new Error("Loop requires a configured lead and worker providers");
+  const byId = new Map(task.tasks.map((item) => [item.id, item]));
+  for (const itemId of ready) {
+    const item = byId.get(itemId);
+    if (!item || !Array.isArray(item.ownedPaths) || !item.ownedPaths.length) throw new Error(`Build item ${itemId} requires an owned path scope for Docker dispatch`);
+  }
+  const active = assignments.filter((entry) => ACTIVE_ASSIGNMENT_STATES.has(entry.state));
+  const busyPaths = active.flatMap((entry) => entry.ownedPaths ?? []);
+  const unresolvedItems = [...new Set(active.filter((entry) => UNRESOLVED_ASSIGNMENT_STATES.has(entry.state) && byId.get(entry.itemId)?.status !== "done").map((entry) => entry.itemId))];
+  const { selected, deferred } = selectBuildBatch(task, { capacity: providers.length, busyPaths, exclude: unresolvedItems });
+  if (!selected.length) {
+    // Every ready item is held back by an assignment; never auto-release it.
+    const blocking = active.filter((entry) => ready.some((itemId) => entry.itemId === itemId || pathsOverlap(byId.get(itemId).ownedPaths, entry.ownedPaths ?? [])));
+    const details = blocking.map((entry) => `${entry.state === "leased" ? "Active" : "Unresolved"} assignment ${entry.id} (${entry.state}) for ${entry.itemId} holds ${(entry.ownedPaths ?? []).join(", ")}`).join("; ");
+    throw new Error(`${details || `No ready build item of ${taskId} could be dispatched`}; inspect it, then run node .agents/aidlc/scripts/assignment.mjs reconcile ${taskId} or node .agents/aidlc/scripts/assignment.mjs release ${taskId} <assignment-id>`);
+  }
+  const jobs = selected.map((itemId, index) => {
+    const [workerId, agent] = providers[index];
+    return { itemId, workerId, agent, ownedPaths: [...byId.get(itemId).ownedPaths] };
+  });
+  return { jobs, deferred };
+}
+
+const markItemDone = (root, taskId, itemId) => {
+  const envelope = JSON.parse(execFileSync(process.execPath, [join(root, ".agents/aidlc/scripts/state.mjs"), "task", "item", taskId, itemId, "--status", "done", "--root", root], { cwd: root, encoding: "utf8", timeout: 30000, maxBuffer: 2 * 1024 * 1024 }));
+  if (envelope?.ok !== true) throw new Error(`Failed to mark item ${itemId} done`);
+};
+
+/** Fan dependency-ready build items out to Docker-isolated workers, then record
+ * each integrated item as done. No worker ever marks canonical progress itself.
+ * Overlapping or excess ready items are deferred to a later batch, not failed.
+ * The trailing hooks exist for tests; production uses the defaults. */
+export async function dispatchLocalBuild({ root, taskId, task, workers, images = {}, credentials, worktreesRoot, onEvent = () => {}, cancelSignal, runBatch = runLocalWorkerBatch, ensureImage = ensureWorkerImage, prompt = itemPrompt, markDone = markItemDone }) {
+  // Reconcile completed items first so their owned paths are released for the
+  // next batch: an integrated item's assignment stays `reported` (still active)
+  // until reconciled, and overlapping owned paths would otherwise block the next
+  // claim even though the item is already done.
+  const { assignments } = reconcileLocalAssignments(root, taskId);
+  const { jobs: planned, deferred } = planLocalBuildBatch({ taskId, task, workers, assignments });
+  if (!planned.length) return;
+  for (const { id, reason } of deferred) await onEvent({ type: "build_deferred", taskId, itemId: id, reason });
+  const jobs = planned.map((job) => ({ ...job, prompt: prompt(root, taskId, job.itemId) }));
+  // Auto-build any missing per-provider image before dispatch so the user never
+  // has to build the worker image by hand.
+  const resolvedImages = {};
+  for (const provider of new Set(jobs.map((job) => job.agent))) {
+    resolvedImages[provider] = ensureImage({ root, provider, image: images[provider] ?? defaultWorkerImageTag(provider), onEvent });
+  }
+  const completed = await runBatch({ root, taskId, jobs, worktreesRoot, docker: { images: resolvedImages, credentials }, signal: cancelSignal });
+  for (const result of completed) markDone(root, taskId, result.itemId);
+}
+
+/**
+ * Local end-to-end supervisor: host-executed lead (Codex, Claude Code, or
+ * OpenCode) for clarify/plan/wrap, and Docker-isolated workers for build items.
+ * Reuses the local supervisor adapter + runSupervisor and the leased runLoop
+ * with a build dispatcher wired to runLocalWorkerBatch. Workers only ever
+ * receive environment credentials; the host lead and the trusted terminal own
+ * gates and lifecycle state.
+ */
+export function createIsolatedLocalSupervisor({ root: rootInput, taskId, agent, workers = {}, limits, docker, worktreesRoot, workerImages = {}, pollMs, signal, cancelSignal, untilStop = false, onEvent = () => {}, runner = runLoop, driver = runAgentTurn, preflight = true } = {}) {
+  requireLocalAuthority();
+  const root = validateRoot(rootInput);
+  if (!isLoopProvider(agent)) throw new Error(`local lead agent must be ${LOOP_PROVIDER_LIST}`);
+  if (!workers || typeof workers !== "object" || Array.isArray(workers) || !Object.keys(workers).length) throw new Error("Loop requires a configured lead and worker providers");
+  for (const [id, provider] of Object.entries(workers)) if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(id) || !isLoopProvider(provider)) throw new Error(`invalid local worker: ${id}`);
+  const adapter = createLocalSupervisorAdapter({ root, taskId });
+  const getRecord = () => readLoopRecord(root, taskId);
+  const images = Object.fromEntries([...new Set(Object.values(workers))].map((provider) => [provider, docker?.images?.[provider] ?? docker?.image ?? workerImages?.[provider] ?? process.env.AIDLC_WORKER_DOCKER_IMAGE ?? defaultWorkerImageTag(provider)]));
+  const credentials = docker?.credentials ?? Object.fromEntries([...new Set(Object.values(workers))].map((provider) => [provider, workerCredentialKeys(provider)]));
+  const worktrees = resolve(worktreesRoot ?? process.env.AIDLC_LOCAL_WORKTREES_ROOT ?? join(tmpdir(), "aidlc-local-worktrees"));
+  const execute = async (mode) => {
+    requireLocalAuthority();
+    const record = getRecord();
+    if (mode === "run" && record) throw new Error("Local loop record already exists; use resume");
+    if (mode === "resume" && !record) throw new Error("Local loop record missing; use start");
+    if (record && record.agent !== agent) throw new Error("Resume must use the recorded lead agent");
+    let nextMode = mode;
+    return runSupervisor({ taskId, authority: "local", ...adapter, pollMs, signal, untilStop, onEvent,
+      runTurn: async ({ precondition }) => {
+        if (signal?.aborted) return { status: "stopped", taskId };
+        requireLocalAuthority();
+        let expected = precondition;
+        if (!expected) {
+          const snapshot = await adapter.readTask({ taskId });
+          if (snapshot.task.status !== "active" || snapshot.nextAction.classification !== "run_phase") return { status: "blocked", taskId, reason: "Canonical state changed before runner acquired lease" };
+          expected = { taskId, phase: snapshot.task.phase, taskHash: digest(snapshot.task), evidenceHash: digest(snapshot.task.evidence), evidenceCount: snapshot.task.evidence.length };
+        }
+        const dispatchBuild = async ({ root, taskId, task }) => dispatchLocalBuild({ root, taskId, task, workers, images, credentials, worktreesRoot: worktrees, onEvent, cancelSignal });
+        const result = await runner({ root, taskId, agent, mode: nextMode, limits, driver, dispatchBuild, preflight, precondition: expected, onEvent, signal, cancelSignal });
         nextMode = "resume";
         return result;
       }

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

@@ -37,6 +37,8 @@ export async function checkGateCheckpoint({ checkpoint, snapshot, verifyFleetApp
   }
   const appended = task.evidence.slice(checkpoint.evidenceCount);
   const approvals = appended.filter((entry) => entry.kind === "approval" && entry.gate === checkpoint.gate && entry.result === "pass" && typeof entry.source === "string" && entry.source.trim());
+  const cancelled = appended.some((entry) => entry.kind === "diagnostic" && entry.result === "pass" && typeof entry.source === "string" && entry.source.trim() && typeof entry.detail === "string" && entry.detail.startsWith(`Cancelled gate wait at ${checkpoint.gate}: `));
+  if (task.phase === checkpoint.phase && task.gate === checkpoint.gate && task.status === "active" && nextAction.classification === "run_phase" && approvals.length === 0 && cancelled) return { status: "rejected", precondition: { taskId: checkpoint.taskId, gate: checkpoint.gate, phase: task.phase, taskHash: hash(task), evidenceCount: task.evidence.length, evidenceHash: hash(task.evidence) } };
   if (task.phase !== TARGET[checkpoint.gate] || task.status !== "active" || nextAction.classification !== "run_phase" || approvals.length !== 1) return { status: "blocked", reason: "gate changed without its matching approval" };
   if (checkpoint.authority === "local" && verifyLocalApproval && !await verifyLocalApproval({ checkpoint, snapshot })) return { status: "blocked", reason: "local approval lacks the matching host receipt" };
   if (checkpoint.authority === "fleet") {
@@ -57,7 +59,7 @@ export async function checkGateCheckpoint({ checkpoint, snapshot, verifyFleetApp
  * renewable exclusive supervisor lease that does not block human gate approval.
  * No callback is allowed to approve a human gate.
  */
-export async function runSupervisor({ taskId, authority, acquireSupervisor, readTask, runTurn, loadCheckpoint, saveCheckpoint, clearCheckpoint, verifyFleetApproval, verifyLocalApproval, pollMs = 5000, signal, onEvent = () => {} }) {
+export async function runSupervisor({ taskId, authority, acquireSupervisor, readTask, runTurn, loadCheckpoint, saveCheckpoint, clearCheckpoint, verifyFleetApproval, verifyLocalApproval, pollMs = 5000, signal, untilStop = false, onEvent = () => {} }) {
   validId(taskId, "task ID");
   if (!["local", "fleet"].includes(authority)) throw new Error("invalid authority");
   for (const [name, value] of Object.entries({ acquireSupervisor, readTask, runTurn, loadCheckpoint, saveCheckpoint, clearCheckpoint, onEvent })) required(value, name);
@@ -74,9 +76,14 @@ export async function runSupervisor({ taskId, authority, acquireSupervisor, read
       const verdict = await checkGateCheckpoint({ checkpoint, snapshot, verifyFleetApproval, verifyLocalApproval });
       if (verdict.status === "blocked") return { status: "blocked", taskId, reason: verdict.reason };
       if (verdict.status === "wait") {
+        if (untilStop) return { status: "gate", taskId, gate: checkpoint.gate };
         try { await sleep(pollMs, undefined, { signal }); } catch (error) { if (error?.name !== "AbortError") throw error; }
         continue;
       }
+      if (verdict.status === "rejected") {
+        await clearCheckpoint({ taskId, authority, checkpoint });
+        checkpoint = null;
+      }
       precondition = verdict.precondition;
     } else if (snapshot.nextAction.classification !== "run_phase") {
       return { status: snapshot.nextAction.classification === "await_user" ? "blocked" : snapshot.nextAction.classification, taskId, reason: snapshot.nextAction.classification === "await_user" ? "gate checkpoint missing; inspect the gate before resuming" : snapshot.nextAction.reason };
@@ -94,6 +101,7 @@ export async function runSupervisor({ taskId, authority, acquireSupervisor, read
     await ownership.assertOwned();
     await saveCheckpoint({ taskId, authority, checkpoint: next, previous: checkpoint });
     checkpoint = next;
+    if (untilStop) return { status: "gate", taskId, gate: next.gate, ...(next.snapshotId ? { snapshotId: next.snapshotId } : {}), gateView: result.gateView };
     await onEvent({ type: "gate", taskId, gate: next.gate, ...(next.snapshotId ? { snapshotId: next.snapshotId } : {}), gateView: result.gateView });
   }
   return { status: "stopped", taskId };

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

@@ -2,20 +2,45 @@ import { lstatSync, realpathSync } from 'node:fs';
 import { sep } from 'node:path';
 import { isLoopProvider } from './loop-drivers.mjs';
 
-/** Container workers receive credentials as environment keys only. OpenCode
- * authenticates from a file-based data store, so it fails closed here. */
+/** Container workers receive credentials as environment keys only. OpenCode can
+ * authenticate from environment variables too, so the worker path redirects its
+ * XDG data/config roots into the worker's ephemeral HOME instead of failing.
+ * The isolated LEAD container still rejects OpenCode (it needs a file-based
+ * session store that host-brokered proposals do not use); that check lives in
+ * the lead sandbox, not here. */
 export const OPENCODE_CONTAINER_ERROR = 'OpenCode workers require file-based credentials and are not available in isolated containers yet';
 
+/** OpenCode's data/config roots, redirected into the worker's tmpfs HOME so the
+ * container never reads the host ~/.local/share/opencode or ~/.config/opencode. */
+const OPENCODE_XDG_ENV = [
+  'XDG_DATA_HOME=/home/worker/.local/share',
+  'XDG_CONFIG_HOME=/home/worker/.config',
+  'XDG_CACHE_HOME=/home/worker/.cache',
+  'XDG_STATE_HOME=/home/worker/.local/state',
+  'OPENCODE_DB=/home/worker/.local/share/opencode/opencode.db'
+];
+
+/** Environment credential keys a containerized worker of `agent` receives.
+ * OpenCode authenticates from the environment like codex/claude; its key
+ * follows the configured model's provider (opencode-go → OPENCODE_API_KEY). */
+export function workerCredentialKeys(agent, env = process.env) {
+  if (agent === 'codex') return ['OPENAI_API_KEY'];
+  if (agent === 'claude') return ['ANTHROPIC_API_KEY'];
+  const model = env?.AIDLC_OPENCODE_MODEL ?? '';
+  if (model.startsWith('openai/')) return ['OPENAI_API_KEY'];
+  if (model.startsWith('anthropic/')) return ['ANTHROPIC_API_KEY'];
+  return ['OPENCODE_API_KEY'];
+}
+
 /** Build a Docker invocation. This function never accepts a shell command or credentials in arguments. */
 export function workerDockerInvocation({ workspace, image, command, args, credentialEnv, hostEnv, uid, gid, containerName, sessionHome }) {
   const root = realpathSync(workspace);
   if (/[\x00-\x1f,]/.test(root)) throw new Error('Invalid Docker workspace path');
   if (typeof image !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9._/:@-]{0,255}$/.test(image)) throw new Error('Explicit Docker image is required');
-  if (command === 'opencode') throw new Error(OPENCODE_CONTAINER_ERROR);
   if (!isLoopProvider(command) || !Array.isArray(args) || args.some((arg) => typeof arg !== 'string')) throw new Error('Invalid worker provider command');
   if (!Number.isSafeInteger(uid) || uid < 1 || !Number.isSafeInteger(gid) || gid < 1) throw new Error('Non-root worker uid and gid are required');
   if (!hostEnv || typeof hostEnv !== 'object' || !Array.isArray(credentialEnv) || !credentialEnv.length || credentialEnv.some((key) => !/^[A-Z][A-Z0-9_]*$/.test(key) || typeof hostEnv[key] !== 'string' || !hostEnv[key])) throw new Error('Explicit worker provider credentials are required');
-  const allowed = command === 'codex' ? ['OPENAI_API_KEY'] : ['ANTHROPIC_API_KEY'];
+  const allowed = command === 'codex' ? ['OPENAI_API_KEY'] : command === 'claude' ? ['ANTHROPIC_API_KEY'] : ['OPENAI_API_KEY', 'ANTHROPIC_API_KEY', 'OPENCODE_API_KEY'];
   if (credentialEnv.some((key) => !allowed.includes(key)) || new Set(credentialEnv).size !== credentialEnv.length) throw new Error('Unsupported worker credential environment');
   if (containerName !== undefined && (typeof containerName !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$/.test(containerName))) throw new Error('Invalid container name');
   let homeMount;
@@ -28,5 +53,6 @@ export function workerDockerInvocation({ workspace, image, command, args, creden
   }
   const env = { PATH: hostEnv.PATH ?? '/usr/bin:/bin' };
   for (const key of credentialEnv) env[key] = hostEnv[key];
-  return { command: 'docker', args: ['run', '--rm', '--interactive', ...(containerName ? ['--name', containerName] : []), '--read-only', '--user', `${uid}:${gid}`, '--cap-drop', 'ALL', '--security-opt', 'no-new-privileges', '--pids-limit', '256', '--memory', '2g', '--cpus', '2', '--tmpfs', '/tmp:rw,nosuid,nodev,size=256m', ...(homeMount ? ['--mount', homeMount] : ['--tmpfs', `/home/worker:rw,nosuid,nodev,size=128m,uid=${uid},gid=${gid}`]), '--env', 'HOME=/home/worker', '--workdir', '/workspace', '--mount', `type=bind,src=${root},dst=/workspace`, ...credentialEnv.flatMap((key) => ['--env', key]), '--entrypoint', command, image, ...args], env };
+  const opencodeEnv = command === 'opencode' ? [...OPENCODE_XDG_ENV, 'OPENCODE_CONFIG_CONTENT={}'].flatMap((entry) => ['--env', entry]) : [];
+  return { command: 'docker', args: ['run', '--rm', '--interactive', ...(containerName ? ['--name', containerName] : []), '--read-only', '--user', `${uid}:${gid}`, '--cap-drop', 'ALL', '--security-opt', 'no-new-privileges', '--pids-limit', '256', '--memory', '2g', '--cpus', '2', '--tmpfs', '/tmp:rw,nosuid,nodev,size=256m', ...(homeMount ? ['--mount', homeMount] : ['--tmpfs', `/home/worker:rw,nosuid,nodev,size=128m,uid=${uid},gid=${gid}`]), '--env', 'HOME=/home/worker', '--workdir', '/workspace', '--mount', `type=bind,src=${root},dst=/workspace`, ...credentialEnv.flatMap((key) => ['--env', key]), ...opencodeEnv, '--entrypoint', command, image, ...args], env };
 }

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

@@ -0,0 +1,64 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { isLoopProvider } from "./loop-drivers.mjs";
+
+/** Image tag must satisfy the same shape the Docker worker invocation accepts. */
+const IMAGE_TAG = /^[a-zA-Z0-9][a-zA-Z0-9._/:@-]{0,255}$/;
+
+/** Deterministic default tag for a provider: `aidlc-worker-<provider>:local`. */
+export const defaultWorkerImageTag = (provider) => `aidlc-worker-${provider}:local`;
+
+/** Validate an explicit image tag the way `workerDockerInvocation` will. */
+export const validWorkerImageTag = (tag) => typeof tag === "string" && IMAGE_TAG.test(tag);
+
+/** Resolve the shipped Dockerfile for a provider inside an installed project. */
+export const workerDockerfilePath = (root, provider) => join(root, ".agents", "aidlc", "docker", `Dockerfile.${provider}`);
+
+const dockerEnv = (env = process.env) => ({ PATH: env.PATH ?? "/usr/bin:/bin" });
+
+/** True when a local image with that tag already exists in the Docker daemon. */
+export function dockerImageExists(image, env = process.env) {
+  try {
+    execFileSync("docker", ["image", "inspect", "--format", "{{.Id}}", image], { env: dockerEnv(env), encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 30000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Build a worker image from the shipped Dockerfile. Streams progress to the
+ * terminal (stdio inherit) and returns the built tag. Never accepts a shell. */
+export function buildWorkerImage({ root, provider, image, env = process.env, onEvent = () => {} }) {
+  if (!isLoopProvider(provider)) throw new Error(`provider must be codex, claude, or opencode`);
+  if (!validWorkerImageTag(image)) throw new Error("Explicit Docker image is required");
+  const dockerfile = workerDockerfilePath(root, provider);
+  if (!existsSync(dockerfile)) throw new Error(`Worker Dockerfile is missing: ${dockerfile}`);
+  onEvent({ type: "worker_image_build", provider, image });
+  execFileSync("docker", ["build", "-f", dockerfile, "-t", image, join(root, ".agents", "aidlc", "docker")], { env: dockerEnv(env), stdio: "inherit" });
+  return image;
+}
+
+/** Build the image only when it is missing; otherwise return the existing tag. */
+export function ensureWorkerImage({ root, provider, image, env = process.env, onEvent = () => {} }) {
+  if (dockerImageExists(image, env)) return image;
+  return buildWorkerImage({ root, provider, image, env, onEvent });
+}
+
+/** Persist the built tag into `config.loop.workerImage[provider]` so the local
+ * supervisor can reuse it without a manual `export`. No-op when the project
+ * config does not exist yet; credentials are never persisted. */
+export function recordWorkerImage({ root, provider, image }) {
+  if (!isLoopProvider(provider) || !validWorkerImageTag(image)) throw new Error("Cannot record an invalid worker image");
+  const configPath = join(root, ".agents", "config.json");
+  if (!existsSync(configPath)) return;
+  const config = JSON.parse(readFileSync(configPath, "utf8"));
+  if (!config || typeof config !== "object" || Array.isArray(config)) return;
+  const loop = (config.loop && typeof config.loop === "object" && !Array.isArray(config.loop)) ? config.loop : {};
+  const workerImage = (loop.workerImage && typeof loop.workerImage === "object" && !Array.isArray(loop.workerImage)) ? loop.workerImage : {};
+  if (workerImage[provider] === image) return;
+  workerImage[provider] = image;
+  loop.workerImage = workerImage;
+  config.loop = loop;
+  writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`);
+}

package/dist/assets/.agents/aidlc/scripts/lib/store.mjs

@@ -307,6 +307,60 @@ export const readyTaskItems = (task) => {
   return { ready, blocked };
 };
 
+/* Parallel work partition: owned paths overlap by path segment (`a` overlaps `a/b`, not `ab`).
+ * Two open items can run concurrently unless one is a direct or transitive dependency of the other. */
+const ownedPathKey = (path) => String(path).replace(/\/+$/, "");
+export const pathOverlaps = (left, right) => { const a = ownedPathKey(left), b = ownedPathKey(right); return a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`); };
+export const pathsOverlap = (left = [], right = []) => left.some((a) => right.some((b) => pathOverlaps(a, b)));
+const itemAncestors = (task) => {
+  const byId = new Map(task.tasks.map((item) => [item.id, item])); const memo = new Map();
+  const walk = (id, trail = new Set()) => { if (memo.has(id)) return memo.get(id); const found = new Set(); if (trail.has(id)) return found; trail.add(id); for (const dep of byId.get(id)?.dependsOn ?? []) { if (!byId.has(dep)) continue; found.add(dep); for (const deeper of walk(dep, trail)) found.add(deeper); } trail.delete(id); memo.set(id, found); return found; };
+  return (id) => walk(id);
+};
+export const concurrentItemPairs = (task) => {
+  const open = task.tasks.filter((item) => !["done", "deferred"].includes(item.status)); const ancestors = itemAncestors(task); const pairs = [];
+  for (let i = 0; i < open.length; i += 1) for (let j = i + 1; j < open.length; j += 1) { const a = open[i], b = open[j]; if (!ancestors(a.id).has(b.id) && !ancestors(b.id).has(a.id)) pairs.push([a, b]); }
+  return pairs;
+};
+/** Approve-plan partition check. `strict` (enabled loop) makes findings ERRORs; otherwise WARNs. */
+export const partitionDiagnostics = (task, { strict = true } = {}) => {
+  const level = strict ? "ERROR" : "WARN"; const diagnostics = [];
+  const unscoped = task.tasks.filter((item) => !["done", "deferred"].includes(item.status) && !(Array.isArray(item.ownedPaths) && item.ownedPaths.length));
+  if (unscoped.length) diagnostics.push({ level, code: "PARTITION_SCOPE", message: `Build items need owned paths (--owns) for parallel workers: ${unscoped.map((item) => item.id).join(", ")}` });
+  for (const [a, b] of concurrentItemPairs(task)) {
+    const shared = (a.ownedPaths ?? []).filter((path) => (b.ownedPaths ?? []).some((other) => pathOverlaps(path, other)));
+    if (shared.length) diagnostics.push({ level, code: "PARTITION_OVERLAP", message: `Items ${a.id} and ${b.id} can run concurrently but both own ${shared.join(", ")}; split the paths or add --depends-on` });
+  }
+  return diagnostics;
+};
+/** The partition check is strict when the loop is enabled: `loop.mode` local/fleet in the project config, or
+ * running inside a fleet-enabled coordination service. A missing config means the default `off`; an
+ * unreadable or corrupt config fails closed (strict). */
+export const loopPartitionStrict = (root) => {
+  if (process.env.MCP_FLEET_ENABLED === "1") return true;
+  if (root === undefined) return false;
+  const path = join(resolve(root), ".agents", "config.json");
+  if (!existsSync(path)) return false;
+  try { const mode = JSON.parse(readFileSync(path, "utf8"))?.loop?.mode; return mode === "local" || mode === "fleet"; }
+  catch { return true; }
+};
+/** Pick the next dispatchable batch: dependency-ready items in plan order, at most `capacity`,
+ * skipping items that overlap each other, `busyPaths`, or are listed in `exclude`. Never throws for overlap. */
+export const selectBuildBatch = (task, { capacity = Infinity, busyPaths = [], exclude = [] } = {}) => {
+  const byId = new Map(task.tasks.map((item) => [item.id, item])); const selected = []; const deferred = []; const taken = [];
+  for (const id of readyTaskItems(task).ready) {
+    const owned = byId.get(id)?.ownedPaths ?? [];
+    if (exclude.includes(id)) { deferred.push({ id, reason: "unresolved assignment" }); continue; }
+    if (!owned.length) { deferred.push({ id, reason: "no owned paths" }); continue; }
+    if (pathsOverlap(owned, busyPaths)) { deferred.push({ id, reason: "busy path held by an active assignment" }); continue; }
+    const clash = taken.find((entry) => pathsOverlap(owned, entry.owned));
+    if (clash) { deferred.push({ id, reason: `overlaps ${clash.id}` }); continue; }
+    if (selected.length >= capacity) { deferred.push({ id, reason: "capacity" }); continue; }
+    selected.push(id); taken.push({ id, owned });
+  }
+  return { selected, deferred };
+};
+
 export const nextAction = (task, root) => {
   const rootSuffix = root === undefined ? "" : ` --root ${JSON.stringify(resolve(root))}`;
   const script = (name) => root === undefined ? `node .agents/aidlc/scripts/${name}` : `node ${JSON.stringify(join(resolve(root), ".agents/aidlc/scripts", name))}`;
@@ -357,13 +411,14 @@ export const searchLessons = (root, state, query, areas = [], limit = 5) => { co
 
 export const listTaskSummaries = (state, options = {}) => { const active = Object.values(state.tasks).map((task) => ({ id: task.id, title: task.title, phase: task.phase, gate: task.gate, status: task.status, risk: task.risk, areas: task.areas, updatedAt: task.updatedAt, source: "active" })); const archived = options.includeArchive ? Object.values(state.archive ?? {}).map((task) => ({ id: task.id, title: task.title, phase: task.phase, gate: task.gate, status: task.status, risk: task.risk, areas: task.areas, updatedAt: task.updatedAt, source: "archive" })) : []; const queryTokens = tokens(options.query ?? ""); const statusSet = new Set(options.statuses ?? []); const filtered = [...active, ...archived].filter((item) => (!statusSet.size || statusSet.has(item.status)) && (!queryTokens.length || queryTokens.every((token) => tokens(`${item.id} ${item.title} ${item.areas.join(" ")}`).includes(token)))).sort((a, b) => b.updatedAt.localeCompare(a.updatedAt) || a.id.localeCompare(b.id)); const cursor = Math.max(0, options.cursor ?? 0); const limit = Math.max(1, Math.min(options.limit ?? 20, 100)); const items = filtered.slice(cursor, cursor + limit); return { items, nextCursor: cursor + items.length < filtered.length ? String(cursor + items.length) : null, total: filtered.length }; };
 
-export const renderWorkplan = (task) => { const decisions = task.decisions.length ? task.decisions.map((item) => `- [${item.status === "approved" ? "x" : " "}] ${item.id} — ${item.label}${item.resolution ? ` — ${item.resolution}` : ""}`).join("\n") : "- None"; const tasks = task.tasks.length ? task.tasks.map((item) => `- [${item.status === "done" ? "x" : item.status === "in_progress" ? "~" : " "}] ${item.id} — ${item.label}`).join("\n") : "- None"; const lifecycle = [`- Status: \`${task.status}\``, task.handoff ? `- Handoff: \`${task.handoff.kind}\` — ${task.handoff.reason}` : "", task.closure ? `- Closure: ${task.closure.reason}` : "", task.predecessorTaskId ? `- Predecessor: \`${task.predecessorTaskId}\`` : "", task.successorTaskId ? `- Successor: \`${task.successorTaskId}\`` : "", task.lessonDisposition ? `- Lessons: \`${task.lessonDisposition.status}\`` : ""].filter(Boolean).join("\n"); return `# Workplan — ${task.title} (\`${task.id}\`)\n\n> Generated from canonical JSON state.\n\n## Lifecycle\n${lifecycle}\n\n## 🧩 Decisions (Approve plan — before implementation)\n${decisions}\n\n## 🧩 Tasks (Review implementation — work items)\n${tasks}\n`; };
+const workplanScope = (item) => { const parts = [item.ownedPaths?.length ? `owns: ${item.ownedPaths.join(", ")}` : "", item.dependsOn?.length ? `after: ${item.dependsOn.join(", ")}` : ""].filter(Boolean); return parts.length ? ` — ${parts.join(" · ")}` : ""; };
+export const renderWorkplan = (task) => { const decisions = task.decisions.length ? task.decisions.map((item) => `- [${item.status === "approved" ? "x" : " "}] ${item.id} — ${item.label}${item.resolution ? ` — ${item.resolution}` : ""}`).join("\n") : "- None"; const tasks = task.tasks.length ? task.tasks.map((item) => `- [${item.status === "done" ? "x" : item.status === "in_progress" ? "~" : " "}] ${item.id} — ${item.label}${workplanScope(item)}`).join("\n") : "- None"; const lifecycle = [`- Status: \`${task.status}\``, task.handoff ? `- Handoff: \`${task.handoff.kind}\` — ${task.handoff.reason}` : "", task.closure ? `- Closure: ${task.closure.reason}` : "", task.predecessorTaskId ? `- Predecessor: \`${task.predecessorTaskId}\`` : "", task.successorTaskId ? `- Successor: \`${task.successorTaskId}\`` : "", task.lessonDisposition ? `- Lessons: \`${task.lessonDisposition.status}\`` : ""].filter(Boolean).join("\n"); return `# Workplan — ${task.title} (\`${task.id}\`)\n\n> Generated from canonical JSON state.\n\n## Lifecycle\n${lifecycle}\n\n## 🧩 Decisions (Approve plan — before implementation)\n${decisions}\n\n## 🧩 Tasks (Review implementation — work items)\n${tasks}\n`; };
 export const renderViews = (root, state = loadState(root), selected = Object.values(state.tasks)) => { for (const task of selected) { if (!task.artifacts.workplan) continue; assertNoSymlinkPath(root, task.artifacts.workplan); writeAtomic(join(resolve(root), task.artifacts.workplan), renderWorkplan(task)); } };
 
 const safeArtifactTarget = (root, path) => { assertNoSymlinkPath(root, path); return join(resolve(root), path); };
 const artifactContent = (root, path) => { if (!path) return undefined; try { const target = safeArtifactTarget(root, path); return existsSync(target) ? readFileSync(target, "utf8") : undefined; } catch { return undefined; } /* intentional: unreadable/unsafe artifact is treated as absent */ };
 const artifactDiagnostics = (root, task, names) => names.flatMap((name) => { const path = task.artifacts[name]; if (!path) return [{ level: "ERROR", code: "ARTIFACT_REFERENCE", message: `${name} artifact is not referenced` }]; try { return existsSync(safeArtifactTarget(root, path)) ? [] : [{ level: "ERROR", code: "ARTIFACT_MISSING", message: `${path} does not exist` }]; } catch (error) { return [{ level: "ERROR", code: "ARTIFACT_UNSAFE", message: error instanceof Error ? error.message : String(error) }]; } });
-export const checkGate = (root, state, taskId, gate) => { const task = state.tasks[taskId]; if (!task) return [{ level: "ERROR", code: "TASK_UNKNOWN", message: `Unknown active task: ${taskId}` }]; const diagnostics = []; if (task.gate !== gate) diagnostics.push({ level: "ERROR", code: "GATE_STATE", message: `Task is at ${task.gate}, not ${gate}` }); if (["closed", "superseded"].includes(task.status)) diagnostics.push({ level: "ERROR", code: "TASK_TERMINAL", message: `Terminal task cannot approve ${gate}` }); if (task.handoff) diagnostics.push({ level: "ERROR", code: "TASK_HANDOFF", message: `Task has unresolved handoff: ${task.handoff.reason}` }); if (task.id !== taskId) diagnostics.push({ level: "ERROR", code: "TASK_ID", message: "Task key and id differ" }); if (!task.title.trim() || !task.areas.length) diagnostics.push({ level: "ERROR", code: "TASK_FIELDS", message: "Task title and affected areas are required" }); if (gate === "G0_confirm") { diagnostics.push(...artifactDiagnostics(root, task, ["intent"])); const content = artifactContent(root, task.artifacts.intent); if (content !== undefined) for (const heading of ["## 📋 Problem", "## 🗺️ Affected areas", "## 💭 Assumptions", "## ❓ Open questions", "## 🎯 Scope"]) if (!content.includes(heading)) diagnostics.push({ level: "ERROR", code: "INTENT_HEADING", message: `Intent is missing ${heading}` }); } if (gate === "G1_review") { diagnostics.push(...artifactDiagnostics(root, task, ["intent", "design", "workplan"])); diagnostics.push(...transitionDiagnostics(task, "build").filter((item) => item.code === "UNRESOLVED_DECISION")); const content = artifactContent(root, task.artifacts.design); if (content !== undefined) for (const heading of ["## 🧩 Solution per affected area", "## 📌 Spec traceability", "## 🔗 Cross-service contracts", "## ⚠️ Risks / edge cases"]) if (!content.includes(heading)) diagnostics.push({ level: "ERROR", code: "DESIGN_HEADING", message: `Design is missing ${heading}` }); } if (gate === "G2_codereview") { diagnostics.push(...artifactDiagnostics(root, task, ["intent", "design", "workplan"])); if (task.tasks.some((item) => !["done", "deferred"].includes(item.status))) diagnostics.push({ level: "ERROR", code: "TASKS_OPEN", message: "Build tasks remain open" }); for (const area of task.areas) if (!hasAreaVerification(task, area)) diagnostics.push({ level: "ERROR", code: "VERIFY_EVIDENCE", message: `Latest post-G1 verification evidence must pass for affected area: ${area}` }); if (!hasReview(task)) diagnostics.push({ level: "ERROR", code: "REVIEW_EVIDENCE", message: "Latest post-G1 code-review evidence must pass" }); const bounds = repairBounds(task); if (!isLegacyG2Wait(task) && (bounds.verifyExhausted || bounds.reviewExhausted)) diagnostics.push({ level: "ERROR", code: "REPAIR_BOUND", message: "Repair bound exhausted; record a durable handoff instead of presenting G2" }); } if (!diagnostics.length) diagnostics.push({ level: "INFO", code: "GATE_OK", message: `${gate} checks passed for ${taskId}` }); return diagnostics; };
+export const checkGate = (root, state, taskId, gate) => { const task = state.tasks[taskId]; if (!task) return [{ level: "ERROR", code: "TASK_UNKNOWN", message: `Unknown active task: ${taskId}` }]; const diagnostics = []; if (task.gate !== gate) diagnostics.push({ level: "ERROR", code: "GATE_STATE", message: `Task is at ${task.gate}, not ${gate}` }); if (["closed", "superseded"].includes(task.status)) diagnostics.push({ level: "ERROR", code: "TASK_TERMINAL", message: `Terminal task cannot approve ${gate}` }); if (task.handoff) diagnostics.push({ level: "ERROR", code: "TASK_HANDOFF", message: `Task has unresolved handoff: ${task.handoff.reason}` }); if (task.id !== taskId) diagnostics.push({ level: "ERROR", code: "TASK_ID", message: "Task key and id differ" }); if (!task.title.trim() || !task.areas.length) diagnostics.push({ level: "ERROR", code: "TASK_FIELDS", message: "Task title and affected areas are required" }); if (gate === "G0_confirm") { diagnostics.push(...artifactDiagnostics(root, task, ["intent"])); const content = artifactContent(root, task.artifacts.intent); if (content !== undefined) for (const heading of ["## 📋 Problem", "## 🗺️ Affected areas", "## 💭 Assumptions", "## ❓ Open questions", "## 🎯 Scope"]) if (!content.includes(heading)) diagnostics.push({ level: "ERROR", code: "INTENT_HEADING", message: `Intent is missing ${heading}` }); } if (gate === "G1_review") { diagnostics.push(...artifactDiagnostics(root, task, ["intent", "design", "workplan"])); diagnostics.push(...transitionDiagnostics(task, "build").filter((item) => item.code === "UNRESOLVED_DECISION")); const content = artifactContent(root, task.artifacts.design); if (content !== undefined) for (const heading of ["## 🧩 Solution per affected area", "## 📌 Spec traceability", "## 🔗 Cross-service contracts", "## ⚠️ Risks / edge cases"]) if (!content.includes(heading)) diagnostics.push({ level: "ERROR", code: "DESIGN_HEADING", message: `Design is missing ${heading}` }); diagnostics.push(...partitionDiagnostics(task, { strict: loopPartitionStrict(root) })); } if (gate === "G2_codereview") { diagnostics.push(...artifactDiagnostics(root, task, ["intent", "design", "workplan"])); if (task.tasks.some((item) => !["done", "deferred"].includes(item.status))) diagnostics.push({ level: "ERROR", code: "TASKS_OPEN", message: "Build tasks remain open" }); for (const area of task.areas) if (!hasAreaVerification(task, area)) diagnostics.push({ level: "ERROR", code: "VERIFY_EVIDENCE", message: `Latest post-G1 verification evidence must pass for affected area: ${area}` }); if (!hasReview(task)) diagnostics.push({ level: "ERROR", code: "REVIEW_EVIDENCE", message: "Latest post-G1 code-review evidence must pass" }); const bounds = repairBounds(task); if (!isLegacyG2Wait(task) && (bounds.verifyExhausted || bounds.reviewExhausted)) diagnostics.push({ level: "ERROR", code: "REPAIR_BOUND", message: "Repair bound exhausted; record a durable handoff instead of presenting G2" }); } if (!diagnostics.some((item) => item.level === "ERROR")) diagnostics.push({ level: "INFO", code: "GATE_OK", message: `${gate} checks passed for ${taskId}` }); return diagnostics; };
 const gateTarget = { G0_confirm: "plan", G1_review: "build", G2_codereview: "wrap" };
 export const approveAndAdvance = (root, state, taskId, gate, source, recordedAt = new Date().toISOString()) => { const task = state.tasks[taskId]; if (!task) throw new Error(`Unknown active task: ${taskId}`); if (["closed", "superseded"].includes(task.status) || task.handoff) throw new Error(`Terminal or handed-off task cannot approve ${gate}`); const target = gateTarget[gate]; if (!target) throw new Error(`Gate ${gate} cannot be approved`); if (task.phase === target) return { task, nextAction: nextAction(task, root), idempotent: true }; if (task.gate !== gate || task.status !== "blocked_on_user") throw new Error(`Task must be blocked_on_user at ${gate}`); const errors = checkGate(root, state, taskId, gate).filter((item) => item.level === "ERROR"); if (errors.length) throw new Error(errors.map((item) => item.message).join("; ")); task.evidence.push({ kind: "approval", gate, result: "pass", source, recordedAt }); transitionTask(state, taskId, target); return { task, nextAction: nextAction(task, root), idempotent: false }; };
 export const formatDiagnostics = (diagnostics) => diagnostics.map((item) => `${item.level} ${item.code}: ${item.message}`).join("\n");