@felixdotgo/aidlc-kit 0.1.1 → 0.3.0

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

@@ -1,4 +1,4 @@
-import { chmodSync, existsSync, mkdtempSync, rmSync } from "node:fs";
+import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { execFileSync, spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
@@ -8,11 +8,33 @@ import { runFleetCoordinator, runFleetWorker, validateFleetLimits } from "./loop
 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";
+import { workerDockerInvocation, workerCredentialKeys } from "./loop-worker-docker.mjs";
+import { openWorkerLog } from "./loop-worker-log.mjs";
+import { defaultWorkerImageTag, ensureWorkerImage, validWorkerImageTag } from "./loop-worker-image.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));
+/** Sleep `ms`, resolving early once any given signal aborts. */
+const pause = (ms, ...signals) => new Promise((resolve) => {
+  const live = signals.filter(Boolean);
+  if (live.some((signal) => signal.aborted)) return resolve();
+  const done = () => { clearTimeout(timer); for (const signal of live) signal.removeEventListener("abort", done); resolve(); };
+  const timer = setTimeout(done, ms);
+  for (const signal of live) signal.addEventListener("abort", done, { once: true });
+});
 const provider = (value, name) => { if (!isLoopProvider(value)) throw new Error(`${name} must be ${LOOP_PROVIDER_LIST}`); return value; };
+const pendingFeedback = (task) => {
+  const evidence = Array.isArray(task?.evidence) ? task.evidence : [];
+  const pending = [];
+  for (let i = 0; i < evidence.length; i++) {
+    const entry = evidence[i];
+    if (entry?.kind !== "diagnostic" || typeof entry.detail !== "string") continue;
+    const match = entry.detail.match(/^Cancelled gate wait at (G0_confirm|G1_review|G2_codereview): /);
+    if (!match) continue;
+    const approvedAfter = evidence.slice(i + 1).some((later) => later?.kind === "approval" && later.result === "pass" && later.gate === match[1]);
+    if (!approvedAfter) pending.push(entry.detail);
+  }
+  return pending;
+};
 function workerMapping(env, workerIds, defaultAgent) {
   if (!env.AIDLC_FLEET_WORKER_PROVIDERS) return Object.fromEntries(workerIds.map((id) => [id, defaultAgent]));
   let mapping;
@@ -20,9 +42,46 @@ function workerMapping(env, workerIds, defaultAgent) {
   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;
 }
+/** This worker's provider: AIDLC_FLEET_WORKER_AGENT, else its entry in
+ * AIDLC_FLEET_WORKER_PROVIDERS (keyed by worker ID), else AIDLC_FLEET_AGENT
+ * (the lead's provider — only a last resort, so a copied lead env cannot
+ * override this worker's own mapping), else undefined. */
+function workerProvider(env, workerId) {
+  if (env.AIDLC_FLEET_WORKER_AGENT !== undefined) return provider(env.AIDLC_FLEET_WORKER_AGENT, "AIDLC_FLEET_WORKER_AGENT");
+  if (env.AIDLC_FLEET_WORKER_PROVIDERS) {
+    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)) throw new Error("AIDLC_FLEET_WORKER_PROVIDERS must be a JSON object");
+    if (Object.hasOwn(mapping, workerId)) return provider(mapping[workerId], `AIDLC_FLEET_WORKER_PROVIDERS["${workerId}"]`);
+  }
+  return env.AIDLC_FLEET_AGENT === undefined ? undefined : provider(env.AIDLC_FLEET_AGENT, "AIDLC_FLEET_AGENT");
+}
 
-/** 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 } = {}) {
+/** Worker image tag: explicit AIDLC_WORKER_DOCKER_IMAGE, else the project's
+ * `.agents/config.json` `loop.workerImage[provider]`, else the default tag
+ * (built from the shipped Dockerfile when missing). */
+function workerImageTag({ env, root, agent, onEvent }) {
+  const requested = env.AIDLC_WORKER_DOCKER_IMAGE;
+  if (typeof requested === "string" && requested.trim()) return requested;
+  if (!agent) throw new Error("AIDLC_WORKER_DOCKER_IMAGE is required when the worker provider is unknown; set AIDLC_FLEET_WORKER_AGENT (or this worker's AIDLC_FLEET_WORKER_PROVIDERS entry) to use the default worker image, or build one with `aidlc-kit loop worker-image --provider <provider>` and set the env var");
+  const configPath = join(root, ".agents", "config.json");
+  let configured;
+  if (existsSync(configPath)) {
+    let config;
+    try { config = JSON.parse(readFileSync(configPath, "utf8")); } catch { throw new Error(`Invalid project config: ${configPath}`); }
+    configured = config?.loop?.workerImage?.[agent];
+    if (configured !== undefined && !validWorkerImageTag(configured)) throw new Error(`Invalid loop.workerImage.${agent} in ${configPath}`);
+  }
+  const image = configured ?? defaultWorkerImageTag(agent);
+  return ensureWorkerImage({ root, provider: agent, image, env, onEvent });
+}
+
+/** Package-local entrypoint. The service wrapper supplies its MCP HTTP client.
+ * `signal` stops after the current turn; `cancelSignal` also aborts the
+ * in-flight agent turn (result status `stopped`). `onEvent(event)` receives
+ * every emitted event object instead of `out(JSON.stringify(event))`.
+ * `untilStop` applies to role `supervisor` only (see runFleetSupervisor). */
+export async function runFleetCli(argv, { callTool, env = process.env, out = console.log, onEvent, signal, cancelSignal, untilStop = false, 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");
@@ -44,23 +103,21 @@ export async function runFleetCli(argv, { callTool, env = process.env, out = con
   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));
+  const emit = typeof onEvent === "function" ? (event) => onEvent(event) : (event) => out(JSON.stringify(event));
+  const stopRequested = () => Boolean(signal?.aborted || cancelSignal?.aborted);
   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");
+    const workerAgent = workerProvider(env, workerId);
+    const requestedImage = workerImageTag({ env, root, agent: workerAgent, onEvent: emit });
     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});
+        const invocation = workerDockerInvocation({workspace:empty,image,command:agent,args:["--version"],credentialEnv:workerCredentialKeys(agent, env),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()}`;
@@ -77,32 +134,45 @@ export async function runFleetCli(argv, { callTool, env = process.env, out = con
     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 dropSession = (key, current) => { current.log?.close(); rmSync(current.home,{recursive:true,force:true}); sessions.delete(key); };
+    const cleanupSession = (workspace) => { const current=sessions.get(workspace.root); if(current) dropSession(workspace.root, current); };
+    // Same container record and raw output tee as the local loop, written under
+    // this worker checkout's .agents/data/tasks/<task>/runtime/workers (the
+    // index entry carries this host's name). Best-effort: reported once, never fatal.
+    const openLog = (job) => {
+      const diagnostic = (error) => emit({ type: "diagnostic", taskId: job.taskId, itemId: job.itemId, message: `Worker log unavailable for assignment ${job.assignmentId}: ${error instanceof Error ? error.message : String(error)}` });
+      try { return openWorkerLog({ root, taskId: job.taskId, assignmentId: job.assignmentId, itemId: job.itemId, workerId, agent: job.agent, mode: "fleet", onError: diagnostic }); }
+      catch (error) { diagnostic(error); return null; }
+    };
     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});
+        const labels = { "aidlc.task": job.taskId, "aidlc.item": job.itemId, "aidlc.worker": workerId, "aidlc.assignment": job.assignmentId };
+        sessions.set(workspace.root,{home,agent:job.agent,assignmentId:job.assignmentId,attempt:job.attempt,epoch:job.epoch,workerId,image,sessionId:null,labels,log:openLog(job),turns:0});
         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 credentialEnv = workerCredentialKeys(turn.agent, env);
       const name = `aidlc-worker-${randomUUID()}`;
       let started = false;
+      session.turns += 1;
+      session.log?.turnStart(name, session.turns);
       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 result = await runAgentTurn({...turn, root:"/workspace", env, spawnProcess: (command,args,options) => {
+          const invocation=workerDockerInvocation({workspace:turn.root,image,command,args,credentialEnv,hostEnv:env,uid,gid,sessionHome:session.home,labels:session.labels});
           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});
+          const child = spawn(invocation.command,dockerArgs,{...options,cwd:turn.root,env:invocation.env});
+          if (session.log) { session.log.tee(child); child.once("close", (code) => session.log.turnEnd(code)); }
+          return child;
         }});
         session.sessionId=result.sessionId;
         return result;
@@ -114,20 +184,20 @@ export async function runFleetCli(argv, { callTool, env = process.env, out = con
       }
     };
     for (;;) {
-      if (signal?.aborted) return { status: "stopped" };
+      if (stopRequested()) return { status: "stopped" };
       let result;
-      try { result = await runFleetWorker({ repository, workerId, workerAgent, preflight, limits, driver: isolatedDriver, handoff, packet: async ({ job, snapshot }) => [
+      try { result = await runFleetWorker({ repository, workerId, workerAgent, preflight, limits, driver: isolatedDriver, handoff, cancelSignal, 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.",
+        "Complete the scoped item and report remaining risks. The supervisor handles the Git commit and push. End the final answer 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.",
         ...(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); } }
+      finally { for (const [workspace, entry] of sessions) dropSession(workspace, entry); }
       emit(result);
-      if (once) return result;
-      await pause(pollMs);
+      if (once || result.status === "stopped") return result;
+      await pause(pollMs, signal, cancelSignal);
     }
   }
   const workerIds = required(env, "AIDLC_FLEET_WORKER_IDS").split(",").map((value) => value.trim()).filter(Boolean);
@@ -142,19 +212,21 @@ export async function runFleetCli(argv, { callTool, env = process.env, out = con
         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.`;
+        const feedback = pendingFeedback(snapshot.task);
+        const feedbackBlock = feedback.length ? `Human feedback (revise the current review artifact accordingly, then re-present the gate):\n${feedback.map((text) => `- ${text}`).join("\n")}\n\n` : "";
+        return `${feedbackBlock}${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 });
+  const runTask = async (taskId, reservedJobs = []) => runFleetCoordinator({ repository, taskId, ...leadTaskFor(taskId), reservedJobs, stopSignal: signal, cancelSignal, onEvent: emit });
   if (role === "supervisor") {
-    const result = await runFleetSupervisor({ repository, taskId: targetId, ...leadTaskFor(targetId), signal, onEvent: emit, ...(coordinatorOverride ? { coordinator: coordinatorOverride } : {}) });
+    const result = await runFleetSupervisor({ repository, taskId: targetId, ...leadTaskFor(targetId), signal, cancelSignal, untilStop, onEvent: emit, ...(coordinatorOverride ? { coordinator: coordinatorOverride } : {}) });
     emit(result);
     return result;
   }
   for (;;) {
-    if (signal?.aborted) return { status: "stopped" };
+    if (stopRequested()) return { status: "stopped" };
     if (role === "feature") {
       const feature = await repository.getFeature({ featureId: targetId });
       if (!feature) throw new Error(`Unknown feature ${targetId}`);
@@ -167,17 +239,18 @@ export async function runFleetCli(argv, { callTool, env = process.env, out = con
         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 === "stopped") return { status: "stopped", featureId: targetId, results };
         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);
+      await pause(pollMs, signal, cancelSignal);
       continue;
     }
     const result = await runTask(targetId);
     emit(result);
-    if (once || ["terminal", "complete", "blocked", "paused", "reconcile", "gate"].includes(result.status)) return result;
-    await pause(pollMs);
+    if (once || ["terminal", "complete", "blocked", "paused", "reconcile", "gate", "stopped"].includes(result.status)) return result;
+    await pause(pollMs, signal, cancelSignal);
   }
 }

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

@@ -1,11 +1,20 @@
 import { randomUUID } from "node:crypto";
+import { explainFleetConflict } from "./loop-holder.mjs";
 
 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 } });
+  // A FleetConflict keeps its code/current for retry logic; its message gains
+  // a lease/claim explanation and the inspect command (original kept in parentheses).
+  const call = async (name, args) => {
+    try { return await callTool({ url, token, name, args: { workspace, ...args } }); }
+    catch (error) {
+      if (error?.code === "FLEET_CONFLICT" && typeof error.message === "string") error.message = explainFleetConflict(error.message);
+      throw error;
+    }
+  };
   let ownerToken;
   let supervisorToken, supervisorEpoch, supervisorTask;
   const fleet = () => call("fleet_get", {});
@@ -44,6 +53,13 @@ export function createFleetRemoteRepository({ callTool, url, token, workspace, r
     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),
+    /** Every canonical task in the workspace (unordered), for daemon task discovery. */
+    listTasks: async () => {
+      const value = await call("state_get", {});
+      const tasks = value?.state?.tasks;
+      if (!tasks || typeof tasks !== "object" || Array.isArray(tasks)) throw new Error("Invalid remote workspace state");
+      return Object.values(tasks);
+    },
     readTask: async ({ taskId }) => {
       const value = await call("task_get", { taskId, clientProjectRoot: root });
       return { task: value.task, nextAction: value.nextAction, revision: value.revision };

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

@@ -1,19 +1,30 @@
 import { createHash, randomUUID } from "node:crypto";
 import { setTimeout as sleep } from "node:timers/promises";
+import { explainFleetConflict } from "./loop-holder.mjs";
 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 }) {
+ * supervisor. An unavailable or ambiguous checkpoint never authorizes work.
+ *
+ * `signal` stops at the next turn boundary; `cancelSignal` also aborts the
+ * in-flight lead turn. Both end as `{ status: "stopped" }`.
+ *
+ * `untilStop: true` (daemon mode) never polls a human gate: a newly published
+ * gate returns `{ status: "gate", taskId, gate, snapshotId, gateView }` and an
+ * already pending checkpoint returns `{ status: "waiting", taskId, gate,
+ * snapshotId }`. The supervisor lease is released either way; the service
+ * accepts the reviewer approval against the pending checkpoint, and a later
+ * supervisor resumes from the `approved` checkpoint. */
+export async function runFleetSupervisor({ repository, taskId, limits: inputLimits, pollMs = 5000, signal, cancelSignal, untilStop = false, 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;
+  const combined = AbortSignal.any([signal, cancelSignal, controller.signal].filter(Boolean));
   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?.();
@@ -28,12 +39,17 @@ export async function runFleetSupervisor({ repository, taskId, limits: inputLimi
       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 });
+        if (untilStop) return { status: "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) {
+      if (checkpoint?.status === "rejected") {
+        if (task.status !== "active" || task.phase !== checkpoint.phase || task.gate !== checkpoint.gate || snapshot.nextAction?.classification !== "run_phase") return { status: "blocked", taskId, reason: "Rejected checkpoint does not match canonical state" };
+      } else if (checkpoint && checkpoint.status !== "approved") {
+        return { status: "blocked", taskId, reason: "Approved checkpoint does not match canonical state" };
+      }
+      if (checkpoint?.status === "approved") {
         // 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; }
@@ -43,13 +59,14 @@ export async function runFleetSupervisor({ repository, taskId, limits: inputLimi
       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 });
+      const result = await coordinator({ ...options, repository, taskId, limits, claimedLead: claim, supervisorSignal: controller.signal, stopSignal: signal, cancelSignal, 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 (untilStop) return { status: "gate", taskId, gate: result.gate, snapshotId: result.snapshotId, gateView: result.gateView };
     }
-    if (failure) throw new Error(`Supervisor lease renewal failed: ${failure.message}`);
+    if (failure) throw new Error(`Supervisor lease renewal failed: ${explainFleetConflict(failure.message)}`);
     return { status: "stopped", taskId };
   } finally {
     clearInterval(timer); await pending;

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

@@ -3,8 +3,9 @@
  * for multi-host AI-DLC execution.
  */
 import { createHash, randomUUID } from "node:crypto";
-import { readyTaskItems, formatGateView } from "./store.mjs";
+import { readyTaskItems, formatGateView, pathsOverlap } from "./store.mjs";
 import { isLoopProvider, LOOP_PROVIDER_LIST } from "./loop-drivers.mjs";
+import { explainFleetConflict, LEASES_COMMAND } from "./loop-holder.mjs";
 
 export const FLEET_LIMITS = Object.freeze({ maxTurns: 12, turnTimeoutMs: 600_000, maxStallTurns: 2, maxWorkers: 4, leaseMs: 300_000, heartbeatMs: 60_000 });
 const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
@@ -37,9 +38,15 @@ function readyItems(task) {
   const ready = new Set(readyTaskItems(task).ready);
   return items.filter((item) => item.status === "todo" && ready.has(item.id));
 }
-const overlaps = (left, right) => left === right || (left.endsWith("/") && right.startsWith(left)) || (right.endsWith("/") && left.startsWith(right));
-const pathsOverlap = (left = [], right = []) => left.some((a) => right.some((b) => overlaps(a, b)));
-const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Sleep `ms`, resolving early (never rejecting) once any given signal aborts. */
+const wait = (ms, ...signals) => new Promise((resolve) => {
+  const live = signals.filter(Boolean);
+  if (live.some((signal) => signal.aborted)) return resolve();
+  const done = () => { clearTimeout(timer); for (const signal of live) signal.removeEventListener("abort", done); resolve(); };
+  const timer = setTimeout(done, ms);
+  for (const signal of live) signal.addEventListener("abort", done, { once: true });
+});
+const anySignal = (...signals) => { const live = signals.filter(Boolean); return live.length === 1 ? live[0] : AbortSignal.any(live); };
 
 function key(...parts) { return digest(parts); }
 
@@ -105,7 +112,7 @@ async function withHeartbeat(renew, intervalMs, work) {
   try {
     const result = await work(abort.signal);
     await pending;
-    if (failure) throw new Error(`Fleet lease renewal failed: ${failure.message}`);
+    if (failure) throw new Error(`Fleet lease renewal failed: ${explainFleetConflict(failure.message)}`);
     return result;
   } finally { clearInterval(timer); await pending; }
 }
@@ -113,8 +120,13 @@ async function withHeartbeat(renew, intervalMs, work) {
 /**
  * One fenced coordinator invocation. The repository is the remote authority;
  * no local lifecycle file or PID lease is consulted in fleet mode.
+ *
+ * `supervisorSignal` reports a lost supervisor lease (aborts the turn and
+ * fails). `stopSignal` requests a graceful stop at the next turn boundary;
+ * `cancelSignal` additionally aborts the in-flight lead turn. Both end as
+ * `{ status: "stopped" }` without changing canonical task state.
  */
-export async function runFleetCoordinator({ repository, taskId, ownerId = randomUUID(), workerIds = [], workerProviders, reservedJobs = [], allowCodeOnlyRetry = false, limits: inputLimits, pollMs = 5000, pickupTimeoutMs: inputPickupTimeout, packet, driver, gateView, handoff, completeItem, claimedLead, supervisorSignal, onEvent = () => {} }) {
+export async function runFleetCoordinator({ repository, taskId, ownerId = randomUUID(), workerIds = [], workerProviders, reservedJobs = [], allowCodeOnlyRetry = false, limits: inputLimits, pollMs = 5000, pickupTimeoutMs: inputPickupTimeout, packet, driver, gateView, handoff, completeItem, claimedLead, supervisorSignal, stopSignal, cancelSignal, onEvent = () => {} }) {
   assertId(taskId, "task ID"); assertId(ownerId, "owner ID");
   if (!Array.isArray(workerIds) || new Set(workerIds).size !== workerIds.length) throw new Error("workerIds must be distinct IDs");
   for (const workerId of workerIds) assertId(workerId, "worker ID");
@@ -139,15 +151,19 @@ export async function runFleetCoordinator({ repository, taskId, ownerId = random
   const readySeen = new Map();
   try {
     return await withHeartbeat(() => renewLead({ taskId, ownerId, epoch, leaseMs: limits.leaseMs }), limits.heartbeatMs, async (leaseSignal) => {
-      const signal = supervisorSignal ? AbortSignal.any([leaseSignal, supervisorSignal]) : leaseSignal;
+      const leaseLost = anySignal(leaseSignal, supervisorSignal);
+      const signal = anySignal(leaseLost, cancelSignal);
+      const stopping = () => Boolean(stopSignal?.aborted || cancelSignal?.aborted);
+      const stopped = (reason) => ({ status: "stopped", taskId, reason, revision: snapshot.revision });
       for (;;) {
-        if (signal.aborted) throw new Error("Lead lease renewal failed");
+        if (leaseLost.aborted) throw new Error(`Lead lease renewal failed: the lead lease (run_claim, lead epoch ${epoch}) for ${taskId} could not be renewed or the supervisor lease was lost; another lead may have taken over or the coordination service is unreachable. Inspect: ${LEASES_COMMAND} ${taskId}`);
+        if (stopping()) return stopped(cancelSignal?.aborted ? "cancel requested" : "stop requested");
         if (Date.now() - startedAt >= limits.maxTurns * limits.turnTimeoutMs) return { status: "paused", taskId, reason: "coordinator wall-time limit reached" };
         snapshot = validateSnapshot(await readTask({ taskId }), taskId);
         const kind = actionKind(snapshot.nextAction);
         if (kind === "await_user") {
           const reconciled = await reconcileFleetJobs({ repository, taskId, leadEpoch: epoch, snapshot, handoff, allowCodeOnlyRetry, quiesceMs: limits.turnTimeoutMs + limits.heartbeatMs + 1000 });
-          if (reconciled.pending.length && reconciled.pending.every((entry) => entry.waitUntil)) { await wait(pollMs); continue; }
+          if (reconciled.pending.length && reconciled.pending.every((entry) => entry.waitUntil)) { await wait(pollMs, signal, stopSignal); continue; }
           if (reconciled.pending.length) return { status: "reconcile", taskId, revision: snapshot.revision, pending: reconciled.pending };
           const gate = snapshot.nextAction.gate;
           const baseReview = await (gateView ?? ((value) => formatGateView(value.task, [], "markdown")))(snapshot);
@@ -163,7 +179,7 @@ export async function runFleetCoordinator({ repository, taskId, ownerId = random
         const before = digest({ revision: snapshot.revision, action: snapshot.nextAction });
         if (kind === "dispatch" || (kind === "run_phase" && snapshot.task.phase === "build")) {
           const reconciled = await reconcileFleetJobs({ repository, taskId, leadEpoch: epoch, snapshot, handoff, allowCodeOnlyRetry, quiesceMs: limits.turnTimeoutMs + limits.heartbeatMs + 1000 });
-          if (reconciled.pending.length && reconciled.pending.every((entry) => entry.waitUntil)) { await wait(pollMs); continue; }
+          if (reconciled.pending.length && reconciled.pending.every((entry) => entry.waitUntil)) { await wait(pollMs, signal, stopSignal); continue; }
           if (reconciled.pending.length) {
             const verified = reconciled.pending.filter((entry) => entry.artifact?.valid);
             if (verified.length && typeof handoff?.integrate === "function" && typeof completeItem === "function") {
@@ -212,7 +228,7 @@ export async function runFleetCoordinator({ repository, taskId, ownerId = random
               }
             }
             onEvent({ type: "jobs_active", taskId, assignments: active.map((job) => job.assignmentId) });
-            await wait(pollMs);
+            await wait(pollMs, signal, stopSignal);
             continue;
           }
         }
@@ -220,7 +236,11 @@ export async function runFleetCoordinator({ repository, taskId, ownerId = random
         if (typeof packet !== "function" || typeof driver !== "function") throw new Error("Fleet lead requires packet and driver adapters");
         const prompt = await packet(snapshot, epoch);
         if (typeof prompt !== "string" || !prompt) throw new Error("Empty fleet lead packet");
-        await driver({ taskId, snapshot, leadEpoch: epoch, prompt, timeoutMs: limits.turnTimeoutMs, signal });
+        try { await driver({ taskId, snapshot, leadEpoch: epoch, prompt, timeoutMs: limits.turnTimeoutMs, signal }); }
+        catch (error) {
+          if (!leaseLost.aborted && cancelSignal?.aborted) return stopped("cancelled the in-flight lead turn");
+          throw error;
+        }
         turns++;
         const after = validateSnapshot(await readTask({ taskId }), taskId);
         const nextSignal = digest({ revision: after.revision, action: after.nextAction });
@@ -234,8 +254,10 @@ export async function runFleetCoordinator({ repository, taskId, ownerId = random
   }
 }
 
-/** A worker claims one attempt, persists its exact CLI session, and reports a Git artifact. */
-export async function runFleetWorker({ repository, workerId = randomUUID(), workerAgent, preflight, limits: inputLimits, driver, packet, handoff, onEvent = () => {} }) {
+/** A worker claims one attempt, persists its exact CLI session, and reports a Git artifact.
+ * `cancelSignal` aborts the in-flight worker turn; the attempt is then abandoned
+ * (service state `uncertain`, recoverable by the lead) and the result is `stopped`. */
+export async function runFleetWorker({ repository, workerId = randomUUID(), workerAgent, preflight, limits: inputLimits, driver, packet, handoff, cancelSignal, onEvent = () => {} }) {
   assertId(workerId, "worker ID");
   if (workerAgent !== undefined && !isLoopProvider(workerAgent)) throw new Error(`workerAgent must be ${LOOP_PROVIDER_LIST}`);
   const limits = validateFleetLimits(inputLimits);
@@ -259,12 +281,14 @@ export async function runFleetWorker({ repository, workerId = randomUUID(), work
   let turns = 0, stalls = 0;
   const report = async (outcome) => reportJob({ ...identity, report: outcome, idempotencyKey: key("job-report", job.assignmentId, job.attempt, job.epoch, outcome.status, outcome.commitSha ?? "") });
   return withHeartbeat(() => renewJob({ ...identity, leaseMs: limits.leaseMs }), limits.heartbeatMs, async (signal) => {
+    const cancelled = async () => { await report({ status: "uncertain", reason: "worker turn cancelled", sessionId }); return { status: "stopped", assignmentId: job.assignmentId }; };
     if (typeof driver !== "function" || typeof packet !== "function" || typeof handoff?.prepare !== "function" || typeof handoff?.observe !== "function" || typeof handoff?.finish !== "function") throw new Error("Worker requires driver, packet, and Git handoff adapters");
     const workspace = await handoff.prepare(job);
     if (!workspace?.root) throw new Error("Git handoff did not supply a worker root");
     let lastObservation = null;
     for (;;) {
       if (signal.aborted) throw new Error("Job lease renewal failed");
+      if (cancelSignal?.aborted) return cancelled();
       const snapshot = validateSnapshot(await readTask({ taskId: job.taskId }), job.taskId);
       const item = snapshot.task.tasks?.find((candidate) => candidate.id === job.itemId);
       if (!item || item.status === "done") {
@@ -282,11 +306,13 @@ export async function runFleetWorker({ repository, workerId = randomUUID(), work
       }
       const prompt = await packet({ job, snapshot, workspace, turns });
       if (typeof prompt !== "string" || !prompt) throw new Error("Empty worker packet");
-      const result = await driver({ agent: job.agent, root: workspace.root, sessionId: sessionId ?? undefined, prompt: `${prompt}\n\nWorker scope: modify only assigned paths. Do not mutate AI-DLC lifecycle state or approve any gate. When the scoped implementation is ready for commit, end the final answer with AI-DLC-ITEM-COMPLETE on its own line.`, timeoutMs: limits.turnTimeoutMs, signal, onSessionId: async (id) => {
+      let result;
+      try { result = await driver({ agent: job.agent, root: workspace.root, sessionId: sessionId ?? undefined, prompt: `${prompt}\n\nWorker scope: modify only assigned paths. Do not mutate AI-DLC lifecycle state or approve any gate. When the scoped implementation is ready for commit, end the final answer 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.`, timeoutMs: limits.turnTimeoutMs, signal: anySignal(signal, cancelSignal), onSessionId: async (id) => {
         if (typeof id !== "string" || !id) throw new Error("Invalid worker session ID");
         if (sessionId && sessionId !== id) throw new Error("Worker session changed during the same assignment");
         sessionId = id;
-      }, onEvent });
+      }, onEvent }); }
+      catch (error) { if (!signal.aborted && cancelSignal?.aborted) return cancelled(); throw error; }
       if (result?.sessionId && sessionId && result.sessionId !== sessionId) throw new Error("Worker session changed during the same assignment");
       if (result?.sessionId && !sessionId) {
         sessionId = result.sessionId;

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

@@ -7,6 +7,7 @@ import { execFileSync } from "node:child_process";
 import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readlinkSync, rmSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { isLoopProvider } from "./loop-drivers.mjs";
+import { extractCommitMessage } from "./loop-commit-message.mjs";
 import { createWorkerSnapshot, inspectWorkerSnapshot } from "./loop-worker-snapshot.mjs";
 
 const SHA = /^[0-9a-f]{40,64}$/;
@@ -78,8 +79,20 @@ function fetchBranch(root, remote, branch) {
 function ancestor(root, base, head) {
   try { git(root, "merge-base", "--is-ancestor", base, head); return true; } catch { return false; } /* intentional: non-git/non-worktree is treated as not clean */
 }
+// Host-local loop operational files (daemon lock/log, UI event sidecar) and
+// per-task runtime data (worker container index and logs) live in the lead
+// checkout but are never part of a handoff or integration.
+const LOOP_OPERATIONAL_PREFIX = ".agents/data/loop/";
+const TASK_RUNTIME_PATTERN = /^\.agents\/data\/tasks\/[^/]+\/runtime\//;
+/** True for repository-relative paths the loop writes operationally
+ * (`.agents/data/loop/` and `.agents/data/tasks/<id>/runtime/`); such paths are
+ * ignored by clean checks and working-tree change snapshots. */
+export const isLoopOperationalPath = (path) => typeof path === "string" && (path.startsWith(LOOP_OPERATIONAL_PREFIX) || TASK_RUNTIME_PATTERN.test(path));
 function assertClean(root) {
-  if (git(root, "status", "--porcelain=v1", "--untracked-files=all")) throw new Error("Git worktree must be clean before handoff or integration");
+  // Not via git(): its trim() would eat the leading status column of the first row.
+  const status = execFileSync("git", ["status", "--porcelain=v1", "-z", "--no-renames", "--untracked-files=all"], { cwd: root, encoding: "utf8", timeout: 30_000, maxBuffer: 4 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] });
+  const dirty = status.split("\0").filter(Boolean).map((row) => row.slice(3)).filter((path) => !isLoopOperationalPath(path));
+  if (dirty.length) throw new Error("Git worktree must be clean before handoff or integration");
 }
 function normaliseReport(job) {
   const report = job.report ?? job;
@@ -214,7 +227,7 @@ export function createWorkerGitHandoff({ root: inputRoot, worktreesRoot: inputWo
       const done = typeof result?.resultText === "string" && result.resultText.split(/\r?\n/).some((line) => line.trim() === "AI-DLC-ITEM-COMPLETE");
       return { done, fingerprint: worktreeFingerprint(workspace.root, changed) };
     },
-    async finish({ job, workspace }) {
+    async finish({ job, workspace, result }) {
       const branch = validBranch(job.branch);
       if (git(workspace.root, "symbolic-ref", "--short", "HEAD") !== branch) throw new Error("Worker switched away from assigned branch");
       const ownedPaths = scopes(job.ownedPaths);
@@ -222,7 +235,8 @@ export function createWorkerGitHandoff({ root: inputRoot, worktreesRoot: inputWo
       checkScope(dirty, ownedPaths);
       if (dirty.length) {
         git(workspace.root, "add", "-A", "--", ...dirty);
-        git(workspace.root, "-c", "user.name=AI-DLC worker", "-c", "user.email=aidlc-worker@localhost", "commit", "-m", `AI-DLC ${validId(job.taskId, "task ID")}/${validId(job.itemId, "item ID")} ${validId(job.assignmentId, "assignment ID")}`);
+        const message = extractCommitMessage(result?.resultText, { itemId: job.itemId, ownedPaths });
+        git(workspace.root, "-c", "user.name=AI-DLC worker", "-c", "user.email=aidlc-worker@localhost", "commit", "-m", message);
       }
       const commitSha = git(workspace.root, "rev-parse", "HEAD");
       const base = validSha(job.baseCommit, "base commit");
@@ -259,7 +273,7 @@ export function createIsolatedWorkerGitHandoff(options) {
       const done = typeof result?.resultText === "string" && result.resultText.split(/\r?\n/).some((line) => line.trim() === "AI-DLC-ITEM-COMPLETE");
       return {done, fingerprint};
     },
-    async finish({job, workspace}) {
+    async finish({job, workspace, result}) {
       const changed=inspectWorkerSnapshot(workspace.root, workspace.baseline, job.ownedPaths);
       if (!changed.length) throw new Error("Worker produced no changes");
       if (worktreePaths(workspace.checkout.root).length || git(workspace.checkout.root,"rev-parse","HEAD") !== job.baseCommit) throw new Error("Host checkout changed during worker run");
@@ -276,8 +290,8 @@ export function createIsolatedWorkerGitHandoff(options) {
         if (!existsSync(source)) { rmSync(target,{force:true}); continue; }
         copyFileSync(source,target); chmodSync(target,lstatSync(source).mode & 0o777);
       }
-      const result=await host.finish({job,workspace:workspace.checkout});
-      rmSync(workspace.root,{recursive:true,force:true}); return result;
+      const report=await host.finish({job,workspace:workspace.checkout,result});
+      rmSync(workspace.root,{recursive:true,force:true}); return report;
     },
     async discard({workspace}) { rmSync(workspace.root,{recursive:true,force:true}); return host.discard({workspace:workspace.checkout}); }
   };