@felixdotgo/aidlc-kit 0.1.0 → 0.2.0

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

@@ -1,5 +1,9 @@
+/**
+ * Fleet coordination: job reconciliation, coordinator loop, and worker loop
+ * 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";
 
 export const FLEET_LIMITS = Object.freeze({ maxTurns: 12, turnTimeoutMs: 600_000, maxStallTurns: 2, maxWorkers: 4, leaseMs: 300_000, heartbeatMs: 60_000 });
@@ -33,9 +37,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); }
 
@@ -109,13 +119,19 @@ 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");
   if (workerProviders !== undefined && (!workerProviders || typeof workerProviders !== "object" || Array.isArray(workerProviders) || Object.keys(workerProviders).length !== workerIds.length || workerIds.some((workerId) => !isLoopProvider(workerProviders[workerId])) || Object.keys(workerProviders).some((workerId) => !workerIds.includes(workerId)))) throw new Error(`workerProviders must map each configured worker ID to ${LOOP_PROVIDER_LIST}`);
   const limits = validateFleetLimits(inputLimits);
+  // --- Validate limits and normalize inputs ---------------------------------
   integer(pollMs, "pollMs", 300000);
   const pickupTimeoutMs = integer(inputPickupTimeout ?? limits.leaseMs, "pickupTimeoutMs", 3_600_000);
   const readTask = required(repository, "readTask");
@@ -134,15 +150,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");
+        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);
@@ -158,7 +178,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") {
@@ -207,7 +227,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;
           }
         }
@@ -215,7 +235,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 });
@@ -229,11 +253,14 @@ 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);
+  // --- Validate limits and bind adapter methods ------------------------------
   const claimJob = required(repository, "claimJob");
   const renewJob = required(repository, "renewJob");
   const checkpointJob = required(repository, "checkpointJob");
@@ -253,12 +280,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") {
@@ -276,11 +305,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

@@ -1,8 +1,13 @@
+/**
+ * Git handoff helpers: create lead/worker/isolated worktrees, sync the
+ * integration branch, and produce scoped change reports.
+ */
 import { createHash, randomUUID } from "node:crypto";
 import { execFileSync } from "node:child_process";
 import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readlinkSync, rmSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { isLoopProvider } from "./loop-drivers.mjs";
+import { extractCommitMessage } from "./loop-commit-message.mjs";
 import { createWorkerSnapshot, inspectWorkerSnapshot } from "./loop-worker-snapshot.mjs";
 
 const SHA = /^[0-9a-f]{40,64}$/;
@@ -30,9 +35,9 @@ function validPath(value, label = "path") {
 }
 function scopes(input) {
   if (!Array.isArray(input) || input.length === 0) throw new Error("Assignment requires nonempty ownedPaths");
-  return [...new Set(input.map((path) => validPath(path, "owned path")))].sort();
+  return [...new Set(input.map((path) => validPath(path, "owned path").replace(/\/+$/, "")))].filter(Boolean).sort();
 }
-function inScope(path, ownedPaths) { return ownedPaths.some((scope) => path === scope || (scope.endsWith("/") && path.startsWith(scope))); }
+function inScope(path, ownedPaths) { return ownedPaths.some((scope) => path === scope || path.startsWith(`${scope}/`)); }
 function changedPaths(root, base, head) {
   const raw = execFileSync("git", ["diff", "--no-renames", "--name-only", "-z", base, head], { cwd: root, encoding: "buffer", timeout: 30_000, maxBuffer: 4 * 1024 * 1024 });
   return raw.toString("utf8").split("\0").filter(Boolean).map((path) => validPath(path, "changed path")).sort();
@@ -72,10 +77,16 @@ function fetchBranch(root, remote, branch) {
   return git(root, "rev-parse", remoteRef(remote, branch));
 }
 function ancestor(root, base, head) {
-  try { git(root, "merge-base", "--is-ancestor", base, head); return true; } catch { return false; }
+  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) live in
+// the lead checkout but are never part of a handoff or integration.
+const LOOP_OPERATIONAL_PREFIX = ".agents/data/loop/";
 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) => !path.startsWith(LOOP_OPERATIONAL_PREFIX));
+  if (dirty.length) throw new Error("Git worktree must be clean before handoff or integration");
 }
 function normaliseReport(job) {
   const report = job.report ?? job;
@@ -87,6 +98,7 @@ function normaliseReport(job) {
 
 /** The coordinator calls this from its protected integration checkout. */
 export function createLeadGitHandoff({ root: inputRoot, integrationBranch, remote = "origin", agent = "codex" }) {
+  // --- Validate inputs and resolve the integration checkout ------------------
   const root = resolve(inputRoot);
   validBranch(integrationBranch); validId(remote, "remote");
   if (!isLoopProvider(agent)) throw new Error("Invalid worker agent");
@@ -209,7 +221,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);
@@ -217,7 +229,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");
@@ -254,7 +267,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");
@@ -271,8 +284,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}); }
   };

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

@@ -5,8 +5,26 @@ import { join, resolve } from "node:path";
 const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 const digest = (value) => createHash("sha256").update(value).digest("hex");
 
+const firstLine = (text) => {
+  if (typeof text !== "string") return "";
+  return text.split(/\r?\n/).map((line) => line.trim()).find((line) => line.length > 0) ?? "";
+};
+
+const slugify = (text) => {
+  const slug = text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+/, "").slice(0, 127).replace(/-+$/, "");
+  return slug || "loop-task";
+};
+
+/** Derive a memorable task id (kebab-case slug) and a descriptive title from the
+ * requirement's first non-empty line, replacing the opaque `loop-<uuid>` id and
+ * the unhelpful `Loop task <id>` title. */
+export function deriveTaskIdentity(requirement) {
+  const line = firstLine(requirement);
+  return { slug: slugify(line), title: line ? line.slice(0, 256) : "Loop task" };
+}
+
 /** Prepare a durable, idempotent intake without treating it as lifecycle state. */
-export async function prepareLoopIntake({ root, taskId, requirement, authority, createTask, readTask }) {
+export async function prepareLoopIntake({ root, taskId, requirement, authority, createTask, readTask, title }) {
   if (!ID.test(taskId ?? "")) throw new Error("Invalid task ID");
   if (!["local", "fleet"].includes(authority)) throw new Error("Invalid loop authority");
   if (typeof requirement !== "string" || !requirement.trim() || Buffer.byteLength(requirement) > 8192) throw new Error("Requirement must contain 1–8192 bytes");
@@ -39,13 +57,13 @@ export async function prepareLoopIntake({ root, taskId, requirement, authority,
     const existing = lstatSync(requirementPath);
     if (!existing.isFile() || existing.isSymbolicLink() || digest(readFileSync(requirementPath, "utf8")) !== record.requirementHash) throw new Error("Existing requirement does not match intake");
   }
-  const title = `Loop task ${taskId}`;
+  const titleText = typeof title === "string" && title.trim() ? title.trim().slice(0, 256) : deriveTaskIdentity(requirement).title;
   let task = await readTask(taskId);
   if (!task) {
-    try { await createTask({ taskId, title }); }
-    catch (error) { task = await readTask(taskId); if (!task || task.title !== title) throw error; }
+    try { await createTask({ taskId, title: titleText }); }
+    catch (error) { task = await readTask(taskId); if (!task || task.title !== titleText) throw error; }
     task ??= await readTask(taskId);
   }
-  if (!task || task.id !== taskId || task.title !== title) throw new Error("Existing task conflicts with intake");
+  if (!task || task.id !== taskId || task.title !== titleText) throw new Error("Existing task conflicts with intake");
   return { taskId, authority, requirementPath };
 }

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

@@ -4,15 +4,16 @@ import { dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { createHash, randomUUID } from "node:crypto";
 import { tmpdir } from "node:os";
 import { createWorkerSnapshot, inspectWorkerSnapshot } from "./loop-worker-snapshot.mjs";
-import { OPENCODE_CONTAINER_ERROR, workerDockerInvocation } from "./loop-worker-docker.mjs";
+import { workerDockerInvocation } from "./loop-worker-docker.mjs";
 import { isLoopProvider, runAgentTurn } from "./loop-drivers.mjs";
+import { extractCommitMessage } from "./loop-commit-message.mjs";
+import { pathOverlaps } from "./store.mjs";
 import { claimLocalAssignment, heartbeatLocalAssignment, reportLocalAssignment, releaseLocalAssignment } from "./assignment-store.mjs";
 
 const git = (root, ...args) => execFileSync("git", args, { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 30000 });
 const lines = (value) => value.split("\0").filter(Boolean);
 const identifier = (value) => typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(value);
 const safePath = (path) => typeof path === "string" && path.length > 0 && !isAbsolute(path) && !path.includes("\\") && !path.split("/").some((part) => !part || part === "." || part === ".." || part === ".git" || part === ".agents") && !/[\x00-\x1f]/.test(path);
-const overlaps = (a, b) => a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`);
 const scoped = (paths, scopes) => paths.every((path) => safePath(path) && scopes.some((scope) => path === scope || path.startsWith(`${scope}/`)));
 const statusPaths = (root) => {
   // --no-renames yields one entry per path, including both sides of a rename.
@@ -29,7 +30,7 @@ const clean = (root) => { if (statusPaths(root).some((path) => !path.startsWith(
  * state: the caller alone marks canonical items done after inspecting results.
  * A failed batch is deliberately left for reconciliation, not auto-retried.
  */
-export async function runLocalWorkerBatch({ root: inputRoot, taskId, jobs, worktreesRoot: inputWorktreesRoot, docker, timeoutMs = 600000, leaseMs = 300000, maxTurns = 12, maxStallTurns = 2, claim = claimLocalAssignment, heartbeat = heartbeatLocalAssignment, report = reportLocalAssignment, release = releaseLocalAssignment, onEvent = () => {} }) {
+export async function runLocalWorkerBatch({ root: inputRoot, taskId, jobs, worktreesRoot: inputWorktreesRoot, docker, timeoutMs = 600000, leaseMs = 300000, maxTurns = 12, maxStallTurns = 2, claim = claimLocalAssignment, heartbeat = heartbeatLocalAssignment, report = reportLocalAssignment, release = releaseLocalAssignment, onEvent = () => {}, signal } = {}) {
   const root = resolve(inputRoot), worktreesRoot = resolve(inputWorktreesRoot);
   if (!identifier(taskId) || !Array.isArray(jobs) || !jobs.length) throw new Error("Valid task and non-empty jobs are required");
   if (root === worktreesRoot || worktreesRoot.startsWith(`${root}${sep}`)) throw new Error("Worker worktree root must be outside the integration checkout");
@@ -37,28 +38,48 @@ export async function runLocalWorkerBatch({ root: inputRoot, taskId, jobs, workt
   if (!Number.isSafeInteger(maxTurns) || maxTurns < 1 || maxTurns > 1000 || !Number.isSafeInteger(maxStallTurns) || maxStallTurns < 1 || maxStallTurns > 20) throw new Error("Invalid worker turn or stall limit");
   const ids = new Set(), workers = new Set(), scopes = [];
   for (const job of jobs) {
+    if (Array.isArray(job.ownedPaths)) job.ownedPaths = [...new Set(job.ownedPaths.map((path) => (typeof path === "string" ? path.replace(/\/+$/, "") : path)).filter((path) => path))];
     if (!identifier(job.itemId) || !identifier(job.workerId) || !isLoopProvider(job.agent) || typeof job.prompt !== "string" || !job.prompt.trim() || !Array.isArray(job.ownedPaths) || !job.ownedPaths.length || job.ownedPaths.length > 64 || !job.ownedPaths.every(safePath)) throw new Error("Invalid local job");
+    // Last-resort guards: the dispatcher partitions batches (selectBuildBatch),
+    // so plan data should never reach these.
     if (ids.has(job.itemId) || workers.has(job.workerId)) throw new Error("Items and workers must be distinct within a batch");
     ids.add(job.itemId); workers.add(job.workerId);
-    for (const path of job.ownedPaths) { if (scopes.some((prior) => overlaps(path, prior))) throw new Error(`Overlapping assignment scope: ${path}`); scopes.push(path); }
+    for (const path of job.ownedPaths) { if (scopes.some((prior) => pathOverlaps(path, prior))) throw new Error(`Overlapping assignment scope: ${path}`); scopes.push(path); }
   }
-  if (jobs.some((job) => job.agent === "opencode")) throw new Error(OPENCODE_CONTAINER_ERROR);
-  if (process.platform !== "linux" || !docker || typeof docker.image !== "string" || !docker.credentials || typeof docker.credentials !== "object") throw new Error("Linux Docker worker isolation and explicit image and provider credentials are required");
+  const hasImages = docker && typeof docker.images === "object" && !Array.isArray(docker.images);
+  if (process.platform !== "linux" || !docker || (typeof docker.image !== "string" && !hasImages) || !docker.credentials || typeof docker.credentials !== "object") throw new Error("Linux Docker worker isolation and explicit image and provider credentials are required");
+  const resolveImage = (agent) => {
+    const specific = hasImages && typeof docker.images[agent] === "string" && docker.images[agent] ? docker.images[agent] : undefined;
+    return specific ?? docker.image;
+  };
   const uid = process.getuid?.(), gid = process.getgid?.();
   if (!uid || !gid) throw new Error("Docker workers require a non-root host user");
+  const resolvedImages = {};
+  for (const agent of new Set(jobs.map((job) => job.agent))) {
+    const agentImage = resolveImage(agent);
+    if (typeof agentImage !== "string" || !agentImage) throw new Error(`Worker Docker image is required for provider ${agent}`);
+    resolvedImages[agent] = agentImage;
+  }
   for (const job of jobs) {
     const keys = docker.credentials[job.agent];
-    workerDockerInvocation({ workspace: root, image: docker.image, command: job.agent, args: [], credentialEnv: keys, hostEnv: process.env, uid, gid });
+    workerDockerInvocation({ workspace: root, image: resolvedImages[job.agent], command: job.agent, args: [], credentialEnv: keys, hostEnv: process.env, uid, gid });
   }
   const dockerEnv = { PATH: process.env.PATH ?? "/usr/bin:/bin" };
   const dockerCheck = (...args) => execFileSync("docker", args, { env: dockerEnv, stdio: "ignore", timeout: 30000 });
-  let image;
+  // Run each provider CLI through workerDockerInvocation (not a bare `docker run`)
+  // so OpenCode's HOME/XDG roots are redirected to a writable tmpfs. A raw
+  // invocation fails under `--read-only` with `EROFS: mkdir '/home/node/.local'`.
+  const preflightWorkspace = mkdtempSync(join(tmpdir(), "aidlc-worker-preflight-"));
   try {
     dockerCheck("info");
-    image=execFileSync("docker",["image","inspect","--format","{{.Id}}",docker.image],{env:dockerEnv,encoding:"utf8",stdio:["ignore","pipe","ignore"],timeout:30000}).trim();
-    if (!/^sha256:[a-f0-9]{64}$/.test(image)) throw new Error("Docker worker image lacks immutable image ID");
-    for (const agent of new Set(jobs.map((job) => job.agent))) dockerCheck("run", "--rm", "--network", "none", "--read-only", "--user", `${uid}:${gid}`, "--cap-drop", "ALL", "--security-opt", "no-new-privileges", "--entrypoint", agent, image, "--version");
+    for (const [agent, agentImage] of Object.entries(resolvedImages)) {
+      const id=execFileSync("docker",["image","inspect","--format","{{.Id}}",agentImage],{env:dockerEnv,encoding:"utf8",stdio:["ignore","pipe","ignore"],timeout:30000}).trim();
+      if (!/^sha256:[a-f0-9]{64}$/.test(id)) throw new Error("Docker worker image lacks immutable image ID");
+      const invocation = workerDockerInvocation({ workspace: preflightWorkspace, image: agentImage, command: agent, args: ["--version"], credentialEnv: docker.credentials[agent], hostEnv: process.env, uid, gid });
+      execFileSync(invocation.command, invocation.args, { env: invocation.env, stdio: "ignore", timeout: 30000 });
+    }
   } catch { throw new Error("Docker engine, image, or provider CLI preflight failed"); }
+  finally { rmSync(preflightWorkspace, { recursive: true, force: true }); }
   clean(root);
   const base = git(root, "rev-parse", "HEAD").trim();
   const initialBranch = git(root, "symbolic-ref", "--short", "HEAD").trim();
@@ -85,6 +106,10 @@ export async function runLocalWorkerBatch({ root: inputRoot, taskId, jobs, workt
   const execute = async ({ job, assignment, workspace, snapshot, baseline, branch }) => {
     let renewalError;
     const controller = new AbortController();
+    // An external cancel (daemon shutdown stage 2) aborts every worker turn the
+    // same way a lost lease does; the batch then fails and is not integrated.
+    const onCancel = () => { renewalError ??= new Error("Worker batch cancelled by daemon shutdown"); controller.abort(); };
+    if (signal?.aborted) onCancel(); else signal?.addEventListener("abort", onCancel, { once: true });
     const timer = setInterval(() => { Promise.resolve().then(() => heartbeat(root, taskId, assignment.id, leaseMs)).catch((error) => { renewalError = error; controller.abort(); }); }, Math.max(500, Math.floor(leaseMs / 3)));
     try {
       const home=mkdtempSync(join(tmpdir(), "aidlc-local-home-")); chmodSync(home,0o700);
@@ -94,10 +119,10 @@ export async function runLocalWorkerBatch({ root: inputRoot, taskId, jobs, workt
           if (renewalError || controller.signal.aborted) throw renewalError ?? new Error("Worker lease lost");
           const containerName = `aidlc-worker-${randomUUID()}`;
           const spawnProcess = (command, args, options) => {
-            const invocation = workerDockerInvocation({ workspace: snapshot, image, command, args, credentialEnv: docker.credentials[job.agent], hostEnv: process.env, uid, gid, containerName, sessionHome:home });
+            const invocation = workerDockerInvocation({ workspace: snapshot, image: resolvedImages[job.agent], command, args, credentialEnv: docker.credentials[job.agent], hostEnv: process.env, uid, gid, containerName, sessionHome:home });
             return spawn(invocation.command, invocation.args, { ...options, cwd: snapshot, env: invocation.env, shell: false });
           };
-          try { result = await runAgentTurn({ agent: job.agent, root: "/workspace", sessionId, spawnProcess, prompt: `${job.prompt}\n\nOnly modify assigned paths: ${job.ownedPaths.join(", ")}. Do not modify AI-DLC lifecycle state or approve gates. End with AI-DLC-ITEM-COMPLETE on its own line.`, timeoutMs, signal: controller.signal, onSessionId: async (id) => { await heartbeat(root, taskId, assignment.id, leaseMs, id); } }); }
+          try { result = await runAgentTurn({ agent: job.agent, root: "/workspace", sessionId, spawnProcess, prompt: `${job.prompt}\n\nOnly modify assigned paths: ${job.ownedPaths.join(", ")}. Do not modify AI-DLC lifecycle state or approve gates. End with a Conventional Commits message on its own line as AI-DLC-COMMIT: type(scope): subject (for example AI-DLC-COMMIT: docs(ui): add web UI improvement proposal), followed by AI-DLC-ITEM-COMPLETE on its own line.`, timeoutMs, signal: controller.signal, onSessionId: async (id) => { await heartbeat(root, taskId, assignment.id, leaseMs, id); } }); }
           finally {
             try { dockerCheck("rm", "-f", containerName); }
             catch {
@@ -135,12 +160,15 @@ export async function runLocalWorkerBatch({ root: inputRoot, taskId, jobs, workt
       // Fold any commits made by the agent into one scoped assignment commit.
       git(workspace, "reset", "--soft", base);
       git(workspace, "add", "-A", "--", ...changed);
-      if (git(workspace, "diff", "--cached", "--name-only").trim()) git(workspace, "-c", "user.name=AI-DLC worker", "-c", "user.email=aidlc-worker@localhost", "commit", "-m", `AI-DLC ${taskId}/${job.itemId}`);
+      if (git(workspace, "diff", "--cached", "--name-only").trim()) {
+        const message = extractCommitMessage(result?.resultText, { itemId: job.itemId, ownedPaths: job.ownedPaths });
+        git(workspace, "-c", "user.name=AI-DLC worker", "-c", "user.email=aidlc-worker@localhost", "commit", "-m", message);
+      }
       const commit = git(workspace, "rev-parse", "HEAD").trim(), committed = commitPaths(workspace, base, commit);
       if (commit === base || !committed.length || !scoped(committed, job.ownedPaths)) throw new Error("Worker commit is outside assignment scope");
       await report(root, taskId, assignment.id, { commit, changedPaths: committed, checkpoint: `provider=${job.agent}` });
       return { assignmentId: assignment.id, itemId: job.itemId, workerId: job.workerId, agent: job.agent, baseCommit: base, branch, commit, changedPaths: committed, workspace };
-    } finally { clearInterval(timer); }
+    } finally { clearInterval(timer); signal?.removeEventListener("abort", onCancel); }
   };
   const results = await Promise.allSettled(prepared.map(execute));
   const failure = results.find((result) => result.status === "rejected");

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

@@ -1,3 +1,7 @@
+/**
+ * Local loop runtime: record management, checkpointing, turn orchestration,
+ * and pause/resume handling for a single lead.
+ */
 import { createHash, randomUUID } from "node:crypto";
 import { execFileSync } from "node:child_process";
 import { closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
@@ -6,7 +10,7 @@ import { acquireLoopLease, assertLoopPath, readLiveLease } from "./loop-lease.mj
 import { isLoopProvider, LOOP_PROVIDER_LIST } from "./loop-drivers.mjs";
 
 export const DEFAULT_LIMITS = Object.freeze({ maxTurns: 12, turnTimeoutMs: 600000, maxStallTurns: 2 });
-const states = new Set(["running", "gate", "paused", "blocked", "terminal", "complete"]);
+const states = new Set(["running", "gate", "paused", "blocked", "terminal", "complete", "stopped"]);
 const hash = (value) => createHash("sha256").update(value).digest("hex");
 const iso = () => new Date().toISOString();
 const bounded = (value, name, max) => { const n = Number(value); if (!Number.isSafeInteger(n) || n < 1 || n > max) throw new Error(`${name} must be an integer from 1 to ${max}`); return n; };
@@ -148,10 +152,33 @@ export const classifyAction = (action) => {
 };
 
 function approvalCount(task) { return task.evidence.filter((item) => item.kind === "approval" && item.result === "pass").length; }
+function 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 outputStop(record, action, gateView) { return { taskId: record.taskId, runId: record.runId, status: record.status, iteration: record.iteration, sessionId: record.sessionId, stopReason: record.stopReason, nextAction: action, ...(gateView ? { gateView } : {}) }; }
 
-export async function runLoop({ root: rootInput, taskId, agent, mode = "run", limits: limitInput, driver, onEvent = () => {}, preflight = false, precondition }) {
+/**
+ * `signal` requests a graceful stop at the next turn boundary; `cancelSignal`
+ * additionally cancels the in-flight agent turn. Either way the run ends as
+ * `stopped` (the canonical task is NOT paused) and a later resume continues
+ * from fresh canonical nextAction. A failure observed while stopping is a
+ * shutdown side effect (a terminal Ctrl-C also reaches the agent child), not a
+ * transport failure, so it never pauses the task.
+ */
+export async function runLoop({ root: rootInput, taskId, agent, mode = "run", limits: limitInput, driver, dispatchBuild, onEvent = () => {}, preflight = false, precondition, signal: stopSignal, cancelSignal }) {
+  const stopping = () => Boolean(stopSignal?.aborted || cancelSignal?.aborted);
   const root = validateRoot(rootInput);
+  // --- Validate mode and load/create the loop record -------------------------
   let record = readLoopRecord(root, taskId);
   if (mode === "run") {
     if (record) throw new Error(`Loop record already exists for ${taskId}; use resume`);
@@ -181,13 +208,22 @@ export async function runLoop({ root: rootInput, taskId, agent, mode = "run", li
       envelope(root, "state.mjs", ["task", "status", taskId, "--status", "active"]);
       record.pausedByLoop = false;
       current = readCanonical(root, taskId);
+    } else if (mode === "resume" && record.pausedByLoop && current.task.status === "active") {
+      // A human (CLI or dashboard) already re-activated the task: the loop no
+      // longer owns that pause, so a later human pause must not be auto-undone.
+      record.pausedByLoop = false;
     }
     const initial = fingerprint(root, current.task, current.action);
     if (mode === "resume" && record.lastFingerprint && record.lastFingerprint !== initial.digest) onEvent({ type: "context_changed", message: "Canonical task context changed since the last checkpoint; continuing from fresh nextAction", previousCheckpointAt: record.checkpoint?.capturedAt ?? null });
     record.lastFingerprint = initial.digest;
     record.checkpoint = checkpoint(current.task, current.action, initial.tree, record.iteration);
     record.status = "running"; record.stopReason = null; record.updatedAt = iso(); writeLoopRecord(root, record);
-    for (;;) {
+    // --- Main turn loop --------------------------------------------------------
+    // maxTurns bounds one runLoop invocation (a supervised run), not the task's
+    // lifetime: record.iteration stays a cumulative observability counter, so a
+    // long multi-gate task is not permanently re-paused on every resume.
+    let runTurns = 0;
+  for (;;) {
       const kind = classifyAction(current.action);
       if (kind !== "run_phase") {
         record.status = kind === "await_user" ? "gate" : kind;
@@ -196,39 +232,79 @@ export async function runLoop({ root: rootInput, taskId, agent, mode = "run", li
         const gateView = kind === "await_user" ? cli(root, "gate-view.mjs", [taskId]).trim() : undefined;
         return outputStop(record, current.action, gateView);
       }
-      if (record.iteration >= limits.maxTurns) return pause("turn limit reached");
+      if (stopping()) return stop(cancelSignal?.aborted ? "daemon cancelled the run" : "daemon shutdown");
+      if (runTurns >= limits.maxTurns) return pause("turn limit reached");
+      if (dispatchBuild && current.task.phase === "build" && current.task.tasks.some((item) => item.status === "todo" || item.status === "in_progress")) {
+        try {
+          await dispatchBuild({ root, taskId, task: current.task, action: current.action, record });
+        } catch (error) {
+          if (stopping()) return stop("daemon shutdown interrupted build dispatch");
+          return pause(`build dispatch failure: ${error.message}`);
+        }
+        const refreshed = readCanonical(root, taskId);
+        const signal = fingerprint(root, refreshed.task, refreshed.action);
+        record.iteration += 1; runTurns += 1;
+        record.stallTurns = signal.digest === record.lastFingerprint ? record.stallTurns + 1 : 0;
+        record.lastFingerprint = signal.digest;
+        record.checkpoint = checkpoint(refreshed.task, refreshed.action, signal.tree, record.iteration);
+        record.updatedAt = iso(); writeLoopRecord(root, record);
+        current = refreshed;
+        if (stopping()) continue; // the loop top records `stopped` (or the reached stop) instead of a stall pause
+        if (classifyAction(current.action) === "run_phase" && record.stallTurns >= limits.maxStallTurns) return pause(`${record.stallTurns} consecutive turns without observable progress`);
+        continue;
+      }
       let prompt;
       try {
         const packet = JSON.parse(cli(root, "context.mjs", [taskId, "--phase", current.action.phase, ...(current.action.itemId ? ["--item", current.action.itemId] : []), "--format", "json"]));
         if (typeof packet?.content !== "string" || !packet.content.trim()) throw new Error("Context packet was empty or invalid");
         prompt = packet.content;
       } catch {
+        // A terminal Ctrl-C also kills the context.mjs child: that is a shutdown, not a broken packet.
+        if (stopping()) return stop("daemon shutdown interrupted context generation");
         // No driver has started for this turn, so it is safe to resume after repairing context.
         // Do not persist arbitrary subprocess output or malformed context in the stop reason.
         return pause("context packet generation or validation failed; inspect context.mjs and resume after repair");
       }
+      const feedback = pendingFeedback(current.task);
+      if (feedback.length) {
+        prompt = `Human feedback (revise the current review artifact accordingly, then re-present the gate):\n${feedback.map((text) => `- ${text}`).join("\n")}\n\n${prompt}`;
+      }
       const beforeApprovals = approvalCount(current.task);
+      onEvent({ type: "turn_start", taskId, iteration: record.iteration, phase: current.action.phase, agent: record.agent });
       let observedId = record.sessionId;
       try {
-        const result = await driver({ agent: record.agent, root, sessionId: record.sessionId ?? undefined, prompt: `${prompt}\n\nLoop supervisor: complete the current authorized phase or item. Use canonical lifecycle commands for evidence and gates. Never approve a human gate. Stop at a gate and report progress.`, timeoutMs: limits.turnTimeoutMs, onSessionId: (id) => { if (typeof id !== "string" || !id) throw new Error("Invalid agent session id"); observedId = id; record.sessionId = id; record.updatedAt = iso(); writeLoopRecord(root, record); }, onEvent: (event) => { onEvent(event); if (event?.type === "lifecycle_command") { const observed = readCanonical(root, taskId); const signal = fingerprint(root, observed.task, observed.action); record.checkpoint = checkpoint(observed.task, observed.action, signal.tree, record.iteration); record.updatedAt = iso(); writeLoopRecord(root, record); } } });
+        const result = await driver({ agent: record.agent, root, sessionId: record.sessionId ?? undefined, prompt: `${prompt}\n\nLoop supervisor: complete the current authorized phase or item. Use canonical lifecycle commands for evidence and gates. Never approve a human gate. Stop at a gate and report progress.`, timeoutMs: limits.turnTimeoutMs, ...(cancelSignal ? { signal: cancelSignal } : {}), onSessionId: (id) => { if (typeof id !== "string" || !id) throw new Error("Invalid agent session id"); observedId = id; record.sessionId = id; record.updatedAt = iso(); writeLoopRecord(root, record); }, onEvent: (event) => { onEvent(event); if (event?.type === "lifecycle_command") { const observed = readCanonical(root, taskId); const signal = fingerprint(root, observed.task, observed.action); record.checkpoint = checkpoint(observed.task, observed.action, signal.tree, record.iteration); record.updatedAt = iso(); writeLoopRecord(root, record); } } });
         if (!observedId && result?.sessionId) { observedId = result.sessionId; record.sessionId = observedId; record.updatedAt = iso(); writeLoopRecord(root, record); }
         if (!observedId) throw new Error("Agent turn ended without a resumable session id");
       } catch (error) {
         current = readCanonical(root, taskId);
         if (classifyAction(current.action) === "await_user") continue;
+        if (stopping()) return stop(cancelSignal?.aborted ? "daemon cancelled the in-flight turn" : "daemon shutdown interrupted the turn");
         return pause(`agent transport failure: ${error.message}`);
       }
+      onEvent({ type: "turn_end", taskId, iteration: record.iteration });
       const refreshed = readCanonical(root, taskId);
       if (approvalCount(refreshed.task) !== beforeApprovals) return pause("Approval evidence changed during an agent turn");
       const signal = fingerprint(root, refreshed.task, refreshed.action);
-      record.iteration += 1;
+      record.iteration += 1; runTurns += 1;
       record.stallTurns = signal.digest === record.lastFingerprint ? record.stallTurns + 1 : 0;
       record.lastFingerprint = signal.digest;
       record.checkpoint = checkpoint(refreshed.task, refreshed.action, signal.tree, record.iteration);
       record.updatedAt = iso(); writeLoopRecord(root, record);
       current = refreshed;
+      if (stopping()) continue; // the loop top records `stopped` (or the reached stop) instead of a stall pause
       if (classifyAction(current.action) === "run_phase" && record.stallTurns >= limits.maxStallTurns) return pause(`${record.stallTurns} consecutive turns without observable progress`);
     }
+    function stop(reason) {
+      const stopped = readCanonical(root, taskId);
+      const signal = fingerprint(root, stopped.task, stopped.action);
+      record.status = "stopped"; record.stopReason = reason;
+      record.lastFingerprint = signal.digest;
+      record.checkpoint = checkpoint(stopped.task, stopped.action, signal.tree, record.iteration, reason);
+      record.updatedAt = iso(); writeLoopRecord(root, record);
+      onEvent({ type: "loop_stopped", taskId, reason });
+      return outputStop(record, stopped.action);
+    }
     function pause(reason) {
       const fresh = readCanonical(root, taskId);
       record.status = "paused"; record.stopReason = reason;