@felixdotgo/aidlc-kit 0.1.1 → 0.3.0

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

@@ -0,0 +1,268 @@
+// `leases` diagnostic: who holds what, until when, what it blocks, and how to
+// clear it. Read-only except `--clear-stale`, which removes only stale or old
+// corrupt lease/lock/guard files after re-reading them under the holder guard.
+// It never removes a live holder, never releases a claim, and never touches the
+// lifecycle state lock (that lock reclaims itself).
+import { lstatSync, readdirSync, unlinkSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { ASSIGNMENT_STATE_LABELS, assignmentReadPath, assignmentRemedy, showLocalAssignments } from "./assignment-store.mjs";
+import { isRegularFile, legacyTaskRuntimePath, taskRuntimePath } from "./task-runtime.mjs";
+import { CLEAR_STALE_COMMAND, clearStaleHolder, explainHolder, formatAge, GUARD_STALE_MS, LEASE_TTL_MS, LOCK_TTL_MS, pidAlive, readGuard, readHolder } from "./loop-holder.mjs";
+
+export const LEASES_SCHEMA_VERSION = 1;
+const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const STATE_LOCK_STALE_MS = 30000;
+
+const loopDir = (root) => join(root, ".agents", "data", "loop");
+const assignmentsDir = (root) => join(loopDir(root), "assignments");
+const tasksDir = (root) => join(root, ".agents", "data", "tasks");
+const isDirectory = (path) => { try { const stat = lstatSync(path); return stat.isDirectory() && !stat.isSymbolicLink(); } catch { return false; } };
+const listDir = (dir) => { try { return readdirSync(dir).sort(); } catch (error) { if (error?.code === "ENOENT") return []; throw error; } };
+const isFile = (path) => { try { const stat = lstatSync(path); return stat.isFile() && !stat.isSymbolicLink(); } catch { return false; } };
+
+function holderFields(entry) {
+  const holder = entry.holder;
+  if (!holder) return { holder: null, heartbeatAt: null, expiresAt: null };
+  const since = holder.startedAt ?? holder.createdAt ?? null;
+  return {
+    holder: { pid: holder.pid, host: holder.host ?? null, command: holder.command ?? null, purpose: holder.purpose ?? null, activity: holder.activity ?? null, startedAt: typeof since === "number" ? new Date(since).toISOString() : since, version: entry.version },
+    heartbeatAt: holder.heartbeatAt ?? null,
+    expiresAt: holder.expiresAt ?? null,
+  };
+}
+
+function remedyFor(entry, liveRemedy) {
+  if (entry.state === "live") return liveRemedy;
+  return explainHolder(entry).remedy;
+}
+
+function holderEntry({ category, kind, scope, entry, blocks, liveRemedy, ttlMs, clearable = true }) {
+  const effectiveBlocks = entry.state === "stale" ? `nothing while stale (the next acquire reclaims it); it was held for: ${blocks}` : blocks;
+  return { category, kind, scope, path: entry.path, state: entry.state, reason: entry.reason, ...holderFields(entry), blocks: effectiveBlocks, remedy: remedyFor(entry, liveRemedy), clearable: clearable && entry.reclaimable, ttlMs };
+}
+
+function guardEntry(path, scope, category = "guard") {
+  const guard = readGuard(path);
+  if (!guard) return null;
+  return {
+    category, kind: "guard", scope, path, state: guard.live ? "live" : "stale",
+    reason: guard.live ? `held for ${formatAge(guard.ageMs)}` : `abandoned (${formatAge(guard.ageMs)} old)`,
+    holder: null, heartbeatAt: null, expiresAt: null,
+    blocks: "concurrent reclaim/heartbeat/release of the guarded holder (held for milliseconds)",
+    remedy: guard.live ? `Short-lived; it is treated as abandoned after ${formatAge(GUARD_STALE_MS)}` : `Removed automatically by the next acquire, or run: ${CLEAR_STALE_COMMAND}`,
+    clearable: !guard.live, ttlMs: GUARD_STALE_MS,
+  };
+}
+
+function stateLockEntry(root) {
+  const path = join(root, ".agents", "data", "state", ".aidlc-state.lock");
+  const entry = readHolder(path, { ttlMs: STATE_LOCK_STALE_MS });
+  if (entry.state === "absent") return null;
+  // The state lock reclaims itself when its pid is gone AND it is >=30s old.
+  let state = entry.state;
+  if (entry.holder) state = pidAlive(entry.holder.pid) || entry.ageMs < STATE_LOCK_STALE_MS ? "live" : "stale";
+  return {
+    category: "state-lock", kind: "lock", scope: "lifecycle-state", path, state, reason: entry.holder ? (pidAlive(entry.holder.pid) ? "held" : `pid ${entry.holder.pid} is not running`) : entry.reason,
+    ...holderFields(entry),
+    blocks: "every lifecycle mutation (state.mjs) waits up to 5s for it",
+    remedy: state === "live" ? "Short-lived; wait for the lifecycle command to finish" : "Reclaimed automatically by the next lifecycle command (pid gone and at least 30s old); leases never removes it",
+    clearable: false, ttlMs: STATE_LOCK_STALE_MS,
+  };
+}
+
+function taskLeaseBlocks(taskId, entry) {
+  const turn = entry.version === 2 ? entry.holder?.activity === "turn" : entry.version === 1;
+  return turn
+    ? `another loop runner/supervisor for ${taskId}, and state.mjs gate approve ${taskId} (a turn is running)`
+    : `another loop runner/supervisor for ${taskId} (gate approval is allowed while it waits)`;
+}
+
+function claimState(effective) {
+  if (effective === "leased" || effective === "reported") return "live";
+  if (effective === "expired" || effective === "uncertain") return "expired";
+  return effective;
+}
+
+function collectClaims(root, taskId) {
+  const out = [];
+  let value, recordPath;
+  try { recordPath = assignmentReadPath(root, taskId); value = showLocalAssignments(root, taskId); }
+  catch (error) {
+    return [{ category: "claim", kind: "claim", scope: `assignments:${taskId}`, path: recordPath ?? join(assignmentsDir(root), `${taskId}.json`), state: "corrupt", reason: error.message, holder: null, heartbeatAt: null, expiresAt: null, blocks: `every assignment command for ${taskId}`, remedy: "Inspect the file by hand; leases never edits assignment records", clearable: false, ttlMs: null }];
+  }
+  for (const assignment of value.assignments) {
+    if (!["leased", "reported", "uncertain"].includes(assignment.state)) continue;
+    const effective = assignment.effectiveState;
+    out.push({
+      category: "claim", kind: "claim", scope: `item:${taskId}/${assignment.itemId}`, path: recordPath,
+      state: claimState(effective), reason: ASSIGNMENT_STATE_LABELS[effective] ?? effective,
+      holder: { worker: assignment.workerId, assignmentId: assignment.id, attempt: assignment.attempt, ownedPaths: assignment.ownedPaths, persistedState: assignment.state, effectiveState: effective },
+      heartbeatAt: assignment.updatedAt ?? null, expiresAt: assignment.leaseExpiresAt,
+      blocks: `item ${assignment.itemId} and paths ${assignment.ownedPaths.join(", ")} for other workers`,
+      remedy: assignmentRemedy(taskId, assignment),
+      clearable: false, ttlMs: null,
+    });
+  }
+  return out;
+}
+
+/** Collect every local holder under `.agents/data` (optionally one task). */
+export function collectLocalLeases(rootInput, { taskId } = {}) {
+  const root = resolve(rootInput);
+  if (taskId !== undefined && !ID.test(taskId)) throw new Error(`Invalid task id: ${taskId}`);
+  const entries = [];
+  const wanted = (id) => taskId === undefined || id === taskId;
+  const daemonPath = join(loopDir(root), "daemon.lock");
+  if (taskId === undefined) {
+    const daemon = readHolder(daemonPath, { ttlMs: LEASE_TTL_MS });
+    if (daemon.state !== "absent") entries.push(holderEntry({ category: "daemon", kind: "lease", scope: "daemon", entry: daemon, blocks: "a second `loop start` (one daemon per project root)", liveRemedy: `Stop that \`loop start\` (Ctrl-C) or wait; if the process is gone the lease expires after ${formatAge(LEASE_TTL_MS)}`, ttlMs: LEASE_TTL_MS }));
+    const guard = guardEntry(`${daemonPath}.guard`, "daemon");
+    if (guard) entries.push(guard);
+  }
+  for (const name of listDir(loopDir(root))) {
+    const path = join(loopDir(root), name);
+    if (!isFile(path)) continue;
+    let match;
+    if ((match = /^(.+)\.lease$/.exec(name)) && !name.endsWith(".supervisor.lease") && ID.test(match[1]) && wanted(match[1])) {
+      const id = match[1];
+      const entry = readHolder(path, { ttlMs: LEASE_TTL_MS });
+      entries.push(holderEntry({ category: "task", kind: "lease", scope: `task:${id}`, entry, blocks: taskLeaseBlocks(id, entry), liveRemedy: `Stop the owning loop process or wait for it to reach a gate; if the process is gone the lease expires after ${formatAge(LEASE_TTL_MS)}`, ttlMs: LEASE_TTL_MS }));
+    } else if ((match = /^(.+)\.supervisor\.lease$/.exec(name)) && ID.test(match[1]) && wanted(match[1])) {
+      const id = match[1];
+      const entry = readHolder(path, { ttlMs: LEASE_TTL_MS });
+      entries.push(holderEntry({ category: "legacy", kind: "lease", scope: `task:${id} (v1 supervisor)`, entry, blocks: `the new loop for ${id} (left by a previous aidlc-kit version)`, liveRemedy: "A loop from the previous version is still running: stop the loop daemon and any `loop start`", ttlMs: LEASE_TTL_MS }));
+    } else if ((match = /^(.+)\.supervisor\.guard$/.exec(name)) && ID.test(match[1]) && wanted(match[1])) {
+      const guard = guardEntry(path, `task:${match[1]} (v1 supervisor)`, "legacy");
+      if (guard) entries.push(guard);
+    } else if ((match = /^(.+)\.lease\.guard$/.exec(name)) && ID.test(match[1]) && wanted(match[1])) {
+      const guard = guardEntry(path, `task:${match[1]}`);
+      if (guard) entries.push(guard);
+    }
+  }
+  const taskIds = new Set();
+  const assignmentLock = (path, id) => {
+    const entry = readHolder(path, { ttlMs: LOCK_TTL_MS });
+    entries.push(holderEntry({ category: "assignment-lock", kind: "lock", scope: `assignments:${id}`, entry, blocks: `assignment claim/report/reconcile/release for ${id} (they wait up to 5s)`, liveRemedy: "Short-lived; wait for the assignment command to finish", ttlMs: LOCK_TTL_MS }));
+  };
+  // Current layout: .agents/data/tasks/<id>/runtime/{assignments.json,assignments.lock}.
+  for (const id of listDir(tasksDir(root))) {
+    if (!ID.test(id) || !wanted(id) || !isDirectory(join(tasksDir(root), id))) continue;
+    let lock, guard, record;
+    try { lock = taskRuntimePath(root, id, "assignments.lock"); guard = `${lock}.guard`; record = taskRuntimePath(root, id, "assignments.json"); } catch { continue; }
+    if (isFile(lock)) assignmentLock(lock, id);
+    const guardFound = isFile(guard) ? guardEntry(guard, `assignments:${id}`) : null;
+    if (guardFound) entries.push(guardFound);
+    if (isFile(record)) taskIds.add(id);
+  }
+  // Pre-runtime layout (.agents/data/loop/assignments/<id>.*): a record still
+  // here is read as that task's claims until it is migrated; its lock files
+  // are short-lived leftovers that `--clear-stale` may remove.
+  for (const name of listDir(assignmentsDir(root))) {
+    const path = join(assignmentsDir(root), name);
+    if (!isFile(path)) continue;
+    let match;
+    if ((match = /^(.+)\.lock$/.exec(name)) && ID.test(match[1]) && wanted(match[1])) assignmentLock(path, match[1]);
+    else if ((match = /^(.+)\.lock\.guard$/.exec(name)) && ID.test(match[1]) && wanted(match[1])) {
+      const guard = guardEntry(path, `assignments:${match[1]}`);
+      if (guard) entries.push(guard);
+    } else if ((match = /^(.+)\.json$/.exec(name)) && ID.test(match[1]) && wanted(match[1])) {
+      if (taskIds.has(match[1])) entries.push({ category: "legacy", kind: "leftover", scope: `assignments:${match[1]} (pre-runtime copy)`, path, state: "stale", reason: "superseded by the runtime/ record; left by a previous aidlc-kit version", holder: null, heartbeatAt: null, expiresAt: null, blocks: "nothing (the runtime/ record is authoritative)", remedy: "Inspect and delete by hand, or run: node .agents/aidlc/scripts/loop-entry.mjs migrate-data --dry-run --json", clearable: false, ttlMs: null });
+      else taskIds.add(match[1]);
+    }
+  }
+  for (const id of taskIds) entries.push(...collectClaims(root, id));
+  const stateLock = stateLockEntry(root);
+  if (stateLock) entries.push(stateLock);
+  return entries;
+}
+
+/** Read-only fleet view from `fleet_get`: supervisor lease, lead lease
+ * (run_claim) and job claims. Supervisor epoch is shown only when it differs
+ * from the lead epoch. */
+export function summarizeFleet(fleet, { taskId, now = Date.now() } = {}) {
+  const live = (expiresAt) => (Date.parse(expiresAt ?? "") > now ? "live" : "expired");
+  const tasks = new Set([...Object.keys(fleet?.leads ?? {}), ...Object.keys(fleet?.supervisors ?? {})].filter((id) => taskId === undefined || id === taskId));
+  const entries = [];
+  for (const id of [...tasks].sort()) {
+    const lead = fleet.leads?.[id];
+    const supervisor = fleet.supervisors?.[id];
+    if (lead) entries.push({ category: "fleet-lead", kind: "lease", scope: `task:${id}`, state: live(lead.expiresAt), holder: { actor: lead.actor ?? null, leadEpoch: lead.epoch, ...(supervisor && supervisor.epoch !== lead.epoch ? { supervisorEpoch: supervisor.epoch } : {}) }, expiresAt: lead.expiresAt ?? null, blocks: `another lead for ${id}`, remedy: live(lead.expiresAt) === "live" ? "Stop the `loop start` on the lead machine or wait for the lease to expire (5 minutes without heartbeat)" : "Expired: the next `loop start` takes over" });
+    else if (supervisor) entries.push({ category: "fleet-supervisor", kind: "lease", scope: `task:${id}`, state: live(supervisor.expiresAt), holder: { actor: supervisor.actor ?? null, supervisorEpoch: supervisor.epoch }, expiresAt: supervisor.expiresAt ?? null, blocks: `another supervisor for ${id}`, remedy: "Stop the other `loop start` or wait for the lease to expire" });
+  }
+  for (const job of Object.values(fleet?.jobs ?? {}).sort((a, b) => String(a.id).localeCompare(String(b.id)))) {
+    if (taskId !== undefined && job.taskId !== taskId) continue;
+    if (!["leased", "uncertain", "reported"].includes(job.state)) continue;
+    const state = job.state === "leased" ? live(job.expiresAt) : job.state === "uncertain" ? "expired" : "live";
+    entries.push({ category: "fleet-job", kind: "claim", scope: `item:${job.taskId}/${job.itemId}`, state, holder: { worker: job.workerId, jobId: job.id, jobEpoch: job.epoch ?? null, attempt: job.attempt ?? null, persistedState: job.state }, expiresAt: job.expiresAt ?? null, blocks: `item ${job.itemId} for other workers`, remedy: state === "live" ? "Wait for the worker to report" : "The lead reconciles it on its next run" });
+  }
+  return entries;
+}
+
+/** Remove stale/old-corrupt entries from `collectLocalLeases`; returns the
+ * removed paths. Live holders, claims, and the state lock are never touched. */
+export function clearStaleLeases(entries) {
+  const cleared = [];
+  for (const entry of entries) {
+    if (!entry.clearable || entry.state === "live") continue;
+    if (entry.kind === "guard") {
+      const observed = readGuard(entry.path);
+      const again = observed && !observed.live ? readGuard(entry.path) : null;
+      if (again && !again.live && again.token === observed.token) { try { unlinkSync(entry.path); cleared.push(entry.path); } catch (error) { if (error?.code !== "ENOENT") throw error; } }
+      continue;
+    }
+    if (!["lease", "lock"].includes(entry.kind) || !["daemon", "task", "assignment-lock", "legacy"].includes(entry.category)) continue;
+    if (clearStaleHolder(entry.path, { ttlMs: entry.ttlMs ?? LEASE_TTL_MS })) cleared.push(entry.path);
+  }
+  return cleared;
+}
+
+/** Run the diagnostic. `fleetReader` (optional) returns the `fleet_get` result. */
+export async function runLeases({ root: rootInput, taskId, clearStale = false, fleetReader, now = Date.now() } = {}) {
+  const root = resolve(rootInput);
+  let local = collectLocalLeases(root, { taskId });
+  let cleared = [];
+  if (clearStale) { cleared = clearStaleLeases(local); local = collectLocalLeases(root, { taskId }); }
+  let fleet = null;
+  if (fleetReader) {
+    try { const current = await fleetReader(); fleet = { revision: current?.revision ?? null, entries: summarizeFleet(current?.fleet, { taskId, now }), error: null }; }
+    catch (error) { fleet = { revision: null, entries: [], error: error.message }; }
+  }
+  return { schemaVersion: LEASES_SCHEMA_VERSION, root, taskId: taskId ?? null, generatedAt: new Date(now).toISOString(), entries: local, fleet, cleared };
+}
+
+const VOCABULARY = "lock = short mutex while a file is written · lease = process ownership (daemon, task) · claim = a worker's ownership of an item/paths";
+
+function line(entry) {
+  const who = entry.holder
+    ? entry.holder.pid !== undefined
+      ? `pid ${entry.holder.pid}${entry.holder.host ? ` on ${entry.holder.host}` : ""}${entry.holder.command ? ` (${[entry.holder.command, entry.holder.activity].filter(Boolean).join(", ")})` : entry.holder.activity ? ` (${entry.holder.activity})` : ""}`
+      : entry.holder.worker !== undefined
+        ? `worker ${entry.holder.worker}${entry.holder.assignmentId ? `, assignment ${entry.holder.assignmentId}` : ""}${entry.holder.jobId ? `, job ${entry.holder.jobId}` : ""}${entry.holder.jobEpoch ? `, job epoch ${entry.holder.jobEpoch}` : ""}`
+        : [entry.holder.actor, entry.holder.leadEpoch ? `lead epoch ${entry.holder.leadEpoch}` : null, entry.holder.supervisorEpoch ? `supervisor epoch ${entry.holder.supervisorEpoch}` : null].filter(Boolean).join(", ")
+    : "-";
+  const rows = [`${entry.state.toUpperCase().padEnd(7)} ${entry.kind} ${entry.scope}  [${entry.category}]`, `  holder:  ${who}`];
+  if (entry.heartbeatAt || entry.expiresAt) rows.push(`  timing:  ${entry.heartbeatAt ? `heartbeat ${entry.heartbeatAt}` : ""}${entry.heartbeatAt && entry.expiresAt ? ", " : ""}${entry.expiresAt ? `expires ${entry.expiresAt}` : ""}`);
+  if (entry.reason && entry.state !== "live") rows.push(`  why:     ${entry.reason}`);
+  rows.push(`  blocks:  ${entry.blocks}`);
+  if (entry.remedy) rows.push(`  fix:     ${entry.remedy}`);
+  if (entry.path) rows.push(`  file:    ${entry.path}`);
+  return rows.join("\n");
+}
+
+/** Human-readable report. */
+export function formatLeases(report) {
+  const out = [`Loop leases, locks and claims${report.taskId ? ` for ${report.taskId}` : ""} (${report.root})`, VOCABULARY, ""];
+  if (report.cleared.length) out.push(`Cleared ${report.cleared.length} stale file(s):`, ...report.cleared.map((path) => `  - ${path}`), "");
+  if (!report.entries.length) out.push("No local holders: nothing is locked.");
+  else out.push(...report.entries.map(line).join("\n\n").split("\n"));
+  if (report.fleet) {
+    out.push("", `Fleet (coordination service${report.fleet.revision !== null ? `, revision ${report.fleet.revision}` : ""}):`);
+    if (report.fleet.error) out.push(`  unavailable: ${report.fleet.error}`);
+    else if (!report.fleet.entries.length) out.push("  No fleet leases or claims.");
+    else out.push(...report.fleet.entries.map(line).join("\n\n").split("\n").map((row) => `  ${row}`));
+  }
+  const clearable = report.entries.filter((entry) => entry.clearable).length;
+  if (clearable && !report.cleared.length) out.push("", `${clearable} stale entr${clearable === 1 ? "y" : "ies"} can be removed with: ${CLEAR_STALE_COMMAND}`);
+  return out.join("\n");
+}
+

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

@@ -4,15 +4,17 @@ 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 { isLoopProvider, runAgentTurn } from "./loop-drivers.mjs";
-import { claimLocalAssignment, heartbeatLocalAssignment, reportLocalAssignment, releaseLocalAssignment } from "./assignment-store.mjs";
+import { workerDockerInvocation } from "./loop-worker-docker.mjs";
+import { isLoopProvider, runAgentTurn, summarize } from "./loop-drivers.mjs";
+import { extractCommitMessage } from "./loop-commit-message.mjs";
+import { pathOverlaps } from "./store.mjs";
+import { claimLocalAssignment, heartbeatLocalAssignment, recordLocalIntegration, reportLocalAssignment, releaseLocalAssignment } from "./assignment-store.mjs";
+import { openWorkerLog } from "./loop-worker-log.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.
@@ -22,14 +24,40 @@ const commitPaths = (root, base, head) => lines(git(root, "diff", "--name-only",
 // Workflow state and assignment records are lead-owned and never in worker
 // scopes. Their ordinary updates must not block integrating code-only commits.
 const clean = (root) => { if (statusPaths(root).some((path) => !path.startsWith(".agents/data/"))) throw new Error("Local integration worktree must be clean outside workflow data"); };
+// A worker container that may still be running (and writing) must keep its claim.
+const cleanupUncertain = (message) => Object.assign(new Error(message), { cleanupUncertain: true });
+
+/**
+ * Release the claims of failed jobs this batch itself stopped, so a timed-out,
+ * stalled, or daemon-cancelled worker does not hold its item and owned paths
+ * until a human runs `assignment.mjs release`. A claim is released only when the
+ * job rejected before reporting and its container was removed for certain; a
+ * reported (successful but unintegrated) job, an uncertain container cleanup,
+ * or a failed release keeps the claim for reconciliation. Never throws: a
+ * release error must not mask the batch failure.
+ * `outcomes`: `[{ assignmentId, itemId, reported, settled }]`, `settled` being
+ * the job's `Promise.allSettled` entry. Returns `{ released, held }`.
+ */
+export async function releaseFailedAssignments({ root, taskId, outcomes, release }) {
+  const released = [], held = [];
+  for (const { assignmentId, itemId, reported, settled } of outcomes) {
+    if (settled.status === "fulfilled" || reported) { held.push({ itemId, reason: "reported, not integrated" }); continue; }
+    if (settled.reason?.cleanupUncertain) { held.push({ itemId, reason: "container cleanup uncertain" }); continue; }
+    try { await release(root, taskId, assignmentId); released.push(itemId); }
+    catch (error) { held.push({ itemId, reason: `release failed: ${error instanceof Error ? error.message : String(error)}` }); }
+  }
+  return { released, held };
+}
 
 /**
  * Execute a batch of independent local jobs in isolated worktrees, then integrate
  * verified scoped commits sequentially. Assignment metadata is not lifecycle
  * state: the caller alone marks canonical items done after inspecting results.
- * A failed batch is deliberately left for reconciliation, not auto-retried.
+ * A failed batch is not auto-retried: claims of failed jobs the batch stopped
+ * for certain are released (see releaseFailedAssignments); the rest are left
+ * for reconciliation.
  */
-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, recordIntegration = recordLocalIntegration, 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");
@@ -39,27 +67,46 @@ export async function runLocalWorkerBatch({ root: inputRoot, taskId, jobs, workt
   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();
@@ -83,31 +130,58 @@ export async function runLocalWorkerBatch({ root: inputRoot, taskId, jobs, workt
     for (const entry of prepared) { if (entry.created) git(root, "worktree", "remove", entry.workspace); rmSync(entry.snapshot, { recursive: true, force: true }); await release(root, taskId, entry.assignment.id); }
     throw error;
   }
-  const execute = async ({ job, assignment, workspace, snapshot, baseline, branch }) => {
+  const execute = async (entry) => {
+    const { job, assignment, workspace, snapshot, baseline, branch } = entry;
+    // Live-log context: worker events name the worker, its item, and the build phase.
+    // Worker output is never logged in full: agent text is reduced to a redacted
+    // first-line summary (tool and command events already carry summaries only).
+    const workerEvent = (event) => {
+      if (!event || typeof event !== "object" || Array.isArray(event)) return onEvent(event);
+      const brief = event.type === "agent_text" ? { type: "agent_text", text: summarize(String(event.text ?? "").split(/\r?\n/).find((line) => line.trim()) ?? "") ?? "" } : event;
+      return onEvent({ taskId, actor: job.workerId, phase: "build", itemId: job.itemId, ...brief });
+    };
     let renewalError;
+    // The worker's claim ended (renewal stopped or the turn was aborted) before it finished.
+    const leaseLost = () => new Error(`Worker lease lost: the claim on assignment ${assignment.id} (item ${job.itemId}, worker ${job.workerId}, paths ${job.ownedPaths.join(", ")}) ended before the worker finished; its result is not integrated. Run node .agents/aidlc/scripts/assignment.mjs reconcile ${taskId}`);
     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)));
+    // Container record and raw output tee under the task's runtime directory
+    // (.agents/data/tasks/<task>/runtime/workers). Best-effort: a log failure is
+    // reported once as a diagnostic and never fails or delays the worker.
+    const logDiagnostic = (error) => { Promise.resolve().then(() => onEvent({ type: "diagnostic", taskId, itemId: job.itemId, message: `Worker log unavailable for assignment ${assignment.id}: ${error instanceof Error ? error.message : String(error)}` })).catch(() => {}); };
+    let workerLog = null;
+    try { workerLog = openWorkerLog({ root, taskId, assignmentId: assignment.id, itemId: job.itemId, workerId: job.workerId, agent: job.agent, mode: "local", onError: logDiagnostic }); }
+    catch (error) { logDiagnostic(error); }
+    const labels = { "aidlc.task": taskId, "aidlc.item": job.itemId, "aidlc.worker": job.workerId, "aidlc.assignment": assignment.id };
     try {
       const home=mkdtempSync(join(tmpdir(), "aidlc-local-home-")); chmodSync(home,0o700);
       let sessionId, previousFingerprint, stalls=0, result;
       try {
         for (let turn=0; turn<maxTurns; turn++) {
-          if (renewalError || controller.signal.aborted) throw renewalError ?? new Error("Worker lease lost");
+          if (renewalError || controller.signal.aborted) throw renewalError ?? leaseLost();
           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 });
-            return spawn(invocation.command, invocation.args, { ...options, cwd: snapshot, env: invocation.env, shell: false });
+            const invocation = workerDockerInvocation({ workspace: snapshot, image: resolvedImages[job.agent], command, args, credentialEnv: docker.credentials[job.agent], hostEnv: process.env, uid, gid, containerName, sessionHome:home, labels });
+            const child = spawn(invocation.command, invocation.args, { ...options, cwd: snapshot, env: invocation.env, shell: false });
+            if (workerLog) { workerLog.tee(child); child.once("close", (code) => workerLog.turnEnd(code)); }
+            return child;
           };
-          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); } }); }
+          workerLog?.turnStart(containerName, turn + 1);
+          await workerEvent({ type: "worker_turn_start", iteration: turn, agent: job.agent, summary: summarize(`turn ${turn + 1} on ${job.ownedPaths.join(", ")}`) });
+          try { result = await runAgentTurn({ agent: job.agent, root: "/workspace", sessionId, spawnProcess, onEvent: workerEvent, 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 {
-              try { dockerCheck("info"); } catch { throw new Error("Docker cleanup uncertain: engine unavailable"); }
-              try { dockerCheck("inspect", containerName); throw new Error("Docker cleanup uncertain: container remains"); }
-              catch (error) { if (error.message === "Docker cleanup uncertain: container remains") throw error; }
+              try { dockerCheck("info"); } catch { throw cleanupUncertain("Docker cleanup uncertain: engine unavailable"); }
+              try { dockerCheck("inspect", containerName); throw cleanupUncertain("Docker cleanup uncertain: container remains"); }
+              catch (error) { if (error.cleanupUncertain) throw error; }
             }
           }
-          if (renewalError || controller.signal.aborted) throw renewalError ?? new Error("Worker lease lost");
+          if (renewalError || controller.signal.aborted) throw renewalError ?? leaseLost();
           sessionId=result.sessionId;
           const changed=inspectWorkerSnapshot(snapshot,baseline,job.ownedPaths);
           if (result.resultText?.split(/\r?\n/).some((line) => line.trim() === "AI-DLC-ITEM-COMPLETE")) break;
@@ -121,7 +195,7 @@ export async function runLocalWorkerBatch({ root: inputRoot, taskId, jobs, workt
       const snapshotChanges = inspectWorkerSnapshot(snapshot, baseline, job.ownedPaths);
       if (!snapshotChanges.length) throw new Error(`Worker ${job.workerId} changed no files`);
       await heartbeat(root, taskId, assignment.id, leaseMs);
-      if (renewalError || controller.signal.aborted) throw renewalError ?? new Error("Worker lease lost");
+      if (renewalError || controller.signal.aborted) throw renewalError ?? leaseLost();
       for (const path of snapshotChanges) {
         const destination = join(workspace, path), from = join(snapshot, path);
         let parent = workspace;
@@ -136,16 +210,26 @@ 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}` });
+      entry.reported = true;
+      await workerEvent({ type: "worker_reported", commit, changedPaths: committed, summary: summarize(`changed ${committed.length} file(s): ${committed.join(", ")}`) });
       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); workerLog?.close(); }
   };
   const results = await Promise.allSettled(prepared.map(execute));
   const failure = results.find((result) => result.status === "rejected");
-  if (failure) throw new Error(`Local worker batch requires reconciliation: ${failure.reason instanceof Error ? failure.reason.message : String(failure.reason)}`);
+  if (failure) {
+    const cause = failure.reason instanceof Error ? failure.reason.message : String(failure.reason);
+    const { released, held } = await releaseFailedAssignments({ root, taskId, release, outcomes: prepared.map((entry, index) => ({ assignmentId: entry.assignment.id, itemId: entry.job.itemId, reported: entry.reported === true, settled: results[index] })) });
+    if (!held.length) throw new Error(`Local worker batch failed: ${cause}; released assignment(s) for retry: ${released.join(", ")}`);
+    throw new Error(`Local worker batch requires reconciliation: ${cause}; released: ${released.join(", ") || "none"}; still held: ${held.map(({ itemId, reason }) => `${itemId} (${reason})`).join(", ")}`);
+  }
   const completed = results.map((result) => result.value);
   let expectedHead = base;
   for (const result of completed) {
@@ -156,7 +240,11 @@ export async function runLocalWorkerBatch({ root: inputRoot, taskId, jobs, workt
     git(root, "-c", "user.name=AI-DLC integrator", "-c", "user.email=aidlc-integrator@localhost", "cherry-pick", result.commit);
     result.integrationCommit = git(root, "rev-parse", "HEAD").trim();
     expectedHead = result.integrationCommit;
-    await onEvent({ type: "job_integrated", taskId, itemId: result.itemId, assignmentId: result.assignmentId, commit: result.integrationCommit });
+    // Best-effort: the cherry-pick already happened, so a failed record must not
+    // fail the batch; the dashboard then falls back to the worker commit.
+    try { await recordIntegration(root, taskId, result.assignmentId, result.integrationCommit); }
+    catch (error) { await onEvent({ type: "diagnostic", taskId, itemId: result.itemId, message: `Could not record integration commit: ${error instanceof Error ? error.message : String(error)}` }); }
+    await onEvent({ type: "job_integrated", taskId, actor: result.workerId, phase: "build", itemId: result.itemId, assignmentId: result.assignmentId, commit: result.integrationCommit, summary: summarize(`integrated ${result.changedPaths.length} file(s) as ${result.integrationCommit.slice(0, 12)}`) });
   }
   return completed;
 }