@felixdotgo/aidlc-kit 0.0.1 → 0.1.0

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

@@ -0,0 +1,314 @@
+import { createHash, randomUUID } from "node:crypto";
+import { readyTaskItems, formatGateView } 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 });
+const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const digest = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+const integer = (value, name, max) => { if (!Number.isSafeInteger(value) || value < 1 || value > max) throw new Error(`${name} must be an integer from 1 to ${max}`); return value; };
+const required = (object, method) => { if (typeof object?.[method] !== "function") throw new Error(`Fleet adapter requires ${method}()`); return object[method].bind(object); };
+const assertId = (value, label) => { if (typeof value !== "string" || !ID.test(value)) throw new Error(`Invalid ${label}`); return value; };
+const actionKind = (action) => { if (!["run_phase", "dispatch", "await_user", "reconcile", "blocked", "terminal", "complete"].includes(action?.classification)) throw new Error(`Invalid canonical nextAction: ${action?.classification}`); return action.classification; };
+
+export function validateFleetLimits(input = {}) {
+  const value = { ...FLEET_LIMITS, ...input };
+  integer(value.maxTurns, "maxTurns", 1000);
+  integer(value.turnTimeoutMs, "turnTimeoutMs", 3_600_000);
+  integer(value.maxStallTurns, "maxStallTurns", 20);
+  integer(value.maxWorkers, "maxWorkers", 100);
+  integer(value.leaseMs, "leaseMs", 3_600_000);
+  integer(value.heartbeatMs, "heartbeatMs", 600_000);
+  if (value.heartbeatMs * 2 >= value.leaseMs) throw new Error("heartbeatMs must be less than half the leaseMs");
+  return value;
+}
+
+function validateSnapshot(snapshot, taskId) {
+  if (!snapshot || snapshot.task?.id !== taskId || !Number.isSafeInteger(snapshot.revision) || snapshot.revision < 0) throw new Error(`Invalid remote task snapshot for ${taskId}`);
+  actionKind(snapshot.nextAction);
+  return snapshot;
+}
+
+function readyItems(task) {
+  const items = Array.isArray(task.tasks) ? task.tasks : [];
+  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));
+
+function key(...parts) { return digest(parts); }
+
+export async function reconcileFleetJobs({ repository, taskId, leadEpoch, snapshot, handoff, now = Date.now(), allowCodeOnlyRetry = false, quiesceMs = 0 }) {
+  const jobs = await required(repository, "listJobs")({ taskId });
+  if (!Array.isArray(jobs)) throw new Error("Invalid job list");
+  const pending = [];
+  for (const job of jobs) {
+    if (job.taskId !== taskId || !job.assignmentId || !job.itemId) throw new Error("Invalid assignment in job list");
+    const item = snapshot.task.tasks?.find((candidate) => candidate.id === job.itemId);
+    if (item?.status === "done") {
+      if (["reported", "uncertain"].includes(job.state)) {
+        const result = job.state === "reported" ? await required(handoff, "verify")({ job, snapshot }) : await required(handoff, "recover")({ job, snapshot });
+        if (!result?.valid || !result.alreadyIntegrated) pending.push({ assignmentId: job.assignmentId, itemId: job.itemId, reason: result?.reason ?? "Canonical item done but reported commit is not integrated" });
+        else {
+          if (job.state === "uncertain") await required(repository, "recoverJob")({ assignmentId: job.assignmentId, leadEpoch, commitSha: result.report.commitSha, changedPaths: result.report.changedPaths, idempotencyKey: key("recover", job.assignmentId, leadEpoch, result.commitSha) });
+          await required(repository, "reconcileJob")({ assignmentId: job.assignmentId, leadEpoch, decision: "integrated", idempotencyKey: key("integrated", job.assignmentId, leadEpoch, result.commitSha) });
+        }
+      }
+      continue;
+    }
+    if (job.state === "leased" && Date.parse(job.expiresAt) <= now) {
+      const reconcileJob = required(repository, "reconcileJob");
+      const updated = await reconcileJob({ assignmentId: job.assignmentId, leadEpoch, decision: "uncertain", reason: "worker lease expired", idempotencyKey: key("expire", job.assignmentId, leadEpoch, job.attempt, job.epoch) });
+      job.state = "uncertain";
+      job.uncertainAt = updated?.fleet?.jobs?.[job.assignmentId]?.uncertainAt ?? new Date(now).toISOString();
+    }
+    if (job.state === "uncertain") {
+      if (typeof handoff?.recover === "function") {
+        const recovered = await handoff.recover({ job, snapshot });
+        if (recovered?.recovered) {
+          await required(repository, "recoverJob")({ assignmentId: job.assignmentId, leadEpoch, commitSha: recovered.report.commitSha, changedPaths: recovered.report.changedPaths, idempotencyKey: key("recover", job.assignmentId, leadEpoch, recovered.report.commitSha) });
+          job.report = recovered.report;
+          job.state = "reported";
+          pending.push({ assignmentId: job.assignmentId, itemId: job.itemId, reason: "recovered pushed branch after lost report", artifact: { valid: true, ...recovered } });
+        } else if (allowCodeOnlyRetry && recovered?.retryable === true && Number.isFinite(Date.parse(job.uncertainAt))) {
+          const waitUntil = Date.parse(job.uncertainAt) + quiesceMs;
+          if (now < waitUntil) pending.push({ assignmentId: job.assignmentId, itemId: job.itemId, reason: "waiting for stale worker turn to quiesce", waitUntil });
+          else {
+            await required(repository, "reconcileJob")({ assignmentId: job.assignmentId, leadEpoch, decision: "ready", idempotencyKey: randomUUID() });
+            job.state = "ready";
+          }
+        } else pending.push({ assignmentId: job.assignmentId, itemId: job.itemId, reason: recovered?.reason ?? "uncertain assignment; inspect Git branch before retry" });
+      } else pending.push({ assignmentId: job.assignmentId, itemId: job.itemId, reason: "uncertain assignment; inspect Git branch before retry" });
+    } else if (job.state === "reported") {
+      if (typeof handoff?.verify !== "function") throw new Error("Reported job requires Git handoff verify adapter");
+      const result = await handoff.verify({ job, snapshot });
+      if (!result?.valid) pending.push({ assignmentId: job.assignmentId, itemId: job.itemId, reason: result?.reason ?? "Git artifact verification failed" });
+      else pending.push({ assignmentId: job.assignmentId, itemId: job.itemId, reason: "verified report awaits lead integration", artifact: result });
+    }
+  }
+  return { jobs, pending };
+}
+
+async function withHeartbeat(renew, intervalMs, work) {
+  const abort = new AbortController();
+  let failure;
+  let pending = Promise.resolve();
+  const timer = setInterval(() => {
+    pending = pending.then(() => renew()).catch((error) => { failure = error; abort.abort(error); });
+  }, intervalMs);
+  timer.unref?.();
+  try {
+    const result = await work(abort.signal);
+    await pending;
+    if (failure) throw new Error(`Fleet lease renewal failed: ${failure.message}`);
+    return result;
+  } finally { clearInterval(timer); await pending; }
+}
+
+/**
+ * One fenced coordinator invocation. The repository is the remote authority;
+ * no local lifecycle file or PID lease is consulted in fleet mode.
+ */
+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 = () => {} }) {
+  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);
+  integer(pollMs, "pollMs", 300000);
+  const pickupTimeoutMs = integer(inputPickupTimeout ?? limits.leaseMs, "pickupTimeoutMs", 3_600_000);
+  const readTask = required(repository, "readTask");
+  const claimLead = required(repository, "claimLead");
+  const renewLead = required(repository, "renewLead");
+  const releaseLead = required(repository, "releaseLead");
+  const listJobs = required(repository, "listJobs");
+  const scheduleJob = required(repository, "scheduleJob");
+  const saveGateSnapshot = required(repository, "saveGateSnapshot");
+  let snapshot = validateSnapshot(await readTask({ taskId }), taskId);
+  const claim = claimedLead ?? await claimLead({ taskId, ownerId, leaseMs: limits.leaseMs, expectedRevision: snapshot.revision, idempotencyKey: randomUUID() });
+  if (!Number.isSafeInteger(claim?.epoch) || claim.epoch < 1) throw new Error("Lead claim lacks a fencing epoch");
+  const epoch = claim.epoch;
+  let turns = 0, stalls = 0, lastSignal = null;
+  const startedAt = Date.now();
+  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;
+      for (;;) {
+        if (signal.aborted) throw new Error("Lead lease renewal failed");
+        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) 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);
+          if (typeof baseReview !== "string" || !baseReview.trim()) throw new Error("Empty gate review snapshot");
+          const integrationCommit = gate === "G2_codereview" ? await required(handoff, "currentCommit")() : undefined;
+          const review = integrationCommit ? `${baseReview.trimEnd()}\n\nIntegration commit: ${integrationCommit}\n` : baseReview;
+          const saved = await saveGateSnapshot({ taskId, leadEpoch: epoch, expectedRevision: snapshot.revision, gate, gateView: review, integrationCommit, idempotencyKey: key("gate", taskId, snapshot.revision, gate, integrationCommit ?? "") });
+          onEvent({ type: "gate", taskId, gate, snapshotId: saved.snapshotId });
+          return { status: "gate", taskId, gate, snapshotId: saved.snapshotId, revision: snapshot.revision, gateView: review };
+        }
+        if (["blocked", "terminal", "complete"].includes(kind)) return { status: kind, taskId, revision: snapshot.revision, nextAction: snapshot.nextAction };
+        if (turns >= limits.maxTurns) return { status: "paused", taskId, reason: "turn limit reached", revision: snapshot.revision };
+        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) {
+            const verified = reconciled.pending.filter((entry) => entry.artifact?.valid);
+            if (verified.length && typeof handoff?.integrate === "function" && typeof completeItem === "function") {
+              for (const entry of verified) {
+                const job = reconciled.jobs.find((candidate) => candidate.assignmentId === entry.assignmentId);
+                const integrated = await handoff.integrate({ job, artifact: entry.artifact });
+                const fresh = validateSnapshot(await readTask({ taskId }), taskId);
+                await completeItem({ taskId, itemId: job.itemId, job, integrated, snapshot: fresh, leadEpoch: epoch });
+                const committed = validateSnapshot(await readTask({ taskId }), taskId);
+                if (committed.task.tasks?.find((item) => item.id === job.itemId)?.status !== "done") throw new Error(`Canonical item ${job.itemId} was not completed after integration`);
+                await required(repository, "reconcileJob")({ assignmentId: job.assignmentId, leadEpoch: epoch, decision: "integrated", idempotencyKey: key("integrated", job.assignmentId, epoch, integrated.integrationCommit) });
+                onEvent({ type: "job_integrated", taskId, itemId: job.itemId, assignmentId: job.assignmentId, commitSha: integrated.integrationCommit });
+              }
+              continue;
+            }
+            return { status: "reconcile", taskId, revision: snapshot.revision, pending: reconciled.pending };
+          }
+          const jobs = reconciled.jobs;
+          const active = jobs.filter((job) => ["ready", "leased", "reported", "uncertain"].includes(job.state));
+          const pathClaims = [...active, ...reservedJobs].filter((job) => ["ready", "leased", "reported", "uncertain"].includes(job.state));
+          const reserved = new Set(active.map((job) => job.itemId));
+          const load = new Map(workerIds.map((id) => [id, active.filter((job) => job.workerId === id).length]));
+          for (const item of readyItems(snapshot.task)) {
+            if (active.length >= limits.maxWorkers) break;
+            if (reserved.has(item.id)) continue;
+            if (!workerIds.length) throw new Error("Fleet dispatch requires at least one configured worker ID");
+            if (typeof handoff?.prepare !== "function") throw new Error("Fleet dispatch requires Git handoff prepare adapter");
+            const artifact = await handoff.prepare({ taskId, item, snapshot });
+            if (pathClaims.some((job) => pathsOverlap(artifact.ownedPaths, job.ownedPaths))) continue;
+            const workerId = [...load].sort((a, b) => a[1] - b[1])[0][0];
+            const agent = workerProviders ? workerProviders[workerId] : artifact.agent;
+            if (!isLoopProvider(agent)) throw new Error(`Invalid provider for worker ${workerId}`);
+            const job = await scheduleJob({ taskId, itemId: item.id, workerId, leadEpoch: epoch, expectedRevision: snapshot.revision, baseCommit: artifact.baseCommit, branch: artifact.branch, ownedPaths: artifact.ownedPaths, agent, idempotencyKey: randomUUID() });
+            active.push(job); reserved.add(item.id);
+            pathClaims.push({ ...job, ownedPaths: artifact.ownedPaths, state: "ready" });
+            load.set(workerId, load.get(workerId) + 1);
+            onEvent({ type: "job_scheduled", taskId, itemId: item.id, assignmentId: job.assignmentId });
+          }
+          if (active.length) {
+            for (const job of active) {
+              if (job.state !== "ready") { readySeen.delete(job.assignmentId); continue; }
+              if (!readySeen.has(job.assignmentId)) readySeen.set(job.assignmentId, Date.now());
+              if (Date.now() - readySeen.get(job.assignmentId) >= pickupTimeoutMs) {
+                await required(repository, "reconcileJob")({ assignmentId: job.assignmentId, leadEpoch: epoch, decision: "uncertain", idempotencyKey: randomUUID() });
+                return { status: "blocked", taskId, reason: `Worker did not claim assignment ${job.assignmentId} within ${pickupTimeoutMs} ms` };
+              }
+            }
+            onEvent({ type: "jobs_active", taskId, assignments: active.map((job) => job.assignmentId) });
+            await wait(pollMs);
+            continue;
+          }
+        }
+        if (kind === "reconcile") return { status: "reconcile", taskId, revision: snapshot.revision, nextAction: snapshot.nextAction };
+        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 });
+        turns++;
+        const after = validateSnapshot(await readTask({ taskId }), taskId);
+        const nextSignal = digest({ revision: after.revision, action: after.nextAction });
+        stalls = nextSignal === before || nextSignal === lastSignal ? stalls + 1 : 0;
+        lastSignal = nextSignal;
+        if (stalls >= limits.maxStallTurns) return { status: "paused", taskId, reason: `${stalls} lead turns without canonical progress`, revision: after.revision };
+      }
+    });
+  } finally {
+    await releaseLead({ taskId, ownerId, epoch }).catch((error) => onEvent({ type: "release_failed", taskId, message: error.message }));
+  }
+}
+
+/** 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 = () => {} }) {
+  assertId(workerId, "worker ID");
+  if (workerAgent !== undefined && !isLoopProvider(workerAgent)) throw new Error(`workerAgent must be ${LOOP_PROVIDER_LIST}`);
+  const limits = validateFleetLimits(inputLimits);
+  const claimJob = required(repository, "claimJob");
+  const renewJob = required(repository, "renewJob");
+  const checkpointJob = required(repository, "checkpointJob");
+  const reportJob = required(repository, "reportJob");
+  const readTask = required(repository, "readTask");
+  const job = await claimJob({ workerId, leaseMs: limits.leaseMs, idempotencyKey: key("worker-claim", workerId, randomUUID()) });
+  if (!job) return { status: "idle" };
+  if (!isLoopProvider(job.agent) || (workerAgent !== undefined && job.agent !== workerAgent)) throw new Error(`Assigned provider does not match worker ${workerId} capability`);
+  if (preflight !== undefined) {
+    if (typeof preflight !== "function") throw new Error("Worker preflight must be a function");
+    await preflight(job.agent);
+  }
+  assertId(job.taskId, "job task ID"); assertId(job.itemId, "job item ID");
+  if (!Number.isSafeInteger(job.epoch) || job.epoch < 1 || !Number.isSafeInteger(job.attempt) || job.attempt < 1 || !job.assignmentId) throw new Error("Job claim lacks a fenced attempt");
+  const identity = { assignmentId: job.assignmentId, attempt: job.attempt, epoch: job.epoch, workerId };
+  let sessionId = job.sessionId ?? null;
+  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) => {
+    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");
+      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") {
+        await report({ status: "superseded", reason: "Item absent or canonically done" });
+        return { status: "superseded", assignmentId: job.assignmentId };
+      }
+      const kind = actionKind(snapshot.nextAction);
+      if (kind === "await_user" || kind === "blocked" || kind === "terminal") {
+        await report({ status: "paused", reason: `Canonical action: ${kind}` });
+        return { status: "paused", assignmentId: job.assignmentId };
+      }
+      if (turns >= limits.maxTurns) {
+        await report({ status: "uncertain", reason: "turn limit reached", sessionId });
+        return { status: "uncertain", assignmentId: job.assignmentId };
+      }
+      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) => {
+        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 });
+      if (result?.sessionId && sessionId && result.sessionId !== sessionId) throw new Error("Worker session changed during the same assignment");
+      if (result?.sessionId && !sessionId) {
+        sessionId = result.sessionId;
+      }
+      if (signal.aborted) throw new Error("Job lease renewal failed after worker turn");
+      await renewJob({ ...identity, leaseMs: limits.leaseMs });
+      if (signal.aborted) throw new Error("Job lease renewal failed after worker turn");
+      turns++;
+      if (sessionId) await checkpointJob({ ...identity, sessionId, checkpoint: { agent: job.agent, turns, completedAt: new Date().toISOString() } });
+      const observed = await handoff.observe({ job, workspace, result, turns });
+      if (observed?.done) {
+        await renewJob({ ...identity, leaseMs: limits.leaseMs });
+        if (signal.aborted) throw new Error("Job lease renewal failed before Git handoff");
+        const artifact = await handoff.finish({ job, workspace, result });
+        if (signal.aborted) throw new Error("Job lease renewal failed during Git handoff; reconcile remote state");
+        await renewJob({ ...identity, leaseMs: limits.leaseMs });
+        if (signal.aborted) throw new Error("Job lease renewal failed after Git handoff; reconcile remote state");
+        if (!artifact?.commitSha || !Array.isArray(artifact.changedPaths)) throw new Error("Invalid Git handoff artifact");
+        await report({ status: "reported", commitSha: artifact.commitSha, changedPaths: artifact.changedPaths, sessionId });
+        return { status: "reported", assignmentId: job.assignmentId, commitSha: artifact.commitSha };
+      }
+      const currentObservation = digest({ revision: snapshot.revision, artifact: observed?.fingerprint ?? null });
+      stalls = currentObservation === lastObservation ? stalls + 1 : 0;
+      lastObservation = currentObservation;
+      if (stalls >= limits.maxStallTurns) {
+        await report({ status: "uncertain", reason: `${stalls} worker turns without observable progress`, sessionId });
+        return { status: "uncertain", assignmentId: job.assignmentId };
+      }
+    }
+  });
+}

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

@@ -0,0 +1,279 @@
+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 { createWorkerSnapshot, inspectWorkerSnapshot } from "./loop-worker-snapshot.mjs";
+
+const SHA = /^[0-9a-f]{40,64}$/;
+const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const BRANCH = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,240}$/;
+
+function git(root, ...args) {
+  return execFileSync("git", args, { cwd: root, encoding: "utf8", timeout: 30_000, maxBuffer: 4 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+function validId(value, label) {
+  if (typeof value !== "string" || !ID.test(value)) throw new Error(`Invalid ${label}`);
+  return value;
+}
+function validSha(value, label) {
+  if (typeof value !== "string" || !SHA.test(value)) throw new Error(`Invalid ${label}`);
+  return value;
+}
+function validBranch(value) {
+  if (typeof value !== "string" || !BRANCH.test(value) || value.includes("..") || value.includes("//") || value.endsWith("/") || value.split("/").some((part) => part.startsWith("."))) throw new Error("Invalid Git branch");
+  return value;
+}
+function validPath(value, label = "path") {
+  if (typeof value !== "string" || !value || value.startsWith("/") || value.includes("\\") || value.includes("\0") || value.split("/").some((part, index, parts) => (!part && index !== parts.length - 1) || part === "." || part === "..") || value === ".git" || value.startsWith(".git/")) throw new Error(`Invalid ${label}: ${value}`);
+  return value;
+}
+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();
+}
+function inScope(path, ownedPaths) { return ownedPaths.some((scope) => path === scope || (scope.endsWith("/") && 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();
+}
+function worktreePaths(root) {
+  const unstaged = execFileSync("git", ["diff", "--no-ext-diff", "--no-renames", "--name-only", "-z"], { cwd: root, encoding: "buffer", timeout: 30_000, maxBuffer: 4 * 1024 * 1024 });
+  const staged = execFileSync("git", ["diff", "--cached", "--no-ext-diff", "--no-renames", "--name-only", "-z", "HEAD"], { cwd: root, encoding: "buffer", timeout: 30_000, maxBuffer: 4 * 1024 * 1024 });
+  const untracked = execFileSync("git", ["ls-files", "--others", "--exclude-standard", "-z"], { cwd: root, encoding: "buffer", timeout: 30_000, maxBuffer: 4 * 1024 * 1024 });
+  return [...new Set(Buffer.concat([unstaged, staged, untracked]).toString("utf8").split("\0").filter(Boolean).map((path) => validPath(path, "changed path")))].sort();
+}
+function worktreeFingerprint(root, paths) {
+  // Hash the index as well as the worktree: a staged edit may differ from both
+  // HEAD and the current file, even when the latter has been restored to HEAD.
+  const index = execFileSync("git", ["ls-files", "--stage", "-z"], { cwd: root, encoding: "buffer", timeout: 30_000, maxBuffer: 4 * 1024 * 1024 });
+  const files = paths.map((path) => {
+    try {
+      const target = join(root, path);
+      const stat = lstatSync(target);
+      if (stat.isSymbolicLink()) return [path, "symlink", stat.mode, createHash("sha256").update(readlinkSync(target)).digest("hex")];
+      if (!stat.isFile()) throw new Error(`Unsupported changed path type: ${path}`);
+      return [path, "file", stat.mode, createHash("sha256").update(readFileSync(target)).digest("hex")];
+    } catch (error) {
+      if (error?.code === "ENOENT" || error?.code === "ENOTDIR") return [path, "deleted"];
+      throw error;
+    }
+  });
+  return createHash("sha256").update(git(root, "rev-parse", "HEAD")).update(index).update(JSON.stringify(files)).digest("hex");
+}
+function checkScope(paths, ownedPaths) {
+  const outside = paths.filter((path) => !inScope(path, ownedPaths));
+  if (outside.length) throw new Error(`Worker changed paths outside assignment: ${outside.join(", ")}`);
+}
+function remoteRef(remote, branch) { return `refs/remotes/${remote}/${branch}`; }
+function fetchBranch(root, remote, branch) {
+  validBranch(branch);
+  git(root, "fetch", "--no-tags", remote, `refs/heads/${branch}:${remoteRef(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; }
+}
+function assertClean(root) {
+  if (git(root, "status", "--porcelain=v1", "--untracked-files=all")) throw new Error("Git worktree must be clean before handoff or integration");
+}
+function normaliseReport(job) {
+  const report = job.report ?? job;
+  const commitSha = validSha(report.commitSha, "reported commit SHA");
+  const changed = Array.isArray(report.changedPaths) ? [...new Set(report.changedPaths.map((path) => validPath(path, "reported path")))].sort() : null;
+  if (!changed) throw new Error("Report lacks changedPaths");
+  return { commitSha, changed };
+}
+
+/** The coordinator calls this from its protected integration checkout. */
+export function createLeadGitHandoff({ root: inputRoot, integrationBranch, remote = "origin", agent = "codex" }) {
+  const root = resolve(inputRoot);
+  validBranch(integrationBranch); validId(remote, "remote");
+  if (!isLoopProvider(agent)) throw new Error("Invalid worker agent");
+  const current = () => { const branch = git(root, "symbolic-ref", "--short", "HEAD"); if (branch !== integrationBranch) throw new Error(`Expected integration branch ${integrationBranch}, found ${branch}`); return git(root, "rev-parse", "HEAD"); };
+  const syncCurrent = () => {
+    assertClean(root);
+    const localHead = current();
+    const remoteHead = fetchBranch(root, remote, integrationBranch);
+    if (localHead === remoteHead || ancestor(root, remoteHead, localHead)) return localHead;
+    if (!ancestor(root, localHead, remoteHead)) throw new Error("Integration branch diverged from remote; reconcile before dispatch");
+    git(root, "merge", "--ff-only", remoteHead);
+    return current();
+  };
+  return {
+    async currentCommit() {
+      const localHead = syncCurrent();
+      const remoteHead = fetchBranch(root, remote, integrationBranch);
+      if (localHead !== remoteHead) throw new Error("Integration commit is not published to the remote branch");
+      return localHead;
+    },
+    async prepare({ taskId, item }) {
+      validId(taskId, "task ID"); validId(item?.id, "item ID");
+      const ownedPaths = scopes(item.ownedPaths);
+      const baseCommit = syncCurrent();
+      const branch = validBranch(`aidlc/${taskId}/${item.id}/${randomUUID()}`);
+      return { baseCommit, branch, ownedPaths, agent: item.agent ?? agent };
+    },
+    async verify({ job }) {
+      try {
+        const branch = validBranch(job.branch);
+        const baseCommit = validSha(job.baseCommit, "base commit");
+        const ownedPaths = scopes(job.ownedPaths);
+        const { commitSha, changed } = normaliseReport(job);
+        const fetched = fetchBranch(root, remote, branch);
+        if (fetched !== commitSha) throw new Error("Reported commit does not match remote worker branch");
+        git(root, "cat-file", "-e", `${baseCommit}^{commit}`);
+        if (!ancestor(root, baseCommit, commitSha) || baseCommit === commitSha) throw new Error("Worker commit is not descended from assigned base");
+        const actualPaths = changedPaths(root, baseCommit, commitSha);
+        checkScope(actualPaths, ownedPaths);
+        if (JSON.stringify(actualPaths) !== JSON.stringify(changed)) throw new Error("Reported changed paths do not match Git commit");
+        const currentHead = syncCurrent();
+        if (!ancestor(root, baseCommit, currentHead)) throw new Error("Integration branch no longer contains assigned base");
+        return { valid: true, commitSha, baseCommit, branch, changedPaths: actualPaths, ownedPaths, alreadyIntegrated: ancestor(root, commitSha, currentHead) };
+      } catch (error) { return { valid: false, reason: error.message }; }
+    },
+    async recover({ job }) {
+      try {
+        const branch = validBranch(job.branch);
+        const baseCommit = validSha(job.baseCommit, "base commit");
+        const ownedPaths = scopes(job.ownedPaths);
+        try { git(root, "ls-remote", "--exit-code", remote, `refs/heads/${branch}`); }
+        catch (error) {
+          if (error?.status === 2) return { recovered: false, retryable: true, reason: "Assigned remote branch has no pushed commit" };
+          throw error;
+        }
+        const commitSha = fetchBranch(root, remote, branch);
+        git(root, "cat-file", "-e", `${baseCommit}^{commit}`);
+        if (baseCommit === commitSha) return { recovered: false, retryable: true, reason: "Assigned remote branch remains at base commit" };
+        if (!ancestor(root, baseCommit, commitSha)) throw new Error("Worker branch is not descended from assigned base");
+        const changed = changedPaths(root, baseCommit, commitSha);
+        if (!changed.length) throw new Error("Worker branch has no changed paths");
+        checkScope(changed, ownedPaths);
+        const report = { commitSha, changedPaths: changed };
+        const verified = await this.verify({ job: { ...job, report } });
+        if (!verified.valid) throw new Error(verified.reason);
+        return { recovered: true, report, ...verified };
+      } catch (error) { return { recovered: false, reason: error.message }; }
+    },
+    async integrate({ job }) {
+      // A prior verification result is advisory: re-fetch the ref at integration
+      // time so a rewritten worker branch or stale report cannot be trusted.
+      const verified = await this.verify({ job });
+      if (!verified.valid) throw new Error(`Git artifact verification failed: ${verified.reason}`);
+      const before = syncCurrent();
+      if (ancestor(root, verified.commitSha, before)) {
+        try { git(root, "push", remote, `HEAD:refs/heads/${integrationBranch}`); }
+        catch (error) { throw new Error(`Integrated locally at ${before}, but remote push failed: ${error.message}`); }
+        return { integrated: false, alreadyIntegrated: true, commitSha: verified.commitSha, integrationCommit: before, changedPaths: verified.changedPaths };
+      }
+      try {
+        git(root, "-c", "user.name=AI-DLC lead", "-c", "user.email=aidlc-lead@localhost", "merge", "--no-ff", "--no-edit", verified.commitSha);
+      } catch (error) {
+        try { git(root, "merge", "--abort"); } catch { /* The original merge error is authoritative. */ }
+        throw new Error(`Git integration conflict or failure: ${error.message}`);
+      }
+      const integrationCommit = current();
+      try { git(root, "push", remote, `HEAD:refs/heads/${integrationBranch}`); }
+      catch (error) { throw new Error(`Integrated locally at ${integrationCommit}, but remote push failed: ${error.message}`); }
+      return { integrated: true, alreadyIntegrated: false, commitSha: verified.commitSha, integrationCommit, changedPaths: verified.changedPaths };
+    }
+  };
+}
+
+/** Workers receive only assignment metadata and never write the integration branch. */
+export function createWorkerGitHandoff({ root: inputRoot, worktreesRoot: inputWorktreesRoot, remote = "origin" }) {
+  const root = resolve(inputRoot);
+  const worktreesRoot = resolve(inputWorktreesRoot);
+  validId(remote, "remote");
+  if (worktreesRoot === root || worktreesRoot.startsWith(`${root}/`)) throw new Error("Worker worktree directory must be outside the source checkout");
+  return {
+    async prepare(job) {
+      validId(job.assignmentId, "assignment ID");
+      const base = validSha(job.baseCommit, "base commit");
+      const branch = validBranch(job.branch);
+      scopes(job.ownedPaths);
+      mkdirSync(worktreesRoot, { recursive: true });
+      const workspace = join(worktreesRoot, job.assignmentId);
+      if (existsSync(workspace)) {
+        const actualBranch = git(workspace, "symbolic-ref", "--short", "HEAD");
+        if (actualBranch !== branch || !ancestor(workspace, base, "HEAD")) throw new Error("Existing worker worktree does not match assignment");
+        return { root: workspace, branch };
+      }
+      git(root, "fetch", "--no-tags", remote, base);
+      git(root, "worktree", "add", "-b", branch, workspace, base);
+      return { root: workspace, branch };
+    },
+    async observe({ job, workspace, result }) {
+      const changed = worktreePaths(workspace.root);
+      checkScope(changed, scopes(job.ownedPaths));
+      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 }) {
+      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);
+      const dirty = worktreePaths(workspace.root);
+      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 commitSha = git(workspace.root, "rev-parse", "HEAD");
+      const base = validSha(job.baseCommit, "base commit");
+      if (commitSha === base) throw new Error("Worker produced no commit");
+      const changed = changedPaths(workspace.root, base, commitSha);
+      checkScope(changed, ownedPaths);
+      git(workspace.root, "push", remote, `HEAD:refs/heads/${branch}`);
+      return { commitSha, changedPaths: changed };
+    },
+    async discard({ workspace }) {
+      const path = resolve(workspace.root);
+      if (!path.startsWith(`${worktreesRoot}/`)) throw new Error("Invalid worker worktree path");
+      git(root, "worktree", "remove", "--force", path);
+      rmSync(path, { recursive: true, force: true });
+    }
+  };
+}
+
+/** Worker sees only a checked source snapshot. Git and credentials remain on host. */
+export function createIsolatedWorkerGitHandoff(options) {
+  const host = createWorkerGitHandoff(options);
+  return {
+    async prepare(job) {
+      const checkout = await host.prepare(job);
+      if (worktreePaths(checkout.root).length || git(checkout.root, "rev-parse", "HEAD") !== job.baseCommit) throw new Error("Existing worker checkout requires reconciliation");
+      const tracked = execFileSync("git", ["ls-files", "-z"], { cwd: checkout.root, encoding: "utf8", timeout: 30000 }).split("\0").filter((path) => path && path !== ".agents/data" && !path.startsWith(".agents/data/"));
+      const snapshot = mkdtempSync(join(resolve(options.worktreesRoot), "snapshot-"));
+      try { const baseline = createWorkerSnapshot(checkout.root, snapshot, tracked); return { root: snapshot, checkout, baseline }; }
+      catch (error) { rmSync(snapshot, {recursive:true,force:true}); throw error; }
+    },
+    async observe({job, workspace, result}) {
+      const changed = inspectWorkerSnapshot(workspace.root, workspace.baseline, job.ownedPaths);
+      const fingerprint = createHash("sha256").update(JSON.stringify(changed.map((path) => { const full=join(workspace.root,path); return existsSync(full) ? [path,createHash("sha256").update(readFileSync(full)).digest("hex"),lstatSync(full).mode] : [path,null]; }))).digest("hex");
+      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}) {
+      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");
+      for (const path of changed) {
+        const source=join(workspace.root,path), target=join(workspace.checkout.root,path);
+        let parent = workspace.checkout.root;
+        for (const segment of path.split("/").slice(0,-1)) {
+          parent = join(parent,segment);
+          try { const info=lstatSync(parent); if (!info.isDirectory() || info.isSymbolicLink()) throw new Error("Unsafe integration directory"); }
+          catch(error) { if (error.code !== "ENOENT") throw error; mkdirSync(parent); }
+        }
+        try { const info=lstatSync(target); if (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1) throw new Error("Unsafe integration target"); }
+        catch(error) { if (error.code !== "ENOENT") throw error; }
+        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;
+    },
+    async discard({workspace}) { rmSync(workspace.root,{recursive:true,force:true}); return host.discard({workspace:workspace.checkout}); }
+  };
+}