@felixdotgo/aidlc-kit 0.1.1 → 0.3.0

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

@@ -1,24 +1,32 @@
 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 { ASSIGNMENT_STATE_LABELS, effectiveAssignmentState, 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}`);
   if (typeof driver !== "function" || typeof runner !== "function" || typeof onEvent !== "function") throw new Error("invalid local supervisor callbacks");
-  const adapter = createLocalSupervisorAdapter({ root, taskId });
+  const adapter = createLocalSupervisorAdapter({ root, taskId, onWarning: onEvent });
   const getRecord = () => readLoopRecord(root, taskId);
   const execute = async (mode) => {
     requireLocalAuthority();
@@ -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,142 @@ 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 now = Date.now();
+    const details = blocking.map((entry) => {
+      const state = entry.leaseExpiresAt ? effectiveAssignmentState(entry, now) : entry.state;
+      const claim = [entry.workerId ? `worker ${entry.workerId}` : null, `${ASSIGNMENT_STATE_LABELS[state] ?? state}`, entry.leaseExpiresAt ? `claim expires ${entry.leaseExpiresAt}` : null].filter(Boolean).join(", ");
+      return `${entry.state === "leased" ? "Active" : "Unresolved"} assignment ${entry.id} (${entry.state}) for ${entry.itemId} holds ${(entry.ownedPaths ?? []).join(", ")} [${claim}]`;
+    }).join("; ");
+    const releaseTarget = blocking.length === 1 ? blocking[0].id : "<assignment-id>";
+    throw new Error(`${details || `No ready build item of ${taskId} could be dispatched`}; inspect it (node .agents/aidlc/scripts/assignment.mjs show ${taskId}), then run node .agents/aidlc/scripts/assignment.mjs reconcile ${taskId} once the item is done, or node .agents/aidlc/scripts/assignment.mjs release ${taskId} ${releaseTarget} to drop the claim (discards the worker's unintegrated result)`);
+  }
+  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 }, onEvent, 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, onWarning: onEvent });
+  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,22 +2,59 @@ 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';
 
+const LABEL_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+/** 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 }) {
+export function workerDockerInvocation({ workspace, image, command, args, credentialEnv, hostEnv, uid, gid, containerName, sessionHome, labels }) {
   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');
+  // Optional `--label key=value` pairs (aidlc.task/item/worker/assignment) so the
+  // dashboard can `docker ps --filter label=`; keys and values are plain identifiers.
+  const labelArgs = [];
+  if (labels !== undefined) {
+    if (!labels || typeof labels !== 'object' || Array.isArray(labels)) throw new Error('Invalid container labels');
+    for (const [key, value] of Object.entries(labels)) {
+      if (!LABEL_PATTERN.test(key) || typeof value !== 'string' || !LABEL_PATTERN.test(value)) throw new Error(`Invalid container label: ${key}`);
+      labelArgs.push('--label', `${key}=${value}`);
+    }
+  }
   let homeMount;
   if (sessionHome !== undefined) {
     const info = lstatSync(sessionHome);
@@ -28,5 +65,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] : []), ...labelArgs, '--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/loop-worker-log.mjs

@@ -0,0 +1,158 @@
+/**
+ * Per-task record of worker containers and a raw tee of their output.
+ *
+ * Both the local loop (`loop-local-workers.mjs`) and fleet workers
+ * (`loop-fleet-cli.mjs`) write the same structure under the task's own data
+ * directory, so the dashboard lists containers identically in every mode:
+ *
+ *   .agents/data/tasks/<taskId>/runtime/workers/index.json      one entry per container (turn)
+ *   .agents/data/tasks/<taskId>/runtime/workers/<assignmentId>.log  raw stdout+stderr, all turns
+ *
+ * The log is capped at WORKER_LOG_MAX_BYTES and rotates once to `.log.1`
+ * (overwritten), the same rule as the per-task event log. Writes never throw
+ * into the caller: the first failure is reported through `onError`, later ones
+ * are swallowed. The `runtime/` directory is operational and never committed.
+ */
+import { closeSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
+import { hostname } from "node:os";
+import { join, resolve } from "node:path";
+import { taskRuntimeDir } from "./task-runtime.mjs";
+
+export const WORKER_LOG_MAX_BYTES = 5 * 1024 * 1024;
+export const WORKER_INDEX_MAX_ENTRIES = 500;
+const ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const MODES = new Set(["local", "fleet"]);
+const safeId = (value, label) => { if (typeof value !== "string" || !ID_PATTERN.test(value)) throw new Error(`Invalid ${label}`); return value; };
+const iso = () => new Date().toISOString();
+
+/** True when `path` is missing or a real (non-symlink) entry. */
+const refuseSymlink = (path) => {
+  try { if (lstatSync(path).isSymbolicLink()) throw new Error(`Worker log path crosses symlink: ${path}`); }
+  catch (error) { if (error?.code !== "ENOENT") throw error; }
+};
+
+/** `.agents/data/tasks/<taskId>/runtime/workers`, refusing symlinked components. */
+export function workerLogDirectory(root, taskId) {
+  const path = join(taskRuntimeDir(root, safeId(taskId, "task id")), "workers");
+  refuseSymlink(path);
+  return path;
+}
+export const workerIndexPath = (root, taskId) => join(workerLogDirectory(root, taskId), "index.json");
+export function workerLogPath(root, taskId, assignmentId, generation = 0) {
+  safeId(assignmentId, "assignment id");
+  const path = join(workerLogDirectory(root, taskId), `${assignmentId}.log${generation ? `.${generation}` : ""}`);
+  refuseSymlink(path);
+  return path;
+}
+
+const validEntry = (entry) => entry && typeof entry === "object" && !Array.isArray(entry) && typeof entry.name === "string" && typeof entry.assignmentId === "string" && typeof entry.startedAt === "string";
+
+/** Read a task's container index; a missing or corrupt file reads as empty. */
+export function readWorkerIndex(root, taskId) {
+  let raw;
+  try { raw = readFileSync(workerIndexPath(root, taskId), "utf8"); }
+  catch (error) { if (error?.code === "ENOENT") return []; throw error; }
+  try { const value = JSON.parse(raw); return Array.isArray(value) ? value.filter(validEntry) : []; }
+  catch { return []; }
+}
+
+function writeWorkerIndex(directory, entries) {
+  const path = join(directory, "index.json"), temp = join(directory, `index.json.${process.pid}.${Date.now().toString(36)}.tmp`);
+  const trimmed = entries.length > WORKER_INDEX_MAX_ENTRIES ? entries.slice(entries.length - WORKER_INDEX_MAX_ENTRIES) : entries;
+  const fd = openSync(temp, "w", 0o644);
+  try { writeSync(fd, `${JSON.stringify(trimmed, null, 2)}\n`); fsyncSync(fd); }
+  finally { closeSync(fd); }
+  try { renameSync(temp, path); }
+  catch (error) { try { unlinkSync(temp); } catch { /* best effort */ } throw error; }
+}
+
+/**
+ * Open the container record and raw log for one assignment.
+ * Returns `{ turnStart(containerName, turn), tee(child), turnEnd(exitCode), close() }`.
+ * `turnStart` appends `--- turn <N> container <name> <ISO> ---` and adds an index
+ * entry; `tee` appends every stdout/stderr chunk unmodified; `turnEnd` appends a
+ * trailer and records `endedAt`/`exitCode`; `close` ends a dangling turn
+ * (exitCode null) and releases the file descriptor. Methods never throw.
+ */
+export function openWorkerLog({ root, taskId, assignmentId, itemId, workerId, agent, mode, onError, maxBytes = WORKER_LOG_MAX_BYTES } = {}) {
+  if (typeof root !== "string" || !root) throw new Error("Worker log root is required");
+  safeId(taskId, "task id"); safeId(assignmentId, "assignment id"); safeId(itemId, "item id"); safeId(workerId, "worker id"); safeId(agent, "agent");
+  if (!MODES.has(mode)) throw new Error("Worker log mode must be local or fleet");
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) throw new Error("Invalid worker log size cap");
+  const base = resolve(root), host = hostname(), logName = `${assignmentId}.log`;
+  let fd = null, size = 0, reported = false, current = null, closed = false;
+  const report = (error) => {
+    if (reported) return;
+    reported = true;
+    if (typeof onError === "function") { try { onError(error instanceof Error ? error : new Error(String(error))); } catch { /* diagnostics never throw */ } }
+  };
+  const guard = (fn) => { try { fn(); } catch (error) { report(error); } };
+  const directory = () => { const path = workerLogDirectory(base, taskId); mkdirSync(path, { recursive: true }); refuseSymlink(path); return path; };
+  const open = () => {
+    if (fd !== null) return;
+    const path = workerLogPath(base, taskId, assignmentId);
+    directory();
+    fd = openSync(path, "a", 0o644);
+    try { size = lstatSync(path).size; } catch { size = 0; }
+  };
+  const write = (chunk) => {
+    if (closed) return;
+    const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk), "utf8");
+    if (!bytes.length) return;
+    open();
+    if (size > 0 && size + bytes.length > maxBytes) {
+      closeSync(fd); fd = null;
+      const path = workerLogPath(base, taskId, assignmentId);
+      refuseSymlink(workerLogPath(base, taskId, assignmentId, 1));
+      renameSync(path, `${path}.1`);
+      open();
+    }
+    let offset = 0;
+    while (offset < bytes.length) offset += writeSync(fd, bytes, offset, bytes.length - offset);
+    size += bytes.length;
+  };
+  const updateIndex = (mutate) => {
+    const dir = directory();
+    const entries = readWorkerIndex(base, taskId);
+    writeWorkerIndex(dir, mutate(entries));
+  };
+  const finish = (exitCode) => {
+    if (!current) return;
+    const entry = current; current = null;
+    const endedAt = iso(), code = Number.isSafeInteger(exitCode) ? exitCode : null;
+    try { write(`--- end turn ${entry.turn} container ${entry.name} exit ${code === null ? "signal" : code} ${endedAt} ---\n`); }
+    catch (error) { report(error); }
+    updateIndex((entries) => {
+      const index = entries.findIndex((candidate) => candidate.name === entry.name && candidate.assignmentId === assignmentId && candidate.turn === entry.turn);
+      const record = { ...(index === -1 ? entry.record : entries[index]), endedAt, exitCode: code };
+      if (index === -1) entries.push(record); else entries[index] = record;
+      return entries;
+    });
+  };
+  return {
+    turnStart(containerName, turn) {
+      guard(() => {
+        if (closed) throw new Error("Worker log is closed");
+        safeId(containerName, "container name");
+        if (!Number.isSafeInteger(turn) || turn < 0) throw new Error("Invalid worker turn");
+        if (current) finish(null);
+        const startedAt = iso();
+        const record = { name: containerName, assignmentId, itemId, workerId, agent, mode, host, turn, startedAt, log: logName };
+        current = { name: containerName, turn, record };
+        write(`--- turn ${turn} container ${containerName} ${startedAt} ---\n`);
+        updateIndex((entries) => { entries.push(record); return entries; });
+      });
+    },
+    tee(child) {
+      const listener = (chunk) => guard(() => write(chunk));
+      for (const stream of [child?.stdout, child?.stderr]) { if (stream && typeof stream.on === "function") stream.on("data", listener); }
+      return child;
+    },
+    turnEnd(exitCode) { guard(() => finish(exitCode)); },
+    close() {
+      guard(() => finish(null));
+      closed = true;
+      if (fd !== null) { const handle = fd; fd = null; try { closeSync(handle); } catch (error) { report(error); } }
+    }
+  };
+}

package/dist/assets/.agents/aidlc/scripts/lib/repo-head.mjs

@@ -0,0 +1,22 @@
+/**
+ * Resolve the repository HEAD commit for lifecycle wrappers (state.mjs, remote-state.mjs).
+ * The lifecycle core never runs git; wrappers call this and then store.mjs#recordTaskCommit.
+ */
+import { execFileSync } from "node:child_process";
+
+const shaPattern = /^[0-9a-f]{40,64}$/;
+
+/**
+ * Returns the full HEAD commit SHA of the git repository at `root`, or `undefined` when git is
+ * unavailable, `root` is not inside a repository, or the repository has no commits. Never throws.
+ */
+export const headCommit = (root, { timeout = 5000 } = {}) => {
+  if (typeof root !== "string" || !root.trim()) return undefined;
+  try {
+    const output = execFileSync("git", ["rev-parse", "--verify", "--quiet", "HEAD^{commit}"], { cwd: root, shell: false, timeout, stdio: ["ignore", "pipe", "pipe"], encoding: "utf8", maxBuffer: 4096 });
+    const sha = String(output).trim().toLowerCase();
+    return shaPattern.test(sha) ? sha : undefined;
+  } catch {
+    return undefined;
+  }
+};