@felixdotgo/aidlc-kit 0.2.0 → 0.3.0

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

@@ -1,27 +1,84 @@
-import { appendFileSync, mkdirSync, renameSync, statSync } from "node:fs";
-import { dirname } from "node:path";
+import { appendFileSync, lstatSync, mkdirSync, renameSync, statSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+import { isTaskId, taskRuntimePath } from "./task-runtime.mjs";
+import { migrateTaskRuntime } from "./task-runtime-migrate.mjs";
 
 /** The event-log sidecar rotates to `<path>.1` (one generation kept) once it
  * reaches this size, so a 24/7 daemon cannot grow it without bound. */
 export const EVENT_LOG_MAX_BYTES = 5 * 1024 * 1024;
+/** Per-task history files (`.agents/data/tasks/<taskId>/runtime/events.jsonl`)
+ * rotate the same way at a smaller bound, since one exists for every task. */
+export const TASK_EVENT_LOG_MAX_BYTES = 1024 * 1024;
 
 let preparedDirectory;
+const migratedTasks = new Set();
 
-/** Append one structured event to the optional UI event-log sidecar (JSONL).
- * Each record gets an `at` timestamp; the directory is created on demand. */
+const rotate = (path, limit) => {
+  try { if (statSync(path).size >= limit) renameSync(path, `${path}.1`); }
+  catch (error) { if (error?.code !== "ENOENT") throw error; }
+};
+
+/** True when `path` is missing or a real (non-symlink) entry of the expected kind. */
+const safeEntry = (path, directory) => {
+  try {
+    const stat = lstatSync(path);
+    return !stat.isSymbolicLink() && (directory ? stat.isDirectory() : stat.isFile());
+  } catch (error) { if (error?.code === "ENOENT") return true; throw error; }
+};
+
+/** Path of the per-task history file (`.agents/data/tasks/<taskId>/runtime/events.jsonl`),
+ * or null when `root` is not a string or the id is not a canonical task id. */
+export const taskEventLogPath = (root, taskId) => {
+  if (typeof root !== "string" || !root || !isTaskId(taskId)) return null;
+  try { return taskRuntimePath(root, taskId, "events.jsonl"); } catch { return null; }
+};
+
+/** The project root a global event sidecar belongs to: the sidecar is always
+ * `<root>/.agents/data/loop/<file>`; any other location has no task history. */
+export const loopRootFromEventLog = (logPath) => {
+  if (typeof logPath !== "string" || !logPath) return null;
+  const loopDir = dirname(resolve(logPath));
+  const data = dirname(loopDir), agents = dirname(data);
+  return basename(loopDir) === "loop" && basename(data) === "data" && basename(agents) === ".agents" ? dirname(agents) : null;
+};
+
+/** Append one line to a task's history. Refuses symlinked (or non-regular)
+ * directories and files so a planted link cannot redirect the write. A
+ * pre-runtime `.agents/data/loop/events/<taskId>.jsonl` is moved under
+ * `runtime/` before the first append of this process. */
+function appendTaskEventLog(root, taskId, line) {
+  const path = taskEventLogPath(root, taskId);
+  if (!path) return;
+  if (!migratedTasks.has(path)) { migratedTasks.add(path); migrateTaskRuntime(root, taskId, { names: ["events.jsonl", "events.jsonl.1"] }); }
+  const directory = dirname(path);
+  if (!safeEntry(dirname(directory), true) || !safeEntry(directory, true)) return;
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  if (!safeEntry(directory, true) || !safeEntry(path, false) || !safeEntry(`${path}.1`, false)) return;
+  rotate(path, TASK_EVENT_LOG_MAX_BYTES);
+  appendFileSync(path, line);
+}
+
+/** Append one structured event to the optional UI event-log sidecar (JSONL)
+ * and, when it carries a valid `taskId`, to that task's history file. Each
+ * record gets an `at` timestamp; directories are created on demand. */
 function appendEventLog(event) {
   const path = process.env.AIDLC_LOOP_EVENT_LOG;
   if (!path) return;
+  let line;
   try {
     const directory = dirname(path);
     if (preparedDirectory !== directory) { mkdirSync(directory, { recursive: true }); preparedDirectory = directory; }
-    try { if (statSync(path).size >= EVENT_LOG_MAX_BYTES) renameSync(path, `${path}.1`); }
-    catch (error) { if (error?.code !== "ENOENT") throw error; }
+    rotate(path, EVENT_LOG_MAX_BYTES);
     const record = event && typeof event === "object" && !Array.isArray(event) && !("at" in event) ? { at: new Date().toISOString(), ...event } : event;
-    appendFileSync(path, `${JSON.stringify(record)}\n`);
+    line = `${JSON.stringify(record)}\n`;
+    appendFileSync(path, line);
   } catch { /* best-effort: never break the loop on a log write failure */ }
+  try { if (line && typeof event?.taskId === "string") appendTaskEventLog(loopRootFromEventLog(path), event.taskId, line); }
+  catch { /* best-effort, independently of the global log */ }
 }
 
+const withSummary = (event, separator) => typeof event.summary === "string" && event.summary ? `${separator}${event.summary}` : "";
+
 /** Render foreground loop progress to stderr without polluting stdout JSON. */
 export function streamLog(event) {
   appendEventLog(event);
@@ -37,10 +94,10 @@ export function streamLog(event) {
       process.stderr.write(`${event.text ?? ""}\n`);
       break;
     case "agent_tool":
-      process.stderr.write(`  › tool: ${event.tool ?? "?"}\n`);
+      process.stderr.write(`  › tool: ${event.tool ?? "?"}${withSummary(event, " · ")}\n`);
       break;
     case "lifecycle_command":
-      process.stderr.write(`  › command ${event.status ?? "?"} (exit ${event.exitCode ?? "?"})\n`);
+      process.stderr.write(`  › command ${event.status ?? "?"} (exit ${event.exitCode ?? "?"})${withSummary(event, ": ")}\n`);
       break;
     case "daemon_turn_error":
       process.stderr.write(`  ! ${event.taskId ?? "?"}: ${event.message ?? "error"} (retry in ${Math.round(Number(event.retryInMs ?? 0) / 1000)}s)\n`);

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

@@ -1,61 +1,28 @@
 import { randomUUID } from "node:crypto";
 import { closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { assertLoopPath } from "./loop-lease.mjs";
+import { acquireTaskLease, assertLoopPath } from "./loop-lease.mjs";
 import { validateRoot } from "./loop-runtime.mjs";
 import { acquireStateLock, loadTask, nextAction } from "./store.mjs";
 import { recoverLeadArtifact } from "./loop-lead-artifacts.mjs";
 
 const same = (left, right) => JSON.stringify(left) === JSON.stringify(right);
 const checkAuthority = (authority) => { if (authority !== "local") throw new Error("local supervisor adapter requires local authority"); };
-const alive = (pid) => { try { process.kill(pid, 0); return true; } catch (error) { return error?.code !== "ESRCH"; } };
-const wait = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-
-function readLease(path, taskId) {
-  try {
-    const lease = JSON.parse(readFileSync(path, "utf8"));
-    if (lease?.taskId !== taskId || !Number.isSafeInteger(lease.pid) || lease.pid < 1 || typeof lease.token !== "string" || !lease.token) throw new Error("invalid fields");
-    return lease;
-  } catch (error) { if (error?.code === "ENOENT") return null; throw new Error(`Corrupt supervisor lease for ${taskId}: ${error.message}`); }
-}
-
-function writeExclusive(path, value) {
-  const fd = openSync(path, "wx", 0o600);
-  try { writeFileSync(fd, `${JSON.stringify(value)}\n`); fsyncSync(fd); } finally { closeSync(fd); }
-}
-
-/** Local durable checkpoint + separate PID-fenced supervisor lock.
- * The lock uses a distinct task key from the runner's lease so humans can approve.
+/** Local durable checkpoint + the task lease (`loop/<task>.lease`).
+ * The supervisor holds the lease with activity "waiting" between runs, so a
+ * human can approve gates; the runLoop it drives shares the same handle and
+ * flips activity to "turn" while a run executes (see loop-lease.mjs).
  * This adapter intentionally does not implement runTurn or perform approvals.
  */
-export function createLocalSupervisorAdapter({ root: rootInput, taskId }) {
+export function createLocalSupervisorAdapter({ root: rootInput, taskId, onWarning }) {
   const root = validateRoot(rootInput);
   const checkpointPath = assertLoopPath(root, taskId, ".supervisor.json");
-  const leasePath = assertLoopPath(root, taskId, ".supervisor.lease");
-  const guardPath = assertLoopPath(root, taskId, ".supervisor.guard");
-  let token;
-  const withGuard = (action) => {
-    assertLoopPath(root, taskId, ".supervisor.guard");
-    mkdirSync(dirname(guardPath), { recursive: true });
-    const guard = { taskId, pid: process.pid, token: randomUUID() }, deadline = Date.now() + 5000;
-    for (;;) {
-      try { writeExclusive(guardPath, guard); break; }
-      catch (error) {
-        if (error?.code !== "EEXIST") throw error;
-        const existing = readLease(guardPath, taskId);
-        if (!existing) continue;
-        if (!alive(existing.pid)) { if (readLease(guardPath, taskId)?.token === existing.token) { try { unlinkSync(guardPath); } catch (e) { if (e?.code !== "ENOENT") throw e; } } continue; }
-        if (Date.now() >= deadline) throw new Error(`Timed out waiting for supervisor guard: ${taskId}`);
-        wait(10);
-      }
-    }
-    try { return action(); } finally { if (readLease(guardPath, taskId)?.token === guard.token) unlinkSync(guardPath); }
-  };
+  let lease;
   const checkScope = (input) => { checkAuthority(input?.authority); if (input?.taskId !== taskId) throw new Error("supervisor task mismatch"); };
   const assertOwned = async () => {
-    assertLoopPath(root, taskId, ".supervisor.lease");
-    const current = readLease(leasePath, taskId);
-    if (!token || !current || current.token !== token || current.pid !== process.pid) throw new Error("local supervisor ownership lost");
+    if (!lease) throw new Error("local supervisor ownership lost: the task lease is not held");
+    try { lease.assertOwned(); }
+    catch (error) { throw new Error(`local supervisor ownership lost: ${error.message}`); }
   };
   const readCheckpoint = () => {
     assertLoopPath(root, taskId, ".supervisor.json");
@@ -72,27 +39,20 @@ export function createLocalSupervisorAdapter({ root: rootInput, taskId }) {
   return {
     async acquireSupervisor(input) {
       checkScope(input);
-      if (token) throw new Error("local supervisor adapter is already acquired");
+      if (lease) throw new Error("local supervisor adapter is already acquired");
       if (input.signal?.aborted) throw new Error("supervisor already aborted");
-      const newToken = randomUUID();
-      withGuard(() => {
-        assertLoopPath(root, taskId, ".supervisor.lease");
-        const existing = readLease(leasePath, taskId);
-        if (existing && alive(existing.pid)) throw new Error(`Task ${taskId} already has a live supervisor (pid ${existing.pid})`);
-        if (existing && readLease(leasePath, taskId)?.token === existing.token) unlinkSync(leasePath);
-        writeExclusive(leasePath, { taskId, pid: process.pid, token: newToken });
-      });
-      token = newToken;
-      return { assertOwned, release: async () => { if (token !== newToken) return; withGuard(() => { if (readLease(leasePath, taskId)?.token === newToken) unlinkSync(leasePath); }); token = undefined; } };
+      const handle = acquireTaskLease(root, taskId, { activity: "waiting", label: "supervisor", purpose: "local loop supervisor", onWarning });
+      lease = handle;
+      return { assertOwned, release: async () => { if (lease !== handle) return; try { handle.release(); } finally { lease = undefined; } } };
     },
     async readTask(input) {
       checkScope({ ...input, authority: "local" });
       const release = acquireStateLock(root);
       try {
-        if (token) await assertOwned();
+        if (lease) await assertOwned();
         const task = loadTask(root, taskId);
         if (!task || task.id !== taskId) throw new Error("invalid local canonical task snapshot");
-        if (token) {
+        if (lease) {
           await recoverLeadArtifact({ root, taskId, task, assertOwned });
           await assertOwned();
         } else {

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

@@ -9,7 +9,7 @@ import { runSupervisor } from "./loop-supervisor.mjs";
 import { createLocalSupervisorAdapter } from "./loop-supervisor-local.mjs";
 import { pathsOverlap, readyTaskItems, selectBuildBatch } from "./store.mjs";
 import { runLocalWorkerBatch } from "./loop-local-workers.mjs";
-import { reconcileLocalAssignments } from "./assignment-store.mjs";
+import { ASSIGNMENT_STATE_LABELS, effectiveAssignmentState, reconcileLocalAssignments } from "./assignment-store.mjs";
 import { ensureWorkerImage, defaultWorkerImageTag } from "./loop-worker-image.mjs";
 import { workerCredentialKeys } from "./loop-worker-docker.mjs";
 
@@ -26,7 +26,7 @@ export function createLocalLoopSupervisor({ root: rootInput, taskId, agent, limi
   const root = validateRoot(rootInput);
   if (!isLoopProvider(agent)) throw new Error(`local lead agent must be ${LOOP_PROVIDER_LIST}`);
   if (typeof driver !== "function" || typeof runner !== "function" || typeof onEvent !== "function") throw new Error("invalid local supervisor callbacks");
-  const adapter = createLocalSupervisorAdapter({ root, taskId });
+  const adapter = createLocalSupervisorAdapter({ root, taskId, onWarning: onEvent });
   const getRecord = () => readLoopRecord(root, taskId);
   const execute = async (mode) => {
     requireLocalAuthority();
@@ -98,8 +98,14 @@ export function planLocalBuildBatch({ taskId, task, workers, assignments = [] })
   if (!selected.length) {
     // Every ready item is held back by an assignment; never auto-release it.
     const blocking = active.filter((entry) => ready.some((itemId) => entry.itemId === itemId || pathsOverlap(byId.get(itemId).ownedPaths, entry.ownedPaths ?? [])));
-    const details = blocking.map((entry) => `${entry.state === "leased" ? "Active" : "Unresolved"} assignment ${entry.id} (${entry.state}) for ${entry.itemId} holds ${(entry.ownedPaths ?? []).join(", ")}`).join("; ");
-    throw new Error(`${details || `No ready build item of ${taskId} could be dispatched`}; inspect it, then run node .agents/aidlc/scripts/assignment.mjs reconcile ${taskId} or node .agents/aidlc/scripts/assignment.mjs release ${taskId} <assignment-id>`);
+    const now = Date.now();
+    const details = blocking.map((entry) => {
+      const state = entry.leaseExpiresAt ? effectiveAssignmentState(entry, now) : entry.state;
+      const claim = [entry.workerId ? `worker ${entry.workerId}` : null, `${ASSIGNMENT_STATE_LABELS[state] ?? state}`, entry.leaseExpiresAt ? `claim expires ${entry.leaseExpiresAt}` : null].filter(Boolean).join(", ");
+      return `${entry.state === "leased" ? "Active" : "Unresolved"} assignment ${entry.id} (${entry.state}) for ${entry.itemId} holds ${(entry.ownedPaths ?? []).join(", ")} [${claim}]`;
+    }).join("; ");
+    const releaseTarget = blocking.length === 1 ? blocking[0].id : "<assignment-id>";
+    throw new Error(`${details || `No ready build item of ${taskId} could be dispatched`}; inspect it (node .agents/aidlc/scripts/assignment.mjs show ${taskId}), then run node .agents/aidlc/scripts/assignment.mjs reconcile ${taskId} once the item is done, or node .agents/aidlc/scripts/assignment.mjs release ${taskId} ${releaseTarget} to drop the claim (discards the worker's unintegrated result)`);
   }
   const jobs = selected.map((itemId, index) => {
     const [workerId, agent] = providers[index];
@@ -133,7 +139,7 @@ export async function dispatchLocalBuild({ root, taskId, task, workers, images =
   for (const provider of new Set(jobs.map((job) => job.agent))) {
     resolvedImages[provider] = ensureImage({ root, provider, image: images[provider] ?? defaultWorkerImageTag(provider), onEvent });
   }
-  const completed = await runBatch({ root, taskId, jobs, worktreesRoot, docker: { images: resolvedImages, credentials }, signal: cancelSignal });
+  const completed = await runBatch({ root, taskId, jobs, worktreesRoot, docker: { images: resolvedImages, credentials }, onEvent, signal: cancelSignal });
   for (const result of completed) markDone(root, taskId, result.itemId);
 }
 
@@ -151,7 +157,7 @@ export function createIsolatedLocalSupervisor({ root: rootInput, taskId, agent,
   if (!isLoopProvider(agent)) throw new Error(`local lead agent must be ${LOOP_PROVIDER_LIST}`);
   if (!workers || typeof workers !== "object" || Array.isArray(workers) || !Object.keys(workers).length) throw new Error("Loop requires a configured lead and worker providers");
   for (const [id, provider] of Object.entries(workers)) if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(id) || !isLoopProvider(provider)) throw new Error(`invalid local worker: ${id}`);
-  const adapter = createLocalSupervisorAdapter({ root, taskId });
+  const adapter = createLocalSupervisorAdapter({ root, taskId, onWarning: onEvent });
   const getRecord = () => readLoopRecord(root, taskId);
   const images = Object.fromEntries([...new Set(Object.values(workers))].map((provider) => [provider, docker?.images?.[provider] ?? docker?.image ?? workerImages?.[provider] ?? process.env.AIDLC_WORKER_DOCKER_IMAGE ?? defaultWorkerImageTag(provider)]));
   const credentials = docker?.credentials ?? Object.fromEntries([...new Set(Object.values(workers))].map((provider) => [provider, workerCredentialKeys(provider)]));

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

@@ -10,6 +10,8 @@ import { isLoopProvider } from './loop-drivers.mjs';
  * the lead sandbox, not here. */
 export const OPENCODE_CONTAINER_ERROR = 'OpenCode workers require file-based credentials and are not available in isolated containers yet';
 
+const LABEL_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
 /** OpenCode's data/config roots, redirected into the worker's tmpfs HOME so the
  * container never reads the host ~/.local/share/opencode or ~/.config/opencode. */
 const OPENCODE_XDG_ENV = [
@@ -33,7 +35,7 @@ export function workerCredentialKeys(agent, env = process.env) {
 }
 
 /** Build a Docker invocation. This function never accepts a shell command or credentials in arguments. */
-export function workerDockerInvocation({ workspace, image, command, args, credentialEnv, hostEnv, uid, gid, containerName, sessionHome }) {
+export function workerDockerInvocation({ workspace, image, command, args, credentialEnv, hostEnv, uid, gid, containerName, sessionHome, labels }) {
   const root = realpathSync(workspace);
   if (/[\x00-\x1f,]/.test(root)) throw new Error('Invalid Docker workspace path');
   if (typeof image !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9._/:@-]{0,255}$/.test(image)) throw new Error('Explicit Docker image is required');
@@ -43,6 +45,16 @@ export function workerDockerInvocation({ workspace, image, command, args, creden
   const allowed = command === 'codex' ? ['OPENAI_API_KEY'] : command === 'claude' ? ['ANTHROPIC_API_KEY'] : ['OPENAI_API_KEY', 'ANTHROPIC_API_KEY', 'OPENCODE_API_KEY'];
   if (credentialEnv.some((key) => !allowed.includes(key)) || new Set(credentialEnv).size !== credentialEnv.length) throw new Error('Unsupported worker credential environment');
   if (containerName !== undefined && (typeof containerName !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$/.test(containerName))) throw new Error('Invalid container name');
+  // Optional `--label key=value` pairs (aidlc.task/item/worker/assignment) so the
+  // dashboard can `docker ps --filter label=`; keys and values are plain identifiers.
+  const labelArgs = [];
+  if (labels !== undefined) {
+    if (!labels || typeof labels !== 'object' || Array.isArray(labels)) throw new Error('Invalid container labels');
+    for (const [key, value] of Object.entries(labels)) {
+      if (!LABEL_PATTERN.test(key) || typeof value !== 'string' || !LABEL_PATTERN.test(value)) throw new Error(`Invalid container label: ${key}`);
+      labelArgs.push('--label', `${key}=${value}`);
+    }
+  }
   let homeMount;
   if (sessionHome !== undefined) {
     const info = lstatSync(sessionHome);
@@ -54,5 +66,5 @@ export function workerDockerInvocation({ workspace, image, command, args, creden
   const env = { PATH: hostEnv.PATH ?? '/usr/bin:/bin' };
   for (const key of credentialEnv) env[key] = hostEnv[key];
   const opencodeEnv = command === 'opencode' ? [...OPENCODE_XDG_ENV, 'OPENCODE_CONFIG_CONTENT={}'].flatMap((entry) => ['--env', entry]) : [];
-  return { command: 'docker', args: ['run', '--rm', '--interactive', ...(containerName ? ['--name', containerName] : []), '--read-only', '--user', `${uid}:${gid}`, '--cap-drop', 'ALL', '--security-opt', 'no-new-privileges', '--pids-limit', '256', '--memory', '2g', '--cpus', '2', '--tmpfs', '/tmp:rw,nosuid,nodev,size=256m', ...(homeMount ? ['--mount', homeMount] : ['--tmpfs', `/home/worker:rw,nosuid,nodev,size=128m,uid=${uid},gid=${gid}`]), '--env', 'HOME=/home/worker', '--workdir', '/workspace', '--mount', `type=bind,src=${root},dst=/workspace`, ...credentialEnv.flatMap((key) => ['--env', key]), ...opencodeEnv, '--entrypoint', command, image, ...args], env };
+  return { command: 'docker', args: ['run', '--rm', '--interactive', ...(containerName ? ['--name', containerName] : []), ...labelArgs, '--read-only', '--user', `${uid}:${gid}`, '--cap-drop', 'ALL', '--security-opt', 'no-new-privileges', '--pids-limit', '256', '--memory', '2g', '--cpus', '2', '--tmpfs', '/tmp:rw,nosuid,nodev,size=256m', ...(homeMount ? ['--mount', homeMount] : ['--tmpfs', `/home/worker:rw,nosuid,nodev,size=128m,uid=${uid},gid=${gid}`]), '--env', 'HOME=/home/worker', '--workdir', '/workspace', '--mount', `type=bind,src=${root},dst=/workspace`, ...credentialEnv.flatMap((key) => ['--env', key]), ...opencodeEnv, '--entrypoint', command, image, ...args], env };
 }

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

@@ -0,0 +1,158 @@
+/**
+ * Per-task record of worker containers and a raw tee of their output.
+ *
+ * Both the local loop (`loop-local-workers.mjs`) and fleet workers
+ * (`loop-fleet-cli.mjs`) write the same structure under the task's own data
+ * directory, so the dashboard lists containers identically in every mode:
+ *
+ *   .agents/data/tasks/<taskId>/runtime/workers/index.json      one entry per container (turn)
+ *   .agents/data/tasks/<taskId>/runtime/workers/<assignmentId>.log  raw stdout+stderr, all turns
+ *
+ * The log is capped at WORKER_LOG_MAX_BYTES and rotates once to `.log.1`
+ * (overwritten), the same rule as the per-task event log. Writes never throw
+ * into the caller: the first failure is reported through `onError`, later ones
+ * are swallowed. The `runtime/` directory is operational and never committed.
+ */
+import { closeSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
+import { hostname } from "node:os";
+import { join, resolve } from "node:path";
+import { taskRuntimeDir } from "./task-runtime.mjs";
+
+export const WORKER_LOG_MAX_BYTES = 5 * 1024 * 1024;
+export const WORKER_INDEX_MAX_ENTRIES = 500;
+const ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const MODES = new Set(["local", "fleet"]);
+const safeId = (value, label) => { if (typeof value !== "string" || !ID_PATTERN.test(value)) throw new Error(`Invalid ${label}`); return value; };
+const iso = () => new Date().toISOString();
+
+/** True when `path` is missing or a real (non-symlink) entry. */
+const refuseSymlink = (path) => {
+  try { if (lstatSync(path).isSymbolicLink()) throw new Error(`Worker log path crosses symlink: ${path}`); }
+  catch (error) { if (error?.code !== "ENOENT") throw error; }
+};
+
+/** `.agents/data/tasks/<taskId>/runtime/workers`, refusing symlinked components. */
+export function workerLogDirectory(root, taskId) {
+  const path = join(taskRuntimeDir(root, safeId(taskId, "task id")), "workers");
+  refuseSymlink(path);
+  return path;
+}
+export const workerIndexPath = (root, taskId) => join(workerLogDirectory(root, taskId), "index.json");
+export function workerLogPath(root, taskId, assignmentId, generation = 0) {
+  safeId(assignmentId, "assignment id");
+  const path = join(workerLogDirectory(root, taskId), `${assignmentId}.log${generation ? `.${generation}` : ""}`);
+  refuseSymlink(path);
+  return path;
+}
+
+const validEntry = (entry) => entry && typeof entry === "object" && !Array.isArray(entry) && typeof entry.name === "string" && typeof entry.assignmentId === "string" && typeof entry.startedAt === "string";
+
+/** Read a task's container index; a missing or corrupt file reads as empty. */
+export function readWorkerIndex(root, taskId) {
+  let raw;
+  try { raw = readFileSync(workerIndexPath(root, taskId), "utf8"); }
+  catch (error) { if (error?.code === "ENOENT") return []; throw error; }
+  try { const value = JSON.parse(raw); return Array.isArray(value) ? value.filter(validEntry) : []; }
+  catch { return []; }
+}
+
+function writeWorkerIndex(directory, entries) {
+  const path = join(directory, "index.json"), temp = join(directory, `index.json.${process.pid}.${Date.now().toString(36)}.tmp`);
+  const trimmed = entries.length > WORKER_INDEX_MAX_ENTRIES ? entries.slice(entries.length - WORKER_INDEX_MAX_ENTRIES) : entries;
+  const fd = openSync(temp, "w", 0o644);
+  try { writeSync(fd, `${JSON.stringify(trimmed, null, 2)}\n`); fsyncSync(fd); }
+  finally { closeSync(fd); }
+  try { renameSync(temp, path); }
+  catch (error) { try { unlinkSync(temp); } catch { /* best effort */ } throw error; }
+}
+
+/**
+ * Open the container record and raw log for one assignment.
+ * Returns `{ turnStart(containerName, turn), tee(child), turnEnd(exitCode), close() }`.
+ * `turnStart` appends `--- turn <N> container <name> <ISO> ---` and adds an index
+ * entry; `tee` appends every stdout/stderr chunk unmodified; `turnEnd` appends a
+ * trailer and records `endedAt`/`exitCode`; `close` ends a dangling turn
+ * (exitCode null) and releases the file descriptor. Methods never throw.
+ */
+export function openWorkerLog({ root, taskId, assignmentId, itemId, workerId, agent, mode, onError, maxBytes = WORKER_LOG_MAX_BYTES } = {}) {
+  if (typeof root !== "string" || !root) throw new Error("Worker log root is required");
+  safeId(taskId, "task id"); safeId(assignmentId, "assignment id"); safeId(itemId, "item id"); safeId(workerId, "worker id"); safeId(agent, "agent");
+  if (!MODES.has(mode)) throw new Error("Worker log mode must be local or fleet");
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) throw new Error("Invalid worker log size cap");
+  const base = resolve(root), host = hostname(), logName = `${assignmentId}.log`;
+  let fd = null, size = 0, reported = false, current = null, closed = false;
+  const report = (error) => {
+    if (reported) return;
+    reported = true;
+    if (typeof onError === "function") { try { onError(error instanceof Error ? error : new Error(String(error))); } catch { /* diagnostics never throw */ } }
+  };
+  const guard = (fn) => { try { fn(); } catch (error) { report(error); } };
+  const directory = () => { const path = workerLogDirectory(base, taskId); mkdirSync(path, { recursive: true }); refuseSymlink(path); return path; };
+  const open = () => {
+    if (fd !== null) return;
+    const path = workerLogPath(base, taskId, assignmentId);
+    directory();
+    fd = openSync(path, "a", 0o644);
+    try { size = lstatSync(path).size; } catch { size = 0; }
+  };
+  const write = (chunk) => {
+    if (closed) return;
+    const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk), "utf8");
+    if (!bytes.length) return;
+    open();
+    if (size > 0 && size + bytes.length > maxBytes) {
+      closeSync(fd); fd = null;
+      const path = workerLogPath(base, taskId, assignmentId);
+      refuseSymlink(workerLogPath(base, taskId, assignmentId, 1));
+      renameSync(path, `${path}.1`);
+      open();
+    }
+    let offset = 0;
+    while (offset < bytes.length) offset += writeSync(fd, bytes, offset, bytes.length - offset);
+    size += bytes.length;
+  };
+  const updateIndex = (mutate) => {
+    const dir = directory();
+    const entries = readWorkerIndex(base, taskId);
+    writeWorkerIndex(dir, mutate(entries));
+  };
+  const finish = (exitCode) => {
+    if (!current) return;
+    const entry = current; current = null;
+    const endedAt = iso(), code = Number.isSafeInteger(exitCode) ? exitCode : null;
+    try { write(`--- end turn ${entry.turn} container ${entry.name} exit ${code === null ? "signal" : code} ${endedAt} ---\n`); }
+    catch (error) { report(error); }
+    updateIndex((entries) => {
+      const index = entries.findIndex((candidate) => candidate.name === entry.name && candidate.assignmentId === assignmentId && candidate.turn === entry.turn);
+      const record = { ...(index === -1 ? entry.record : entries[index]), endedAt, exitCode: code };
+      if (index === -1) entries.push(record); else entries[index] = record;
+      return entries;
+    });
+  };
+  return {
+    turnStart(containerName, turn) {
+      guard(() => {
+        if (closed) throw new Error("Worker log is closed");
+        safeId(containerName, "container name");
+        if (!Number.isSafeInteger(turn) || turn < 0) throw new Error("Invalid worker turn");
+        if (current) finish(null);
+        const startedAt = iso();
+        const record = { name: containerName, assignmentId, itemId, workerId, agent, mode, host, turn, startedAt, log: logName };
+        current = { name: containerName, turn, record };
+        write(`--- turn ${turn} container ${containerName} ${startedAt} ---\n`);
+        updateIndex((entries) => { entries.push(record); return entries; });
+      });
+    },
+    tee(child) {
+      const listener = (chunk) => guard(() => write(chunk));
+      for (const stream of [child?.stdout, child?.stderr]) { if (stream && typeof stream.on === "function") stream.on("data", listener); }
+      return child;
+    },
+    turnEnd(exitCode) { guard(() => finish(exitCode)); },
+    close() {
+      guard(() => finish(null));
+      closed = true;
+      if (fd !== null) { const handle = fd; fd = null; try { closeSync(handle); } catch (error) { report(error); } }
+    }
+  };
+}

package/dist/assets/.agents/aidlc/scripts/lib/repo-head.mjs

@@ -0,0 +1,22 @@
+/**
+ * Resolve the repository HEAD commit for lifecycle wrappers (state.mjs, remote-state.mjs).
+ * The lifecycle core never runs git; wrappers call this and then store.mjs#recordTaskCommit.
+ */
+import { execFileSync } from "node:child_process";
+
+const shaPattern = /^[0-9a-f]{40,64}$/;
+
+/**
+ * Returns the full HEAD commit SHA of the git repository at `root`, or `undefined` when git is
+ * unavailable, `root` is not inside a repository, or the repository has no commits. Never throws.
+ */
+export const headCommit = (root, { timeout = 5000 } = {}) => {
+  if (typeof root !== "string" || !root.trim()) return undefined;
+  try {
+    const output = execFileSync("git", ["rev-parse", "--verify", "--quiet", "HEAD^{commit}"], { cwd: root, shell: false, timeout, stdio: ["ignore", "pipe", "pipe"], encoding: "utf8", maxBuffer: 4096 });
+    const sha = String(output).trim().toLowerCase();
+    return shaPattern.test(sha) ? sha : undefined;
+  } catch {
+    return undefined;
+  }
+};

package/dist/assets/.agents/aidlc/scripts/lib/store.mjs

@@ -12,6 +12,8 @@ const phaseGate = (phase) => phase === "clarify" ? "G0_confirm" : phase === "pla
 const iso = (value) => typeof value === "string" && Number.isFinite(Date.parse(value)) && new Date(Date.parse(value)).toISOString() === value;
 const text = (value) => typeof value === "string" && Boolean(value.trim());
 const idPattern = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const commitPattern = /^[0-9a-f]{7,64}$/;
+const commitFields = ["baseCommit", "finalCommit"];
 const digest = (content) => createHash("sha256").update(content).digest("hex");
 const archiveRecordPath = (id) => `.agents/data/state/archive/${id}.json`;
 const taskRecordContent = (task) => `${JSON.stringify(task, null, 2)}\n`;
@@ -74,6 +76,7 @@ const validateTask = (id, task) => {
   if (task.closure && (!text(task.closure.reason) || !text(task.closure.source) || !iso(task.closure.recordedAt))) throw new Error(`Invalid task closure: ${id}`);
   if ((task.status === "superseded") !== Boolean(task.successorTaskId) || (task.status === "closed" && task.successorTaskId)) throw new Error(`Invalid task successor: ${id}`);
   if (task.predecessorTaskId !== undefined && !text(task.predecessorTaskId)) throw new Error(`Invalid task predecessor: ${id}`);
+  for (const field of commitFields) if (task[field] !== undefined && !(typeof task[field] === "string" && commitPattern.test(task[field]))) throw new Error(`Invalid task ${field}: ${id}`);
   for (const path of Object.values(task.artifacts ?? {})) if (path) {
     const cleaned = normalize(path);
     if (isAbsolute(cleaned) || cleaned === ".." || cleaned.startsWith(`..${separator}`) || !cleaned.startsWith(`.agents${separator}data${separator}tasks${separator}`)) throw new Error(`Invalid artifact path for ${id}: ${path}`);
@@ -278,6 +281,14 @@ export const transitionTask = (state, id, target) => {
   task.phase = target; task.gate = phaseGate(target); task.status = target === "done" ? "done" : "active"; delete task.legacyG2Wait; task.updatedAt = new Date().toISOString(); return task;
 };
 
+/** Record a git SHA on a task. Wrappers resolve the SHA (lib/repo-head.mjs); the core never runs git. */
+export const recordTaskCommit = (task, field, sha) => {
+  if (!task || typeof task !== "object") throw new Error("recordTaskCommit requires a task");
+  if (!commitFields.includes(field)) throw new Error(`Unknown task commit field: ${field}`);
+  if (typeof sha !== "string" || !commitPattern.test(sha)) throw new Error(`Invalid ${field}: expected a lowercase hex git SHA (7-64 chars)`);
+  task[field] = sha; task.updatedAt = new Date().toISOString(); return task;
+};
+
 export const readyTaskItems = (task) => {
   const byId = new Map(task.tasks.map((item) => [item.id, item]));
   if (byId.size !== task.tasks.length) throw new Error(`Duplicate execution item: ${task.id}`);

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

@@ -0,0 +1,75 @@
+/**
+ * One-time, idempotent move of per-task runtime files from the layout of older
+ * aidlc-kit versions (`.agents/data/loop/assignments/<task>.json`,
+ * `.agents/data/loop/events/<task>.jsonl`, `.agents/data/loop/<task>.json`,
+ * `.agents/data/tasks/<task>/loop-intake.json`, `.../requirement.md`) to
+ * `.agents/data/tasks/<task>/runtime/` (see task-runtime.mjs).
+ *
+ * Rules: a file is renamed only when its destination does not exist (a
+ * destination that already exists is reported `skipped` and the source is left
+ * for inspection); nothing is ever deleted or overwritten; only regular files
+ * move (symlinks are reported `skipped`); a rename across filesystems falls
+ * back to copy + unlink. Leases, locks and guards stay where they are: locks
+ * are short mutexes that expire on their own, leases belong to
+ * `.agents/data/loop/`. Every writer calls `migrateTaskRuntime` for its own
+ * file before its first write, the local daemon calls `migrateAllTaskRuntime`
+ * once at start, and `loop-entry.mjs migrate-data` runs it on demand.
+ */
+import { copyFileSync, lstatSync, readdirSync, renameSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { ensureTaskRuntimeDir, isRegularFile, isTaskId, legacyTaskRuntimePath, MIGRATED_TASK_RUNTIME_FILES, taskRuntimePath } from "./task-runtime.mjs";
+
+const exists = (path) => { try { lstatSync(path); return true; } catch (error) { if (error?.code === "ENOENT") return false; throw error; } };
+
+const move = (from, to) => {
+  try { renameSync(from, to); }
+  catch (error) {
+    if (error?.code !== "EXDEV") throw error;
+    copyFileSync(from, to);
+    unlinkSync(from);
+  }
+};
+
+/** Move the legacy runtime files of one task. `names` limits the files
+ * considered (default: every migrated file). Returns one entry per legacy file
+ * found: `{ taskId, name, from, to, action: "moved" | "skipped" | "would-move", reason? }`. */
+export function migrateTaskRuntime(root, taskId, { dryRun = false, names = MIGRATED_TASK_RUNTIME_FILES } = {}) {
+  const entries = [];
+  for (const name of names) {
+    let from, to;
+    try { from = legacyTaskRuntimePath(root, taskId, name); if (!exists(from)) continue; to = taskRuntimePath(root, taskId, name); }
+    catch (error) { entries.push({ taskId, name, from: from ?? null, to: to ?? null, action: "skipped", reason: error.message }); continue; }
+    const entry = { taskId, name, from, to };
+    if (!isRegularFile(from)) { entries.push({ ...entry, action: "skipped", reason: "source is not a regular file" }); continue; }
+    if (exists(to)) { entries.push({ ...entry, action: "skipped", reason: "destination already exists" }); continue; }
+    if (dryRun) { entries.push({ ...entry, action: "would-move" }); continue; }
+    try {
+      ensureTaskRuntimeDir(root, taskId);
+      move(from, to);
+      entries.push({ ...entry, action: "moved" });
+    } catch (error) { entries.push({ ...entry, action: "skipped", reason: error.message }); }
+  }
+  return entries;
+}
+
+const listDir = (dir) => { try { return readdirSync(dir).sort(); } catch (error) { if (error?.code === "ENOENT") return []; throw error; } };
+
+/** Task ids that still have a legacy runtime file somewhere under `.agents/data`. */
+export function legacyTaskRuntimeIds(root) {
+  const data = join(root, ".agents", "data");
+  const ids = new Set();
+  const add = (value) => { if (isTaskId(value)) ids.add(value); };
+  for (const name of listDir(join(data, "loop", "assignments"))) { const match = /^(.+)\.json$/.exec(name); if (match) add(match[1]); }
+  for (const name of listDir(join(data, "loop", "events"))) { const match = /^(.+)\.jsonl(?:\.1)?$/.exec(name); if (match) add(match[1]); }
+  // `<task>.json` run records only: `<task>.supervisor.json` (lead checkpoint), `<task>.gate-receipt.json`, `ui.json` and `cli.json` stay in the loop directory.
+  for (const name of listDir(join(data, "loop"))) { const match = /^(.+)\.json$/.exec(name); if (match && !["ui", "cli"].includes(match[1]) && !/\.(supervisor|gate-receipt)$/.test(match[1])) add(match[1]); }
+  for (const name of listDir(join(data, "tasks"))) { if (exists(join(data, "tasks", name, "loop-intake.json")) || exists(join(data, "tasks", name, "requirement.md"))) add(name); }
+  return [...ids].sort();
+}
+
+/** Migrate every task with legacy runtime files. Returns `{ dryRun, entries, moved, skipped }`. */
+export function migrateAllTaskRuntime(root, { dryRun = false } = {}) {
+  const entries = [];
+  for (const taskId of legacyTaskRuntimeIds(root)) entries.push(...migrateTaskRuntime(root, taskId, { dryRun }));
+  return { dryRun, entries, moved: entries.filter((entry) => entry.action === "moved").length, skipped: entries.filter((entry) => entry.action === "skipped").length };
+}