@felixdotgo/aidlc-kit 0.2.0 → 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

@@ -5,10 +5,11 @@ import { createHash, randomUUID } from "node:crypto";
 import { tmpdir } from "node:os";
 import { createWorkerSnapshot, inspectWorkerSnapshot } from "./loop-worker-snapshot.mjs";
 import { workerDockerInvocation } from "./loop-worker-docker.mjs";
-import { isLoopProvider, runAgentTurn } from "./loop-drivers.mjs";
+import { isLoopProvider, runAgentTurn, summarize } 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";
+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);
@@ -23,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 = () => {}, signal } = {}) {
+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");
@@ -103,35 +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: 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 });
+            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 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); } }); }
+          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;
@@ -145,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;
@@ -167,12 +217,19 @@ export async function runLocalWorkerBatch({ root: inputRoot, taskId, jobs, workt
       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); signal?.removeEventListener("abort", onCancel); }
+    } 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) {
@@ -183,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;
 }

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

@@ -6,8 +6,12 @@ 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";
 import { dirname, join, resolve } from "node:path";
-import { acquireLoopLease, assertLoopPath, readLiveLease } from "./loop-lease.mjs";
+import { acquireTaskLease, heldTaskLease, readLiveLease, readTaskLease } from "./loop-lease.mjs";
+import { resolveTaskRuntimeRead, taskRuntimePath } from "./task-runtime.mjs";
+import { migrateTaskRuntime } from "./task-runtime-migrate.mjs";
+import { explainHolder } from "./loop-holder.mjs";
 import { isLoopProvider, LOOP_PROVIDER_LIST } from "./loop-drivers.mjs";
+import { isLoopOperationalPath } from "./loop-git.mjs";
 
 export const DEFAULT_LIMITS = Object.freeze({ maxTurns: 12, turnTimeoutMs: 600000, maxStallTurns: 2 });
 const states = new Set(["running", "gate", "paused", "blocked", "terminal", "complete", "stopped"]);
@@ -34,7 +38,10 @@ export function validateRoot(root) {
   return absolute;
 }
 
-export const loopRecordPath = (root, taskId) => assertLoopPath(root, taskId);
+/** Write location of the loop run record (`.agents/data/tasks/<task>/runtime/run.json`). */
+export const loopRecordPath = (root, taskId) => taskRuntimePath(root, taskId, "run.json");
+/** Read location: the runtime record, else the pre-runtime `.agents/data/loop/<task>.json`. */
+export const loopRecordReadPath = (root, taskId) => resolveTaskRuntimeRead(root, taskId, "run.json");
 
 function validateRecord(value, taskId) {
   if (!value || value.schemaVersion !== 1 || value.taskId !== taskId || typeof value.runId !== "string" || !value.runId || !isLoopProvider(value.agent) || !states.has(value.status) || !Number.isSafeInteger(value.iteration) || value.iteration < 0 || !Number.isSafeInteger(value.stallTurns) || value.stallTurns < 0 || (value.sessionId !== null && (typeof value.sessionId !== "string" || !value.sessionId)) || !value.limits || !value.updatedAt || Number.isNaN(Date.parse(value.updatedAt))) throw new Error(`Corrupt loop run record for ${taskId}`);
@@ -45,7 +52,7 @@ function validateRecord(value, taskId) {
 }
 
 export function readLoopRecord(root, taskId) {
-  const path = loopRecordPath(root, taskId);
+  const path = loopRecordReadPath(root, taskId);
   try { lstatSync(path); } catch (error) { if (error?.code === "ENOENT") return null; throw error; }
   let value;
   try { value = JSON.parse(readFileSync(path, "utf8")); }
@@ -55,6 +62,7 @@ export function readLoopRecord(root, taskId) {
 
 export function writeLoopRecord(root, record) {
   validateRecord(record, record.taskId);
+  migrateTaskRuntime(root, record.taskId, { names: ["run.json"] });
   const path = loopRecordPath(root, record.taskId);
   mkdirSync(dirname(path), { recursive: true });
   const temporary = `${path}.tmp-${process.pid}-${randomUUID()}`;
@@ -114,7 +122,7 @@ function worktreeSignal(root) {
     const status = entry.slice(0, 2);
     let name = entry.slice(3);
     if (/^[RC]/.test(status) || /[RC]$/.test(status)) name = entries[++i] ?? name;
-    if (name.startsWith(".agents/data/loop/")) continue;
+    if (isLoopOperationalPath(name)) continue;
     const path = resolve(root, name);
     if (!path.startsWith(`${root}/`)) return { kind: "unknown", reason: "unsafe changed path" };
     try {
@@ -193,7 +201,16 @@ export async function runLoop({ root: rootInput, taskId, agent, mode = "run", li
   if (preflight) checkAgent(record?.agent ?? agent, root);
   if (!record) record = { schemaVersion: 1, taskId, runId: randomUUID(), agent, status: "running", sessionId: null, iteration: 0, stallTurns: 0, limits, lastFingerprint: null, checkpoint: null, stopReason: null, pausedByLoop: false, updatedAt: iso() };
   else { const prior = { iteration: record.iteration, status: record.status, stopReason: record.stopReason, limits: record.limits }; record.limits = limits; record.stallTurns = 0; onEvent({ type: "resume", prior }); }
-  const release = acquireLoopLease(root, taskId, record.runId);
+  // The task lease: shared with the supervisor that drives this run (activity
+  // flips waiting -> turn -> waiting), or acquired here for a manual
+  // `loop.mjs run|resume` (activity turn). While activity is "turn",
+  // `state.mjs gate approve` refuses to approve.
+  const shared = heldTaskLease(root, taskId);
+  const lease = shared ?? acquireTaskLease(root, taskId, { activity: "turn", label: "loop runner", purpose: `loop run ${record.runId}`, onWarning: onEvent });
+  if (shared) {
+    try { shared.setActivity("turn"); }
+    catch (error) { try { shared.setActivity("waiting"); } catch { /* the next heartbeat writes the requested activity */ } throw error; }
+  }
   try {
     let current = readCanonical(root, taskId);
     if (precondition) {
@@ -224,6 +241,7 @@ export async function runLoop({ root: rootInput, taskId, agent, mode = "run", li
     // long multi-gate task is not permanently re-paused on every resume.
     let runTurns = 0;
   for (;;) {
+      lease.assertOwned();
       const kind = classifyAction(current.action);
       if (kind !== "run_phase") {
         record.status = kind === "await_user" ? "gate" : kind;
@@ -270,10 +288,13 @@ export async function runLoop({ root: rootInput, taskId, agent, mode = "run", li
         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 });
+      // Live-log context: every event of this lead turn names its actor, phase, and item.
+      const turnContext = { taskId, actor: "lead", phase: current.action.phase, ...(typeof current.action.itemId === "string" && current.action.itemId ? { itemId: current.action.itemId } : {}) };
+      const leadEvent = (event) => onEvent(event && typeof event === "object" && !Array.isArray(event) ? { ...turnContext, ...event } : event);
+      leadEvent({ type: "turn_start", iteration: record.iteration, 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, ...(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); } } });
+        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) => { leadEvent(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) {
@@ -282,7 +303,7 @@ export async function runLoop({ root: rootInput, taskId, agent, mode = "run", li
         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 });
+      leadEvent({ type: "turn_end", 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);
@@ -319,12 +340,23 @@ export async function runLoop({ root: rootInput, taskId, agent, mode = "run", li
       record.updatedAt = iso(); writeLoopRecord(root, record);
       return outputStop(record, stopped.action);
     }
-  } finally { release(); }
+  } finally {
+    if (!shared) lease.release();
+    else {
+      // Back to "waiting" so a human can approve the gate this run stopped at.
+      // If the write fails (guard timeout), the requested activity is kept and
+      // written by the next heartbeat; a lost lease is reported by the
+      // supervisor's next assertOwned.
+      try { shared.setActivity("waiting"); } catch (error) { onEvent({ type: "diagnostic", message: `Task lease not yet returned to waiting (retried by the next heartbeat): ${error.message}` }); }
+    }
+  }
 }
 
 export function loopStatus(rootInput, taskId) {
   const root = validateRoot(rootInput);
   const record = readLoopRecord(root, taskId);
   const current = readCanonical(root, taskId);
-  return { record, liveLease: readLiveLease(root, taskId), nextAction: current.action };
+  const entry = readTaskLease(root, taskId);
+  const lease = { state: entry.state, path: entry.path, holder: entry.holder, reason: entry.reason, ...explainHolder(entry) };
+  return { record, liveLease: entry.state === "corrupt" ? null : readLiveLease(root, taskId), lease, nextAction: current.action };
 }