@felixdotgo/aidlc-kit 0.0.1 → 0.1.0

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

@@ -0,0 +1,70 @@
+import { existsSync, lstatSync, mkdirSync, readFileSync, renameSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { nextAction } from "./store.mjs";
+
+const idPattern = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const checkedId = (id) => { if (!idPattern.test(id ?? "")) throw new Error(`Invalid feature/task id: ${id}`); return id; };
+const directory = (root) => join(root, ".agents/data/features");
+const pathOf = (root, id) => join(directory(root), `${checkedId(id)}.json`);
+const safePath = (root, id) => {
+  const dir = directory(root);
+  let cursor = root;
+  for (const part of [".agents", "data", "features"]) {
+    cursor = join(cursor, part);
+    if (existsSync(cursor) && lstatSync(cursor).isSymbolicLink()) throw new Error(`Feature path crosses symlink: ${id}`);
+  }
+  const path = pathOf(root, id);
+  if (existsSync(path) && lstatSync(path).isSymbolicLink()) throw new Error(`Feature path crosses symlink: ${id}`);
+  return path;
+};
+
+export const validateFeature = (feature, state) => {
+  if (!feature || feature.schemaVersion !== 1 || !idPattern.test(feature.id ?? "") || typeof feature.integrationBranch !== "string" || !feature.integrationBranch.trim() || !Array.isArray(feature.tasks)) throw new Error("Invalid feature manifest");
+  const byId = new Map();
+  for (const item of feature.tasks) {
+    if (!idPattern.test(item?.id ?? "") || !Array.isArray(item.dependsOn) || new Set(item.dependsOn).size !== item.dependsOn.length || byId.has(item.id)) throw new Error(`Invalid feature task: ${item?.id}`);
+    if (!state.tasks[item.id] && !state.archive?.[item.id]) throw new Error(`Unknown feature task: ${item.id}`);
+    byId.set(item.id, item);
+  }
+  const visiting = new Set(); const visited = new Set();
+  const visit = (id) => {
+    if (visiting.has(id)) throw new Error(`Cyclic feature dependency: ${id}`);
+    if (visited.has(id)) return;
+    visiting.add(id);
+    for (const dep of byId.get(id).dependsOn) {
+      if (!byId.has(dep)) throw new Error(`Unknown feature dependency: ${id}/${dep}`);
+      visit(dep);
+    }
+    visiting.delete(id); visited.add(id);
+  };
+  for (const id of byId.keys()) visit(id);
+  return feature;
+};
+
+export const loadFeature = (root, id, state) => {
+  const path = safePath(root, id);
+  return existsSync(path) ? validateFeature(JSON.parse(readFileSync(path, "utf8")), state) : undefined;
+};
+export const listFeatures = (root, state) => existsSync(directory(root)) ? readdirSync(directory(root)).filter((name) => name.endsWith(".json")).map((name) => loadFeature(root, name.slice(0, -5), state)) : [];
+export const saveFeature = (root, feature, state) => {
+  validateFeature(feature, state);
+  const path = safePath(root, feature.id);
+  mkdirSync(directory(root), { recursive: true });
+  const temporary = `${path}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(temporary, `${JSON.stringify(feature, null, 2)}\n`, "utf8");
+  renameSync(temporary, path);
+  return feature;
+};
+export const readyFeatureTasks = (feature, state) => {
+  validateFeature(feature, state);
+  const ready = []; const blocked = [];
+  for (const item of feature.tasks) {
+    const task = state.tasks[item.id] ?? state.archive?.[item.id];
+    if (task.status === "done") continue;
+    if (task.status === "closed" || task.status === "superseded") { blocked.push({ id: item.id, waitingOn: [], reason: `Task is ${task.status}` }); continue; }
+    const waitingOn = item.dependsOn.filter((id) => (state.tasks[id] ?? state.archive?.[id])?.status !== "done");
+    if (waitingOn.length) blocked.push({ id: item.id, waitingOn });
+    else ready.push({ id: item.id, nextAction: state.tasks[item.id] ? nextAction(state.tasks[item.id]) : { classification: "terminal", outcome: task.status } });
+  }
+  return { id: feature.id, ready, blocked };
+};

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

@@ -0,0 +1,215 @@
+import { spawn } from "node:child_process";
+import { accessSync, constants } from "node:fs";
+import { delimiter, join } from "node:path";
+
+const MAX_LINE_BYTES = 1024 * 1024;
+const MAX_STDERR_BYTES = 4096;
+const MAX_RESULT_CHARS = 8192;
+const MAX_DIAGNOSTICS = 16;
+
+/** One runtime enumeration for every loop provider. Host gates import this
+ * list; container paths reject providers that need file-based credentials. */
+export const LOOP_PROVIDERS = Object.freeze(["codex", "claude", "opencode"]);
+export const LOOP_PROVIDER_LIST = `${LOOP_PROVIDERS.slice(0, -1).join(", ")}, or ${LOOP_PROVIDERS[LOOP_PROVIDERS.length - 1]}`;
+export const isLoopProvider = (value) => typeof value === "string" && LOOP_PROVIDERS.includes(value);
+const OPENCODE_MODEL = /^[A-Za-z0-9][A-Za-z0-9._-]*\/[A-Za-z0-9][A-Za-z0-9._-]*(?:#[A-Za-z0-9][A-Za-z0-9._-]*)?$/;
+
+const record = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : null;
+const redact = (value) => String(value ?? "")
+  .replace(/\b([A-Z0-9_]*(?:TOKEN|SECRET|PASSWORD|API_KEY))=([^\s]+)/gi, "$1=[REDACTED]")
+  .replace(/\b(?:sk|ghp|github_pat)_[A-Za-z0-9_-]+\b/g, "[REDACTED]")
+  .replace(/\s+/g, " ").trim();
+const diagnostic = (value) => redact(value).slice(0, 512);
+const isId = (value) => typeof value === "string" && value.length > 0 && value.length <= 256 && !/[\s\x00-\x1f]/.test(value);
+const emit = async (callback, event) => { if (callback) await callback(event); };
+
+// Adapters are registered by trusted application code, never loaded from a
+// project configuration or shell string. Each adapter owns its CLI protocol.
+const adapters = new Map();
+export function registerAgentAdapter(name, adapter) {
+  if (typeof name !== "string" || !/^[a-z][a-z0-9-]{0,63}$/.test(name) || adapters.has(name)) throw new Error("invalid or duplicate agent adapter");
+  if (!adapter || typeof adapter.command !== "string" || !/^[a-z][a-z0-9-]{0,63}$/.test(adapter.command) || typeof adapter.arguments !== "function" || typeof adapter.parse !== "function" || (adapter.preflight !== undefined && typeof adapter.preflight !== "function") || (adapter.completesOnExit !== undefined && typeof adapter.completesOnExit !== "boolean")) throw new Error("agent adapter requires a command, arguments, parser, and optional preflight");
+  adapters.set(name, Object.freeze({ ...adapter }));
+}
+export async function preflightAgentAdapter(name, { env = process.env, root } = {}) {
+  const adapter = adapters.get(name);
+  if (!adapter) throw new Error(`Unknown agent adapter: ${name}`);
+  const paths = (env.PATH ?? process.env.PATH ?? "").split(delimiter);
+  if (!paths.some((entry) => { try { accessSync(join(entry || ".", adapter.command), constants.X_OK); return true; } catch { return false; } })) throw new Error(`Worker provider CLI is unavailable: ${name}`);
+  if (adapter.preflight) await adapter.preflight({ env, root });
+}
+registerAgentAdapter("codex", {
+  command: "codex",
+  arguments: ({ root, sessionId }) => ["exec", "--json", "--sandbox", "workspace-write", "--skip-git-repo-check", "-C", root, ...(sessionId ? ["resume", sessionId] : []), "-"],
+  input: (prompt) => prompt,
+  parse: async (event, context) => {
+    if (event.type === "thread.started") await context.captureId(event.thread_id);
+    if (event.type === "turn.completed") context.complete();
+    if (event.type === "turn.failed" || event.type === "error") throw new Error(`codex reported ${event.type}: ${diagnostic(JSON.stringify(event.error ?? event.message ?? "unknown"))}`);
+    const item = record(event.item);
+    if (event.type === "item.completed" && item?.type === "agent_message" && typeof item.text === "string") context.result(item.text);
+    if (event.type === "item.completed" && item?.type === "command_execution") await context.commandEvent(item.exit_code, item.status);
+  }
+});
+registerAgentAdapter("claude", {
+  command: "claude",
+  arguments: ({ sessionId }) => ["-p", "--verbose", "--input-format", "stream-json", "--output-format", "stream-json", "--permission-mode", "acceptEdits", ...(sessionId ? ["--resume", sessionId] : [])],
+  input: (prompt) => `${JSON.stringify({ type: "user", message: { role: "user", content: prompt } })}\n`,
+  parse: async (event, context) => {
+    if (event.session_id !== undefined) await context.captureId(event.session_id);
+    if (event.type === "result") {
+      if (event.is_error === true) throw new Error(`claude reported an error: ${diagnostic(event.result)}`);
+      context.complete();
+      if (typeof event.result === "string") context.result(event.result);
+    }
+    const message = record(event.message);
+    if (Array.isArray(message?.content)) for (const block of message.content) {
+      if (!record(block)) continue;
+      if (block.type === "tool_use" && typeof block.id === "string" && block.name === "Bash") context.toolUses.set(block.id, true);
+      if (block.type === "tool_result" && typeof block.tool_use_id === "string" && context.toolUses.has(block.tool_use_id)) {
+        context.toolUses.delete(block.tool_use_id);
+        await context.commandEvent(block.is_error === true ? 1 : 0, block.is_error === true ? "failed" : "completed");
+      }
+    }
+  }
+});
+
+registerAgentAdapter("opencode", {
+  command: "opencode",
+  completesOnExit: true,
+  arguments: ({ sessionId, prompt, env }) => {
+    const model = (env ?? process.env).AIDLC_OPENCODE_MODEL;
+    if (typeof model !== "string" || !OPENCODE_MODEL.test(model)) throw new Error("opencode provider requires AIDLC_OPENCODE_MODEL");
+    return ["run", "--format", "json", "--standalone", "--auto", ...(sessionId ? ["--session", sessionId] : []), "--model", model, prompt];
+  },
+  parse: async (event, context) => {
+    if (event.sessionID !== undefined) await context.captureId(event.sessionID);
+    const part = record(event.part);
+    if (event.type === "text" && typeof part?.text === "string") context.result(part.text);
+    if (event.type === "tool_use" && part?.tool === "shell") {
+      const state = record(part.state);
+      const metadata = record(record(state?.metadata)?.metadata);
+      await context.commandEvent(metadata?.exit, state?.status === "error" ? "failed" : state?.status);
+    }
+    if (event.type === "step_finish" && part?.reason === "stop") context.complete();
+  }
+});
+
+/**
+ * Run exactly one agent turn for a registered provider. The returned session ID
+ * is the CLI's exact ID; onSessionId observes it immediately. Callers decide when
+ * a checkpoint is durable. Transport and protocol failures reject with a bounded,
+ * redacted error message.
+ */
+export async function runAgentTurn({ agent, root, sessionId, prompt, timeoutMs, onSessionId, onEvent, signal, env, spawnProcess = spawn } = {}) {
+  const adapter = adapters.get(agent);
+  if (!adapter) throw new Error(`agent must be ${LOOP_PROVIDER_LIST} or a trusted registered adapter`);
+  if (typeof root !== "string" || !root) throw new Error("root must be a nonempty path");
+  if (typeof prompt !== "string" || !prompt) throw new Error("prompt must be nonempty");
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1) throw new Error("timeoutMs must be a positive integer");
+  if (sessionId !== undefined && !isId(sessionId)) throw new Error("invalid explicit session ID");
+  if (onSessionId !== undefined && typeof onSessionId !== "function") throw new Error("onSessionId must be a function");
+  if (onEvent !== undefined && typeof onEvent !== "function") throw new Error("onEvent must be a function");
+  if (signal !== undefined && !(signal instanceof AbortSignal)) throw new Error("signal must be an AbortSignal");
+  if (signal?.aborted) throw new Error("agent turn aborted before start");
+
+  const args = adapter.arguments({ root, sessionId, prompt, env });
+  if (!Array.isArray(args) || args.some((arg) => typeof arg !== "string")) throw new Error("agent adapter arguments must be an array of strings");
+  if (typeof spawnProcess !== "function") throw new Error("spawnProcess must be a function");
+  const input = adapter.input?.(prompt);
+  if (input !== undefined && typeof input !== "string") throw new Error("agent adapter input must be a string");
+  const child = spawnProcess(adapter.command, args, { cwd: root, shell: false, env: { ...(env ?? process.env), PWD: root }, stdio: [input === undefined ? "ignore" : "pipe", "pipe", "pipe"] });
+  if (input !== undefined) {
+    if (!child.stdin) throw new Error("agent transport lacks stdin");
+    child.stdin.on("error", () => {});
+    child.stdin.end(input);
+  }
+  const diagnostics = [];
+  let exactId = sessionId;
+  let resultText = "";
+  let stdoutBuffer = "";
+  let stderrText = "";
+  let stderrBytes = 0;
+  let failed;
+  let timedOut = false;
+  let aborted = false;
+  let completed = false;
+  let resultSeen = false;
+  let processing = Promise.resolve();
+  let killTimer;
+  const toolUses = new Map();
+  const addDiagnostic = (value) => {
+    if (diagnostics.length < MAX_DIAGNOSTICS) diagnostics.push(diagnostic(value));
+  };
+  const fail = (message) => {
+    if (!failed) failed = diagnostic(message);
+    child.kill("SIGTERM");
+    killTimer ??= setTimeout(() => child.kill("SIGKILL"), 1000);
+  };
+  const abort = () => { aborted = true; child.kill("SIGTERM"); killTimer ??= setTimeout(() => child.kill("SIGKILL"), 1000); };
+  signal?.addEventListener("abort", abort, { once: true });
+  if (signal?.aborted) abort();
+  const captureId = async (value) => {
+    if (!isId(value)) throw new Error(`${agent} reported an invalid session ID`);
+    if (exactId && exactId !== value) throw new Error(`${agent} session ID changed during turn`);
+    if (!exactId) {
+      exactId = value;
+      await emit(onSessionId, value);
+    }
+  };
+  const commandEvent = async (exitCode, status) => {
+    const safeExitCode = Number.isSafeInteger(exitCode) ? exitCode : null;
+    const safeStatus = ["completed", "failed", "in_progress"].includes(status) ? status : "unknown";
+    await emit(onEvent, { type: "lifecycle_command", exitCode: safeExitCode, status: safeStatus });
+    if ((safeExitCode !== null && safeExitCode !== 0) || safeStatus === "failed") addDiagnostic(`commandFailed exitCode=${String(safeExitCode ?? "unknown")} status=${safeStatus}`);
+  };
+  const parseEvent = async (line) => {
+    let event;
+    try { event = JSON.parse(line); } catch { throw new Error(`${agent} emitted malformed JSONL`); }
+    if (!record(event) || typeof event.type !== "string") throw new Error(`${agent} emitted malformed event`);
+    await adapter.parse(event, { captureId, commandEvent, toolUses, complete: () => { completed = true; resultSeen = true; }, result: (value) => { resultText = value.slice(0, MAX_RESULT_CHARS); } });
+    await emit(onEvent, { type: "agent_event", eventType: event.type });
+  };
+  const queueLine = (line) => {
+    processing = processing.then(() => parseEvent(line)).catch((error) => fail(error.message));
+  };
+  child.stdout.on("data", (chunk) => {
+    if (failed) return;
+    stdoutBuffer += chunk.toString("utf8");
+    if (Buffer.byteLength(stdoutBuffer) > MAX_LINE_BYTES && !stdoutBuffer.includes("\n")) { fail(`${agent} JSONL line exceeded limit`); return; }
+    let end;
+    while ((end = stdoutBuffer.indexOf("\n")) !== -1) {
+      const line = stdoutBuffer.slice(0, end).trim();
+      stdoutBuffer = stdoutBuffer.slice(end + 1);
+      if (Buffer.byteLength(line) > MAX_LINE_BYTES) { fail(`${agent} JSONL line exceeded limit`); return; }
+      if (line) queueLine(line);
+    }
+  });
+  child.stderr.on("data", (chunk) => {
+    const remaining = MAX_STDERR_BYTES - stderrBytes;
+    if (remaining > 0) { stderrText += chunk.subarray(0, remaining).toString("utf8"); stderrBytes += Math.min(chunk.length, remaining); }
+  });
+  const timer = setTimeout(() => { timedOut = true; child.kill("SIGTERM"); killTimer ??= setTimeout(() => child.kill("SIGKILL"), 1000); }, timeoutMs);
+  timer.unref();
+  const exit = await new Promise((resolve) => {
+    child.once("error", (error) => resolve({ error }));
+    child.once("close", (code, signal) => resolve({ code, signal }));
+  });
+  clearTimeout(timer);
+  clearTimeout(killTimer);
+  signal?.removeEventListener("abort", abort);
+  if (stdoutBuffer.trim() && !failed) queueLine(stdoutBuffer.trim());
+  await processing;
+  if (timedOut) throw new Error(`${agent} turn timed out after ${timeoutMs} ms`);
+  if (aborted) throw new Error(`${agent} turn aborted`);
+  if (exit.error) throw new Error(`${agent} failed to start: ${diagnostic(exit.error.message)}`);
+  if (failed) throw new Error(failed);
+  if (exit.code !== 0) throw new Error(`${agent} exited ${exit.code ?? exit.signal}: ${diagnostic(stderrText)}`);
+  if (!exactId) throw new Error(`${agent} turn ended without an explicit captured session ID`);
+  if (agent === "claude" && !resultSeen) throw new Error("claude turn ended without a result event");
+  if (!completed && adapter.completesOnExit === true) completed = true;
+  if (!completed) throw new Error(`${agent} turn ended without a completion event`);
+  if (stderrText.trim()) addDiagnostic(`stderr: ${stderrText}`);
+  await emit(onEvent, { type: "turn_completed" });
+  return { sessionId: exactId, resultText, diagnostics };
+}

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

@@ -0,0 +1,183 @@
+import { chmodSync, existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { execFileSync, spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { join, resolve } from "node:path";
+import { isLoopProvider, LOOP_PROVIDER_LIST, runAgentTurn } from "./loop-drivers.mjs";
+import { runFleetCoordinator, runFleetWorker, validateFleetLimits } from "./loop-fleet.mjs";
+import { runFleetSupervisor } from "./loop-fleet-supervisor.mjs";
+import { createFleetRemoteRepository } from "./loop-fleet-remote.mjs";
+import { createLeadGitHandoff, createIsolatedWorkerGitHandoff } from "./loop-git.mjs";
+import { workerDockerInvocation, OPENCODE_CONTAINER_ERROR } from "./loop-worker-docker.mjs";
+
+const required = (env, name) => { const value = env[name]; if (typeof value !== "string" || !value.trim()) throw new Error(`${name} is required`); return value; };
+const pause = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const provider = (value, name) => { if (!isLoopProvider(value)) throw new Error(`${name} must be ${LOOP_PROVIDER_LIST}`); return value; };
+function workerMapping(env, workerIds, defaultAgent) {
+  if (!env.AIDLC_FLEET_WORKER_PROVIDERS) return Object.fromEntries(workerIds.map((id) => [id, defaultAgent]));
+  let mapping;
+  try { mapping = JSON.parse(env.AIDLC_FLEET_WORKER_PROVIDERS); } catch { throw new Error("AIDLC_FLEET_WORKER_PROVIDERS must be a JSON object"); }
+  if (!mapping || typeof mapping !== "object" || Array.isArray(mapping) || Object.keys(mapping).length !== workerIds.length || workerIds.some((id) => !Object.hasOwn(mapping, id) || !isLoopProvider(mapping[id])) || Object.keys(mapping).some((id) => !workerIds.includes(id))) throw new Error(`AIDLC_FLEET_WORKER_PROVIDERS must map every configured worker ID to ${LOOP_PROVIDER_LIST}`);
+  return mapping;
+}
+
+/** Package-local entrypoint. The service wrapper supplies its MCP HTTP client. */
+export async function runFleetCli(argv, { callTool, env = process.env, out = console.log, signal, coordinator: coordinatorOverride } = {}) {
+  const [role, targetId, ...flags] = argv;
+  if (!["coordinator", "feature", "worker", "supervisor"].includes(role) || ((role === "coordinator" || role === "feature" || role === "supervisor") && !targetId) || flags.some((arg) => arg !== "--once") || (role === "supervisor" && flags.length) || (role === "worker" && targetId && targetId !== "--once")) throw new Error("Usage: aidlc-fleet coordinator <task-id> [--once] | feature <feature-id> [--once] | supervisor <task-id> | worker [--once]");
+  const once = flags.includes("--once") || (role === "worker" && targetId === "--once");
+  if (role === "worker" && targetId && targetId !== "--once") throw new Error("worker accepts no task ID");
+  const root = resolve(required(env, "AIDLC_FLEET_PROJECT_ROOT"));
+  const url = required(env, "AIDLC_FLEET_URL");
+  const token = required(env, "AIDLC_FLEET_TOKEN");
+  const workspace = required(env, "AIDLC_FLEET_WORKSPACE");
+  const remote = env.AIDLC_FLEET_GIT_REMOTE ?? "origin";
+  const limits = validateFleetLimits({
+    ...(env.AIDLC_FLEET_MAX_TURNS ? { maxTurns: Number(env.AIDLC_FLEET_MAX_TURNS) } : {}),
+    ...(env.AIDLC_FLEET_TURN_TIMEOUT_MS ? { turnTimeoutMs: Number(env.AIDLC_FLEET_TURN_TIMEOUT_MS) } : {}),
+    ...(env.AIDLC_FLEET_MAX_STALL_TURNS ? { maxStallTurns: Number(env.AIDLC_FLEET_MAX_STALL_TURNS) } : {}),
+    ...(env.AIDLC_FLEET_MAX_WORKERS ? { maxWorkers: Number(env.AIDLC_FLEET_MAX_WORKERS) } : {}),
+    ...(env.AIDLC_FLEET_LEASE_MS ? { leaseMs: Number(env.AIDLC_FLEET_LEASE_MS) } : {}),
+    ...(env.AIDLC_FLEET_HEARTBEAT_MS ? { heartbeatMs: Number(env.AIDLC_FLEET_HEARTBEAT_MS) } : {})
+  });
+  const repository = createFleetRemoteRepository({ callTool, url, token, workspace, root, workerId: env.AIDLC_FLEET_WORKER_ID });
+  const pollMs = env.AIDLC_FLEET_POLL_MS ? Number(env.AIDLC_FLEET_POLL_MS) : 5000;
+  if (!Number.isSafeInteger(pollMs) || pollMs < 1000 || pollMs > 300000) throw new Error("AIDLC_FLEET_POLL_MS must be 1000..300000");
+  if (env.AIDLC_FLEET_CODE_ONLY_RETRY && !["0", "1"].includes(env.AIDLC_FLEET_CODE_ONLY_RETRY)) throw new Error("AIDLC_FLEET_CODE_ONLY_RETRY must be 0 or 1");
+  const emit = (event) => out(JSON.stringify(event));
+  if (role === "worker") {
+    const workerId = required(env, "AIDLC_FLEET_WORKER_ID");
+    const workerAgentSetting = env.AIDLC_FLEET_WORKER_AGENT ?? env.AIDLC_FLEET_AGENT;
+    const workerAgent = workerAgentSetting === undefined ? undefined : provider(workerAgentSetting, "AIDLC_FLEET_WORKER_AGENT");
+    if (workerAgent === "opencode") throw new Error(OPENCODE_CONTAINER_ERROR);
+    const requestedImage = required(env, "AIDLC_WORKER_DOCKER_IMAGE");
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._/:@-]{0,255}$/.test(requestedImage)) throw new Error("Invalid Docker worker image");
+    const image = execFileSync("docker", ["image", "inspect", "--format", "{{.Id}}", requestedImage], {env:{PATH:env.PATH ?? "/usr/bin:/bin"},encoding:"utf8",timeout:30000,stdio:["ignore","pipe","ignore"]}).trim();
+    if (!/^sha256:[a-f0-9]{64}$/.test(image)) throw new Error("Docker worker image lacks immutable image ID");
+    const uid = process.getuid?.(), gid = process.getgid?.();
+    if (!Number.isSafeInteger(uid) || uid < 1 || !Number.isSafeInteger(gid) || gid < 1) throw new Error("Docker worker requires a non-root host uid and gid");
+    const preflight = async (agent) => {
+      const credential = agent === "codex" ? "OPENAI_API_KEY" : "ANTHROPIC_API_KEY";
+      const empty = mkdtempSync(join(tmpdir(), "aidlc-worker-preflight-"));
+      try {
+        const invocation = workerDockerInvocation({workspace:empty,image,command:agent,args:["--version"],credentialEnv:[credential],hostEnv:env,uid,gid});
+        execFileSync("docker", ["info"], {env:{PATH:invocation.env.PATH},stdio:"ignore",timeout:30000});
+        execFileSync("docker", ["image","inspect",image], {env:{PATH:invocation.env.PATH},stdio:"ignore",timeout:30000});
+        const name = `aidlc-worker-preflight-${randomUUID()}`;
+        const args = invocation.args.filter((arg,index) => !(index===1 && arg==="--rm"));
+        args.splice(1,0,"--name",name);
+        let failure;
+        try { execFileSync(invocation.command, args, {env:invocation.env,stdio:"ignore",timeout:30000}); }
+        catch (error) { failure = error; }
+        try { execFileSync("docker",["rm","--force",name],{env:{PATH:invocation.env.PATH},stdio:"ignore",timeout:30000}); }
+        catch { throw new Error("Could not confirm Docker preflight container removal"); }
+        if (failure) throw failure;
+      } finally { rmSync(empty,{recursive:true,force:true}); }
+    };
+    if (workerAgent) await preflight(workerAgent);
+    const baseHandoff = createIsolatedWorkerGitHandoff({ root, worktreesRoot: resolve(required(env, "AIDLC_FLEET_WORKTREES_ROOT")), remote });
+    const sessions = new Map();
+    const cleanupSession = (workspace) => { const current=sessions.get(workspace.root); if(current) { rmSync(current.home,{recursive:true,force:true}); sessions.delete(workspace.root); } };
+    const handoff = {
+      ...baseHandoff,
+      async prepare(job) {
+        const workspace=await baseHandoff.prepare(job);
+        const home=mkdtempSync(join(tmpdir(),"aidlc-worker-home-")); chmodSync(home,0o700);
+        sessions.set(workspace.root,{home,agent:job.agent,assignmentId:job.assignmentId,attempt:job.attempt,epoch:job.epoch,workerId,image,sessionId:null});
+        return workspace;
+      },
+      async finish(args) { try { return await baseHandoff.finish(args); } finally { cleanupSession(args.workspace); } },
+      async discard(args) { try { return await baseHandoff.discard(args); } finally { cleanupSession(args.workspace); } }
+    };
+    const isolatedDriver = async (turn) => {
+      if (turn.agent === "opencode") throw new Error(OPENCODE_CONTAINER_ERROR);
+      const session=sessions.get(turn.root);
+      if (!session || session.agent !== turn.agent || (turn.sessionId && turn.sessionId !== session.sessionId)) throw new Error("Docker worker session is not recoverable; reconcile this assignment");
+      const credential = turn.agent === "codex" ? "OPENAI_API_KEY" : "ANTHROPIC_API_KEY";
+      const name = `aidlc-worker-${randomUUID()}`;
+      let started = false;
+      try {
+        const result = await runAgentTurn({...turn, root:"/workspace", spawnProcess: (command,args,options) => {
+          const invocation=workerDockerInvocation({workspace:turn.root,image,command,args,credentialEnv:[credential],hostEnv:env,uid,gid,sessionHome:session.home});
+          const dockerArgs=invocation.args.filter((arg,index) => !(index===1 && arg==="--rm"));
+          dockerArgs.splice(1,0,"--name",name);
+          started = true;
+          return spawn(invocation.command,dockerArgs,{...options,cwd:turn.root,env:invocation.env});
+        }});
+        session.sessionId=result.sessionId;
+        return result;
+      } finally {
+        if (started) {
+          try { execFileSync("docker",["rm","--force",name],{env:{PATH:env.PATH ?? "/usr/bin:/bin"},stdio:"ignore",timeout:30000}); }
+          catch { throw new Error("Could not confirm isolated Docker worker removal; reconcile before continuing"); }
+        }
+      }
+    };
+    for (;;) {
+      if (signal?.aborted) return { status: "stopped" };
+      let result;
+      try { result = await runFleetWorker({ repository, workerId, workerAgent, preflight, limits, driver: isolatedDriver, handoff, packet: async ({ job, snapshot }) => [
+        `AI-DLC worker assignment ${job.assignmentId}, attempt ${job.attempt}.`,
+        `Task: ${snapshot.task.title} (${job.taskId}). Item: ${job.itemId}.`,
+        `Only change these owned paths: ${job.ownedPaths.join(", ")}.`,
+        `Base commit: ${job.baseCommit}. Assigned branch: ${job.branch}.`,
+        "Complete the scoped item and report remaining risks. The supervisor handles the Git commit and push.",
+        ...(env.AIDLC_FLEET_CODE_ONLY_RETRY === "1" ? ["This assignment is declared code-only: perform no external side effects beyond the supervisor's Git handoff."] : [])
+      ].join("\n"), onEvent: emit }); }
+      finally { for (const [workspace, entry] of sessions) { rmSync(entry.home,{recursive:true,force:true}); sessions.delete(workspace); } }
+      emit(result);
+      if (once) return result;
+      await pause(pollMs);
+    }
+  }
+  const workerIds = required(env, "AIDLC_FLEET_WORKER_IDS").split(",").map((value) => value.trim()).filter(Boolean);
+  const agent = provider(env.AIDLC_FLEET_AGENT ?? "codex", "AIDLC_FLEET_AGENT");
+  const workerProviders = workerMapping(env, workerIds, agent);
+  const handoff = createLeadGitHandoff({ root, integrationBranch: required(env, "AIDLC_FLEET_INTEGRATION_BRANCH"), remote, agent });
+  const remoteState = join(root, ".agents/aidlc/scripts/remote-state.mjs");
+  if (!existsSync(remoteState)) throw new Error(`Remote lifecycle CLI is missing: ${remoteState}`);
+  const leadTaskFor = (taskId) => ({ ownerId: env.AIDLC_FLEET_LEAD_ID ?? "lead", workerIds, workerProviders, allowCodeOnlyRetry: env.AIDLC_FLEET_CODE_ONLY_RETRY === "1", pollMs, limits, handoff, completeItem: repository.completeItem,
+      packet: async (snapshot, leadEpoch) => {
+        const fleetEnv = { ...env, AIDLC_FLEET_LEAD_EPOCH: String(leadEpoch), AIDLC_FLEET_LEAD_OWNER_TOKEN: repository.leadOwnerToken() };
+        const raw = execFileSync(process.execPath, [remoteState, "phase", "context", taskId], { cwd: root, env: fleetEnv, encoding: "utf8", timeout: 30000, maxBuffer: 2 * 1024 * 1024 });
+        const packet = JSON.parse(raw);
+        if (packet?.ok !== true || typeof packet.result?.content !== "string" || !packet.result.content) throw new Error("Remote phase context is empty or invalid");
+        return `${packet.result.content}\n\nFleet supervisor: canonical nextAction is ${JSON.stringify(snapshot.nextAction)}. Use only remote-state.mjs for lifecycle commands. Never approve a gate.`;
+      },
+      driver: async ({ leadEpoch, prompt, timeoutMs, signal: turnSignal }) => {
+        return runAgentTurn({ agent, root, prompt, timeoutMs, signal: turnSignal, env: { ...env, AIDLC_FLEET_LEAD_EPOCH: String(leadEpoch), AIDLC_FLEET_LEAD_OWNER_TOKEN: repository.leadOwnerToken() }, onEvent: emit });
+      } });
+  const runTask = async (taskId, reservedJobs = []) => runFleetCoordinator({ repository, taskId, ...leadTaskFor(taskId), reservedJobs, onEvent: emit });
+  if (role === "supervisor") {
+    const result = await runFleetSupervisor({ repository, taskId: targetId, ...leadTaskFor(targetId), signal, onEvent: emit, ...(coordinatorOverride ? { coordinator: coordinatorOverride } : {}) });
+    emit(result);
+    return result;
+  }
+  for (;;) {
+    if (signal?.aborted) return { status: "stopped" };
+    if (role === "feature") {
+      const feature = await repository.getFeature({ featureId: targetId });
+      if (!feature) throw new Error(`Unknown feature ${targetId}`);
+      if (feature.integrationBranch !== env.AIDLC_FLEET_INTEGRATION_BRANCH) throw new Error("Feature integration branch differs from configured checkout");
+      const readiness = await repository.featureReady({ featureId: targetId });
+      const ready = readiness.items.filter((item) => item.ready);
+      if (!ready.length && readiness.items.every((item) => !item.blockers.length)) return { status: "complete", featureId: targetId };
+      const results = [];
+      for (const member of ready) {
+        const reservedJobs = (await repository.listAllJobs()).filter((job) => job.taskId !== member.taskId);
+        const result = await runTask(member.taskId, reservedJobs);
+        results.push(result); emit(result);
+        if (result.status === "gate") return { status: "gate", featureId: targetId, results, blockedTaskIds: readiness.items.filter((item) => !item.ready && item.blockers.length).map((item) => item.taskId) };
+      }
+      const stopped = results.some((entry) => ["blocked", "reconcile", "paused", "terminal"].includes(entry.status));
+      const result = { status: !ready.length || stopped ? "blocked" : "active", featureId: targetId, results, blockedTaskIds: readiness.items.filter((member) => !member.ready && member.blockers.length).map((member) => member.taskId) };
+      if (once || result.status === "blocked") return result;
+      await pause(pollMs);
+      continue;
+    }
+    const result = await runTask(targetId);
+    emit(result);
+    if (once || ["terminal", "complete", "blocked", "paused", "reconcile", "gate"].includes(result.status)) return result;
+    await pause(pollMs);
+  }
+}

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

@@ -0,0 +1,100 @@
+import { randomUUID } from "node:crypto";
+
+const idempotency = () => randomUUID();
+
+/** Map the coordination service's versioned MCP tools to the headless runner. */
+export function createFleetRemoteRepository({ callTool, url, token, workspace, root, workerId }) {
+  if (typeof callTool !== "function" || !url || !token || !workspace || !root) throw new Error("Fleet remote requires MCP callTool, URL, token, workspace, and project root");
+  const call = (name, args) => callTool({ url, token, name, args: { workspace, ...args } });
+  let ownerToken;
+  let supervisorToken, supervisorEpoch, supervisorTask;
+  const fleet = () => call("fleet_get", {});
+  const owner = () => { if (!ownerToken) throw new Error("Lead owner token unavailable"); return ownerToken; };
+  const mutation = async (name, args, key, retryRevision = false) => {
+    const mutationKey = key ?? idempotency();
+    for (let attempt = 0; attempt < (retryRevision ? 3 : 1); attempt++) {
+      const current = await fleet();
+      try { return await call(name, { expectedRevision: current.revision, idempotencyKey: mutationKey, ...args }); }
+      catch (error) { if (!retryRevision || error?.code !== "FLEET_CONFLICT" || attempt === 2) throw error; }
+    }
+  };
+  const normalizeJob = (job) => job && ({ ...job, assignmentId: job.id, expiresAt: job.expiresAt });
+  return {
+    leadOwnerToken: owner,
+    claimSupervisor: async ({ taskId, leaseMs, idempotencyKey }) => {
+      if (supervisorToken) throw new Error("Supervisor already claimed by this adapter");
+      const token = randomUUID() + randomUUID();
+      const value = await mutation("supervisor_claim", { taskId, leaseMs, ownerToken: token }, idempotencyKey);
+      const claim = value.fleet.supervisors[taskId];
+      if (!Number.isSafeInteger(claim?.epoch)) throw new Error("Supervisor claim lacks epoch");
+      supervisorToken = token; supervisorEpoch = claim.epoch; supervisorTask = taskId;
+      return claim;
+    },
+    renewSupervisor: async ({ taskId, leaseMs }) => {
+      if (taskId !== supervisorTask || !supervisorToken) throw new Error("Supervisor ownership unavailable");
+      return mutation("supervisor_heartbeat", { taskId, epoch: supervisorEpoch, leaseMs, ownerToken: supervisorToken }, undefined, true);
+    },
+    releaseSupervisor: async ({ taskId }) => {
+      if (taskId !== supervisorTask || !supervisorToken) throw new Error("Supervisor ownership unavailable");
+      const result = await mutation("supervisor_release", { taskId, epoch: supervisorEpoch, ownerToken: supervisorToken });
+      supervisorToken = undefined; supervisorEpoch = undefined; supervisorTask = undefined;
+      return result;
+    },
+    readGateCheckpoint: async ({ taskId }) => call("gate_checkpoint_get", { taskId }),
+    getFeature: async ({ featureId }) => (await fleet()).fleet.features[featureId] ?? null,
+    featureReady: async ({ featureId }) => call("feature_ready", { featureId }),
+    listAllJobs: async () => Object.values((await fleet()).fleet.jobs).map(normalizeJob),
+    readTask: async ({ taskId }) => {
+      const value = await call("task_get", { taskId, clientProjectRoot: root });
+      return { task: value.task, nextAction: value.nextAction, revision: value.revision };
+    },
+    claimLead: async ({ taskId, leaseMs, idempotencyKey, expectedStateRevision, expectedTaskDigest, checkpoint }) => {
+      ownerToken = randomUUID() + randomUUID();
+      if (supervisorToken && supervisorTask !== taskId) throw new Error("Supervisor task mismatch");
+      const binding = supervisorToken ? { supervisorEpoch, supervisorOwnerToken: supervisorToken, expectedStateRevision, expectedTaskDigest, ...(checkpoint?.status === "approved" ? { checkpointSnapshotId: checkpoint.snapshotId, checkpointApprovalRevision: checkpoint.approvalRevision } : {}) } : {};
+      const value = await mutation("run_claim", { taskId, leaseMs, ownerToken, ...binding }, idempotencyKey);
+      return value.fleet.leads[taskId];
+    },
+    renewLead: async ({ taskId, epoch, leaseMs }) => mutation("run_heartbeat", { taskId, epoch, leaseMs, ownerToken: owner() }, undefined, true),
+    releaseLead: async ({ taskId, epoch }) => mutation("run_release", { taskId, epoch, ownerToken: owner() }),
+    listJobs: async ({ taskId }) => Object.values((await fleet()).fleet.jobs).filter((job) => job.taskId === taskId).map(normalizeJob),
+    scheduleJob: async ({ taskId, itemId, workerId: assignedWorker, leadEpoch, baseCommit, branch, ownedPaths, agent, idempotencyKey }) => {
+      const before = await fleet();
+      const prior = Object.values(before.fleet.jobs).filter((job) => job.taskId === taskId && job.itemId === itemId);
+      const attempt = Math.max(0, ...prior.map((job) => job.attempt)) + 1;
+      const jobId = randomUUID();
+      const value = await call("job_schedule", { expectedRevision: before.revision, idempotencyKey, jobId, taskId, itemId, workerId: assignedWorker, attempt, leadEpoch, ownerToken: owner(), baseCommit, branch, ownedPaths, agent });
+      return normalizeJob(value.fleet.jobs[jobId]);
+    },
+    claimJob: async ({ workerId: claimingWorker, leaseMs, idempotencyKey }) => {
+      if (workerId && workerId !== claimingWorker) throw new Error("Worker identity does not match configured credential");
+      const before = await fleet();
+      const ready = Object.values(before.fleet.jobs).find((job) => job.workerId === claimingWorker && job.state === "ready");
+      if (!ready) return null;
+      const value = await call("job_claim", { expectedRevision: before.revision, idempotencyKey, jobId: ready.id, leaseMs });
+      return normalizeJob(value.fleet.jobs[ready.id]);
+    },
+    renewJob: async ({ assignmentId, epoch, leaseMs }) => mutation("job_heartbeat", { jobId: assignmentId, epoch, leaseMs }, undefined, true),
+    checkpointJob: async ({ assignmentId, epoch, sessionId, checkpoint }) => mutation("job_checkpoint", { jobId: assignmentId, epoch, sessionId, checkpoint: JSON.stringify(checkpoint) }, undefined, true),
+    reportJob: async ({ assignmentId, epoch, report, idempotencyKey }) => report.status === "reported"
+      ? mutation("job_report", { jobId: assignmentId, epoch, commitSha: report.commitSha, changedPaths: report.changedPaths, summary: report.summary ?? "" }, idempotencyKey)
+      : mutation("job_abandon", { jobId: assignmentId, epoch, reason: String(report.reason ?? report.status).slice(0, 2000) }, idempotencyKey),
+    reconcileJob: async ({ assignmentId, leadEpoch, decision, idempotencyKey }) => mutation("job_reconcile", { jobId: assignmentId, leadEpoch, ownerToken: owner(), state: decision }, idempotencyKey),
+    recoverJob: async ({ assignmentId, leadEpoch, commitSha, changedPaths, idempotencyKey }) => mutation("job_recover", { jobId: assignmentId, leadEpoch, ownerToken: owner(), commitSha, changedPaths }, idempotencyKey),
+    saveGateSnapshot: async ({ taskId, leadEpoch, expectedRevision, gate, gateView, integrationCommit, idempotencyKey }) => {
+      const value = await call("gate_snapshot_put", { taskId, leadEpoch, leadOwnerToken: owner(), checkpoint: true, expectedRevision, gate, reviewText: gateView, ...(integrationCommit ? { integrationCommit } : {}), idempotencyKey });
+      return { snapshotId: value.id };
+    },
+    completeItem: async ({ taskId, itemId, job, integrated, snapshot, leadEpoch }) => {
+      const task = structuredClone(snapshot.task);
+      const item = task.tasks?.find((entry) => entry.id === itemId);
+      if (!item) throw new Error(`Unknown canonical item ${itemId}`);
+      if (item.status === "done") return { alreadyDone: true };
+      if (!integrated?.integrationCommit || !integrated?.commitSha) throw new Error("Missing verified integration commit");
+      item.status = "done";
+      task.evidence.push({ kind: "diagnostic", result: "pass", source: `Git integration ${integrated.integrationCommit} for ${job.assignmentId}; worker commit ${integrated.commitSha}`, recordedAt: new Date().toISOString() });
+      task.updatedAt = new Date().toISOString();
+      return call("state_apply", { expectedRevision: snapshot.revision, idempotencyKey: `item-${job.assignmentId}`, clientProjectRoot: root, leadEpoch, leadOwnerToken: owner(), command: { type: "upsertTask", taskId, task } });
+    }
+  };
+}

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

@@ -0,0 +1,58 @@
+import { createHash, randomUUID } from "node:crypto";
+import { setTimeout as sleep } from "node:timers/promises";
+import { runFleetCoordinator, validateFleetLimits } from "./loop-fleet.mjs";
+
+const taskDigest = (task) => createHash("sha256").update(JSON.stringify(task)).digest("hex");
+const targets = { G0_confirm: "plan", G1_review: "build", G2_codereview: "wrap" };
+
+/** The service owns the checkpoint and atomically binds each run claim to this
+ * supervisor. An unavailable or ambiguous checkpoint never authorizes work. */
+export async function runFleetSupervisor({ repository, taskId, limits: inputLimits, pollMs = 5000, signal, onEvent = () => {}, coordinator = runFleetCoordinator, ...options }) {
+  const limits = validateFleetLimits(inputLimits);
+  if (!repository || typeof taskId !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(taskId) || !Number.isSafeInteger(pollMs) || pollMs < 1 || pollMs > 300000) throw new Error("Invalid fleet supervisor configuration");
+  for (const name of ["claimSupervisor", "renewSupervisor", "releaseSupervisor", "readGateCheckpoint", "readTask", "claimLead"]) if (typeof repository[name] !== "function") throw new Error(`Fleet supervisor requires ${name}`);
+  await repository.claimSupervisor({ taskId, leaseMs: limits.leaseMs, idempotencyKey: randomUUID() });
+  const controller = new AbortController();
+  const combined = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
+  let failure; let pending = Promise.resolve();
+  const timer = setInterval(() => { pending = pending.then(() => repository.renewSupervisor({ taskId, leaseMs: limits.leaseMs })).catch((error) => { failure = error; controller.abort(error); }); }, limits.heartbeatMs);
+  timer.unref?.();
+  try {
+    while (!combined.aborted) {
+      const snapshot = await repository.readTask({ taskId });
+      const checkpoint = await repository.readGateCheckpoint({ taskId });
+      if (!snapshot?.task || snapshot.task.id !== taskId || !Number.isSafeInteger(snapshot.revision)) throw new Error("Invalid fleet canonical snapshot");
+      const task = snapshot.task;
+      if (task.status === "paused" || task.handoff || ["blocked", "terminal"].includes(snapshot.nextAction?.classification)) return { status: "blocked", taskId, reason: "Task is paused, blocked, or terminal" };
+      if (snapshot.nextAction?.classification === "complete") return { status: "complete", taskId };
+      if (checkpoint?.status === "pending") {
+        if (task.status !== "blocked_on_user" || task.gate !== checkpoint.gate || taskDigest(task) !== checkpoint.taskDigest || snapshot.nextAction?.classification !== "await_user") return { status: "blocked", taskId, reason: "Pending checkpoint does not match canonical gate" };
+        await onEvent({ type: "waiting", taskId, gate: checkpoint.gate, snapshotId: checkpoint.snapshotId });
+        try { await sleep(pollMs, undefined, { signal: combined }); } catch (error) { if (error?.name !== "AbortError") throw error; }
+        continue;
+      }
+      if (checkpoint?.status === "consumed") return { status: "blocked", taskId, reason: "Consumed checkpoint requires reconciliation before restart" };
+      if (checkpoint && checkpoint.status !== "approved") return { status: "blocked", taskId, reason: "Approved checkpoint does not match canonical state" };
+      if (checkpoint) {
+        // A task snapshot older than the atomic approval is a read race between
+        // the two reads, not a mismatch: re-read the canonical task immediately.
+        if (Number.isSafeInteger(checkpoint.approvalRevision) && checkpoint.approvalRevision > snapshot.revision) { await onEvent({ type: "resync", taskId, gate: checkpoint.gate }); continue; }
+        if (task.phase !== targets[checkpoint.gate] || task.status !== "active" || !Number.isSafeInteger(checkpoint.approvalRevision)) return { status: "blocked", taskId, reason: "Approved checkpoint does not match canonical state" };
+      }
+      if (snapshot.nextAction?.classification !== "run_phase" || task.status !== "active") return { status: "blocked", taskId, reason: "Task is not actionable or gate checkpoint is missing" };
+      await repository.renewSupervisor({ taskId, leaseMs: limits.leaseMs });
+      if (combined.aborted) break;
+      const claim = await repository.claimLead({ taskId, leaseMs: limits.leaseMs, expectedStateRevision: snapshot.revision, expectedTaskDigest: taskDigest(task), checkpoint, idempotencyKey: randomUUID() });
+      const result = await coordinator({ ...options, repository, taskId, limits, claimedLead: claim, supervisorSignal: combined, onEvent });
+      if (failure) throw failure;
+      if (result?.status !== "gate") return result;
+      // gate_snapshot_put stores snapshot and checkpoint in one service transaction.
+      await onEvent({ type: "gate", taskId, gate: result.gate, snapshotId: result.snapshotId, gateView: result.gateView });
+    }
+    if (failure) throw new Error(`Supervisor lease renewal failed: ${failure.message}`);
+    return { status: "stopped", taskId };
+  } finally {
+    clearInterval(timer); await pending;
+    await repository.releaseSupervisor({ taskId });
+  }
+}