@felixdotgo/aidlc-kit 0.1.1 → 0.3.0

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}`);
@@ -307,6 +318,60 @@ export const readyTaskItems = (task) => {
   return { ready, blocked };
 };
 
+/* Parallel work partition: owned paths overlap by path segment (`a` overlaps `a/b`, not `ab`).
+ * Two open items can run concurrently unless one is a direct or transitive dependency of the other. */
+const ownedPathKey = (path) => String(path).replace(/\/+$/, "");
+export const pathOverlaps = (left, right) => { const a = ownedPathKey(left), b = ownedPathKey(right); return a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`); };
+export const pathsOverlap = (left = [], right = []) => left.some((a) => right.some((b) => pathOverlaps(a, b)));
+const itemAncestors = (task) => {
+  const byId = new Map(task.tasks.map((item) => [item.id, item])); const memo = new Map();
+  const walk = (id, trail = new Set()) => { if (memo.has(id)) return memo.get(id); const found = new Set(); if (trail.has(id)) return found; trail.add(id); for (const dep of byId.get(id)?.dependsOn ?? []) { if (!byId.has(dep)) continue; found.add(dep); for (const deeper of walk(dep, trail)) found.add(deeper); } trail.delete(id); memo.set(id, found); return found; };
+  return (id) => walk(id);
+};
+export const concurrentItemPairs = (task) => {
+  const open = task.tasks.filter((item) => !["done", "deferred"].includes(item.status)); const ancestors = itemAncestors(task); const pairs = [];
+  for (let i = 0; i < open.length; i += 1) for (let j = i + 1; j < open.length; j += 1) { const a = open[i], b = open[j]; if (!ancestors(a.id).has(b.id) && !ancestors(b.id).has(a.id)) pairs.push([a, b]); }
+  return pairs;
+};
+/** Approve-plan partition check. `strict` (enabled loop) makes findings ERRORs; otherwise WARNs. */
+export const partitionDiagnostics = (task, { strict = true } = {}) => {
+  const level = strict ? "ERROR" : "WARN"; const diagnostics = [];
+  const unscoped = task.tasks.filter((item) => !["done", "deferred"].includes(item.status) && !(Array.isArray(item.ownedPaths) && item.ownedPaths.length));
+  if (unscoped.length) diagnostics.push({ level, code: "PARTITION_SCOPE", message: `Build items need owned paths (--owns) for parallel workers: ${unscoped.map((item) => item.id).join(", ")}` });
+  for (const [a, b] of concurrentItemPairs(task)) {
+    const shared = (a.ownedPaths ?? []).filter((path) => (b.ownedPaths ?? []).some((other) => pathOverlaps(path, other)));
+    if (shared.length) diagnostics.push({ level, code: "PARTITION_OVERLAP", message: `Items ${a.id} and ${b.id} can run concurrently but both own ${shared.join(", ")}; split the paths or add --depends-on` });
+  }
+  return diagnostics;
+};
+/** The partition check is strict when the loop is enabled: `loop.mode` local/fleet in the project config, or
+ * running inside a fleet-enabled coordination service. A missing config means the default `off`; an
+ * unreadable or corrupt config fails closed (strict). */
+export const loopPartitionStrict = (root) => {
+  if (process.env.MCP_FLEET_ENABLED === "1") return true;
+  if (root === undefined) return false;
+  const path = join(resolve(root), ".agents", "config.json");
+  if (!existsSync(path)) return false;
+  try { const mode = JSON.parse(readFileSync(path, "utf8"))?.loop?.mode; return mode === "local" || mode === "fleet"; }
+  catch { return true; }
+};
+/** Pick the next dispatchable batch: dependency-ready items in plan order, at most `capacity`,
+ * skipping items that overlap each other, `busyPaths`, or are listed in `exclude`. Never throws for overlap. */
+export const selectBuildBatch = (task, { capacity = Infinity, busyPaths = [], exclude = [] } = {}) => {
+  const byId = new Map(task.tasks.map((item) => [item.id, item])); const selected = []; const deferred = []; const taken = [];
+  for (const id of readyTaskItems(task).ready) {
+    const owned = byId.get(id)?.ownedPaths ?? [];
+    if (exclude.includes(id)) { deferred.push({ id, reason: "unresolved assignment" }); continue; }
+    if (!owned.length) { deferred.push({ id, reason: "no owned paths" }); continue; }
+    if (pathsOverlap(owned, busyPaths)) { deferred.push({ id, reason: "busy path held by an active assignment" }); continue; }
+    const clash = taken.find((entry) => pathsOverlap(owned, entry.owned));
+    if (clash) { deferred.push({ id, reason: `overlaps ${clash.id}` }); continue; }
+    if (selected.length >= capacity) { deferred.push({ id, reason: "capacity" }); continue; }
+    selected.push(id); taken.push({ id, owned });
+  }
+  return { selected, deferred };
+};
+
 export const nextAction = (task, root) => {
   const rootSuffix = root === undefined ? "" : ` --root ${JSON.stringify(resolve(root))}`;
   const script = (name) => root === undefined ? `node .agents/aidlc/scripts/${name}` : `node ${JSON.stringify(join(resolve(root), ".agents/aidlc/scripts", name))}`;
@@ -357,13 +422,14 @@ export const searchLessons = (root, state, query, areas = [], limit = 5) => { co
 
 export const listTaskSummaries = (state, options = {}) => { const active = Object.values(state.tasks).map((task) => ({ id: task.id, title: task.title, phase: task.phase, gate: task.gate, status: task.status, risk: task.risk, areas: task.areas, updatedAt: task.updatedAt, source: "active" })); const archived = options.includeArchive ? Object.values(state.archive ?? {}).map((task) => ({ id: task.id, title: task.title, phase: task.phase, gate: task.gate, status: task.status, risk: task.risk, areas: task.areas, updatedAt: task.updatedAt, source: "archive" })) : []; const queryTokens = tokens(options.query ?? ""); const statusSet = new Set(options.statuses ?? []); const filtered = [...active, ...archived].filter((item) => (!statusSet.size || statusSet.has(item.status)) && (!queryTokens.length || queryTokens.every((token) => tokens(`${item.id} ${item.title} ${item.areas.join(" ")}`).includes(token)))).sort((a, b) => b.updatedAt.localeCompare(a.updatedAt) || a.id.localeCompare(b.id)); const cursor = Math.max(0, options.cursor ?? 0); const limit = Math.max(1, Math.min(options.limit ?? 20, 100)); const items = filtered.slice(cursor, cursor + limit); return { items, nextCursor: cursor + items.length < filtered.length ? String(cursor + items.length) : null, total: filtered.length }; };
 
-export const renderWorkplan = (task) => { const decisions = task.decisions.length ? task.decisions.map((item) => `- [${item.status === "approved" ? "x" : " "}] ${item.id} — ${item.label}${item.resolution ? ` — ${item.resolution}` : ""}`).join("\n") : "- None"; const tasks = task.tasks.length ? task.tasks.map((item) => `- [${item.status === "done" ? "x" : item.status === "in_progress" ? "~" : " "}] ${item.id} — ${item.label}`).join("\n") : "- None"; const lifecycle = [`- Status: \`${task.status}\``, task.handoff ? `- Handoff: \`${task.handoff.kind}\` — ${task.handoff.reason}` : "", task.closure ? `- Closure: ${task.closure.reason}` : "", task.predecessorTaskId ? `- Predecessor: \`${task.predecessorTaskId}\`` : "", task.successorTaskId ? `- Successor: \`${task.successorTaskId}\`` : "", task.lessonDisposition ? `- Lessons: \`${task.lessonDisposition.status}\`` : ""].filter(Boolean).join("\n"); return `# Workplan — ${task.title} (\`${task.id}\`)\n\n> Generated from canonical JSON state.\n\n## Lifecycle\n${lifecycle}\n\n## 🧩 Decisions (Approve plan — before implementation)\n${decisions}\n\n## 🧩 Tasks (Review implementation — work items)\n${tasks}\n`; };
+const workplanScope = (item) => { const parts = [item.ownedPaths?.length ? `owns: ${item.ownedPaths.join(", ")}` : "", item.dependsOn?.length ? `after: ${item.dependsOn.join(", ")}` : ""].filter(Boolean); return parts.length ? ` — ${parts.join(" · ")}` : ""; };
+export const renderWorkplan = (task) => { const decisions = task.decisions.length ? task.decisions.map((item) => `- [${item.status === "approved" ? "x" : " "}] ${item.id} — ${item.label}${item.resolution ? ` — ${item.resolution}` : ""}`).join("\n") : "- None"; const tasks = task.tasks.length ? task.tasks.map((item) => `- [${item.status === "done" ? "x" : item.status === "in_progress" ? "~" : " "}] ${item.id} — ${item.label}${workplanScope(item)}`).join("\n") : "- None"; const lifecycle = [`- Status: \`${task.status}\``, task.handoff ? `- Handoff: \`${task.handoff.kind}\` — ${task.handoff.reason}` : "", task.closure ? `- Closure: ${task.closure.reason}` : "", task.predecessorTaskId ? `- Predecessor: \`${task.predecessorTaskId}\`` : "", task.successorTaskId ? `- Successor: \`${task.successorTaskId}\`` : "", task.lessonDisposition ? `- Lessons: \`${task.lessonDisposition.status}\`` : ""].filter(Boolean).join("\n"); return `# Workplan — ${task.title} (\`${task.id}\`)\n\n> Generated from canonical JSON state.\n\n## Lifecycle\n${lifecycle}\n\n## 🧩 Decisions (Approve plan — before implementation)\n${decisions}\n\n## 🧩 Tasks (Review implementation — work items)\n${tasks}\n`; };
 export const renderViews = (root, state = loadState(root), selected = Object.values(state.tasks)) => { for (const task of selected) { if (!task.artifacts.workplan) continue; assertNoSymlinkPath(root, task.artifacts.workplan); writeAtomic(join(resolve(root), task.artifacts.workplan), renderWorkplan(task)); } };
 
 const safeArtifactTarget = (root, path) => { assertNoSymlinkPath(root, path); return join(resolve(root), path); };
 const artifactContent = (root, path) => { if (!path) return undefined; try { const target = safeArtifactTarget(root, path); return existsSync(target) ? readFileSync(target, "utf8") : undefined; } catch { return undefined; } /* intentional: unreadable/unsafe artifact is treated as absent */ };
 const artifactDiagnostics = (root, task, names) => names.flatMap((name) => { const path = task.artifacts[name]; if (!path) return [{ level: "ERROR", code: "ARTIFACT_REFERENCE", message: `${name} artifact is not referenced` }]; try { return existsSync(safeArtifactTarget(root, path)) ? [] : [{ level: "ERROR", code: "ARTIFACT_MISSING", message: `${path} does not exist` }]; } catch (error) { return [{ level: "ERROR", code: "ARTIFACT_UNSAFE", message: error instanceof Error ? error.message : String(error) }]; } });
-export const checkGate = (root, state, taskId, gate) => { const task = state.tasks[taskId]; if (!task) return [{ level: "ERROR", code: "TASK_UNKNOWN", message: `Unknown active task: ${taskId}` }]; const diagnostics = []; if (task.gate !== gate) diagnostics.push({ level: "ERROR", code: "GATE_STATE", message: `Task is at ${task.gate}, not ${gate}` }); if (["closed", "superseded"].includes(task.status)) diagnostics.push({ level: "ERROR", code: "TASK_TERMINAL", message: `Terminal task cannot approve ${gate}` }); if (task.handoff) diagnostics.push({ level: "ERROR", code: "TASK_HANDOFF", message: `Task has unresolved handoff: ${task.handoff.reason}` }); if (task.id !== taskId) diagnostics.push({ level: "ERROR", code: "TASK_ID", message: "Task key and id differ" }); if (!task.title.trim() || !task.areas.length) diagnostics.push({ level: "ERROR", code: "TASK_FIELDS", message: "Task title and affected areas are required" }); if (gate === "G0_confirm") { diagnostics.push(...artifactDiagnostics(root, task, ["intent"])); const content = artifactContent(root, task.artifacts.intent); if (content !== undefined) for (const heading of ["## 📋 Problem", "## 🗺️ Affected areas", "## 💭 Assumptions", "## ❓ Open questions", "## 🎯 Scope"]) if (!content.includes(heading)) diagnostics.push({ level: "ERROR", code: "INTENT_HEADING", message: `Intent is missing ${heading}` }); } if (gate === "G1_review") { diagnostics.push(...artifactDiagnostics(root, task, ["intent", "design", "workplan"])); diagnostics.push(...transitionDiagnostics(task, "build").filter((item) => item.code === "UNRESOLVED_DECISION")); const content = artifactContent(root, task.artifacts.design); if (content !== undefined) for (const heading of ["## 🧩 Solution per affected area", "## 📌 Spec traceability", "## 🔗 Cross-service contracts", "## ⚠️ Risks / edge cases"]) if (!content.includes(heading)) diagnostics.push({ level: "ERROR", code: "DESIGN_HEADING", message: `Design is missing ${heading}` }); } if (gate === "G2_codereview") { diagnostics.push(...artifactDiagnostics(root, task, ["intent", "design", "workplan"])); if (task.tasks.some((item) => !["done", "deferred"].includes(item.status))) diagnostics.push({ level: "ERROR", code: "TASKS_OPEN", message: "Build tasks remain open" }); for (const area of task.areas) if (!hasAreaVerification(task, area)) diagnostics.push({ level: "ERROR", code: "VERIFY_EVIDENCE", message: `Latest post-G1 verification evidence must pass for affected area: ${area}` }); if (!hasReview(task)) diagnostics.push({ level: "ERROR", code: "REVIEW_EVIDENCE", message: "Latest post-G1 code-review evidence must pass" }); const bounds = repairBounds(task); if (!isLegacyG2Wait(task) && (bounds.verifyExhausted || bounds.reviewExhausted)) diagnostics.push({ level: "ERROR", code: "REPAIR_BOUND", message: "Repair bound exhausted; record a durable handoff instead of presenting G2" }); } if (!diagnostics.length) diagnostics.push({ level: "INFO", code: "GATE_OK", message: `${gate} checks passed for ${taskId}` }); return diagnostics; };
+export const checkGate = (root, state, taskId, gate) => { const task = state.tasks[taskId]; if (!task) return [{ level: "ERROR", code: "TASK_UNKNOWN", message: `Unknown active task: ${taskId}` }]; const diagnostics = []; if (task.gate !== gate) diagnostics.push({ level: "ERROR", code: "GATE_STATE", message: `Task is at ${task.gate}, not ${gate}` }); if (["closed", "superseded"].includes(task.status)) diagnostics.push({ level: "ERROR", code: "TASK_TERMINAL", message: `Terminal task cannot approve ${gate}` }); if (task.handoff) diagnostics.push({ level: "ERROR", code: "TASK_HANDOFF", message: `Task has unresolved handoff: ${task.handoff.reason}` }); if (task.id !== taskId) diagnostics.push({ level: "ERROR", code: "TASK_ID", message: "Task key and id differ" }); if (!task.title.trim() || !task.areas.length) diagnostics.push({ level: "ERROR", code: "TASK_FIELDS", message: "Task title and affected areas are required" }); if (gate === "G0_confirm") { diagnostics.push(...artifactDiagnostics(root, task, ["intent"])); const content = artifactContent(root, task.artifacts.intent); if (content !== undefined) for (const heading of ["## 📋 Problem", "## 🗺️ Affected areas", "## 💭 Assumptions", "## ❓ Open questions", "## 🎯 Scope"]) if (!content.includes(heading)) diagnostics.push({ level: "ERROR", code: "INTENT_HEADING", message: `Intent is missing ${heading}` }); } if (gate === "G1_review") { diagnostics.push(...artifactDiagnostics(root, task, ["intent", "design", "workplan"])); diagnostics.push(...transitionDiagnostics(task, "build").filter((item) => item.code === "UNRESOLVED_DECISION")); const content = artifactContent(root, task.artifacts.design); if (content !== undefined) for (const heading of ["## 🧩 Solution per affected area", "## 📌 Spec traceability", "## 🔗 Cross-service contracts", "## ⚠️ Risks / edge cases"]) if (!content.includes(heading)) diagnostics.push({ level: "ERROR", code: "DESIGN_HEADING", message: `Design is missing ${heading}` }); diagnostics.push(...partitionDiagnostics(task, { strict: loopPartitionStrict(root) })); } if (gate === "G2_codereview") { diagnostics.push(...artifactDiagnostics(root, task, ["intent", "design", "workplan"])); if (task.tasks.some((item) => !["done", "deferred"].includes(item.status))) diagnostics.push({ level: "ERROR", code: "TASKS_OPEN", message: "Build tasks remain open" }); for (const area of task.areas) if (!hasAreaVerification(task, area)) diagnostics.push({ level: "ERROR", code: "VERIFY_EVIDENCE", message: `Latest post-G1 verification evidence must pass for affected area: ${area}` }); if (!hasReview(task)) diagnostics.push({ level: "ERROR", code: "REVIEW_EVIDENCE", message: "Latest post-G1 code-review evidence must pass" }); const bounds = repairBounds(task); if (!isLegacyG2Wait(task) && (bounds.verifyExhausted || bounds.reviewExhausted)) diagnostics.push({ level: "ERROR", code: "REPAIR_BOUND", message: "Repair bound exhausted; record a durable handoff instead of presenting G2" }); } if (!diagnostics.some((item) => item.level === "ERROR")) diagnostics.push({ level: "INFO", code: "GATE_OK", message: `${gate} checks passed for ${taskId}` }); return diagnostics; };
 const gateTarget = { G0_confirm: "plan", G1_review: "build", G2_codereview: "wrap" };
 export const approveAndAdvance = (root, state, taskId, gate, source, recordedAt = new Date().toISOString()) => { const task = state.tasks[taskId]; if (!task) throw new Error(`Unknown active task: ${taskId}`); if (["closed", "superseded"].includes(task.status) || task.handoff) throw new Error(`Terminal or handed-off task cannot approve ${gate}`); const target = gateTarget[gate]; if (!target) throw new Error(`Gate ${gate} cannot be approved`); if (task.phase === target) return { task, nextAction: nextAction(task, root), idempotent: true }; if (task.gate !== gate || task.status !== "blocked_on_user") throw new Error(`Task must be blocked_on_user at ${gate}`); const errors = checkGate(root, state, taskId, gate).filter((item) => item.level === "ERROR"); if (errors.length) throw new Error(errors.map((item) => item.message).join("; ")); task.evidence.push({ kind: "approval", gate, result: "pass", source, recordedAt }); transitionTask(state, taskId, target); return { task, nextAction: nextAction(task, root), idempotent: false }; };
 export const formatDiagnostics = (diagnostics) => diagnostics.map((item) => `${item.level} ${item.code}: ${item.message}`).join("\n");

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 };
+}

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

@@ -0,0 +1,97 @@
+/**
+ * Per-task operational data lives under the task's own directory:
+ *
+ *   .agents/data/tasks/<taskId>/runtime/
+ *     assignments.json      local worker claims (`assignment-store.mjs`)
+ *     assignments.lock      short mutex around one assignments read-modify-write
+ *     events.jsonl (+ .1)   the task's event history (`loop-stream.mjs`)
+ *     run.json              the loop run record (`loop-runtime.mjs`)
+ *     intake.json           the loop intake record (`loop-intake.mjs`)
+ *     requirement.md        the intake requirement text
+ *     workers/              container index and raw output (`loop-worker-log.mjs`)
+ *
+ * The task directory root keeps review artifacts only; `.agents/data/loop/`
+ * keeps daemon/process state (daemon lock and log, the global event sidecar,
+ * task leases). The same layout serves the no-loop workflow, the local loop,
+ * and fleet, so every reader finds task data without knowing which mode wrote
+ * it. `runtime/` is operational: never committed, handed off, or clean-checked
+ * (`isLoopOperationalPath` in loop-git.mjs).
+ *
+ * Older versions kept these files under `.agents/data/loop/` (assignments,
+ * events, `<task>.json` run record) and at the task directory root
+ * (`loop-intake.json`, `requirement.md`). `legacyTaskRuntimePath` names those
+ * locations so readers fall back to them and `task-runtime-migrate.mjs` moves
+ * them once.
+ */
+import { lstatSync, mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+/** Runtime file names and where an older aidlc-kit kept each one (relative to `.agents/data`). */
+export const TASK_RUNTIME_FILES = Object.freeze({
+  "assignments.json": (taskId) => ["loop", "assignments", `${taskId}.json`],
+  "assignments.lock": (taskId) => ["loop", "assignments", `${taskId}.lock`],
+  "events.jsonl": (taskId) => ["loop", "events", `${taskId}.jsonl`],
+  "events.jsonl.1": (taskId) => ["loop", "events", `${taskId}.jsonl.1`],
+  "run.json": (taskId) => ["loop", `${taskId}.json`],
+  "intake.json": (taskId) => ["tasks", taskId, "loop-intake.json"],
+  "requirement.md": (taskId) => ["tasks", taskId, "requirement.md"],
+});
+
+/** Runtime files that `task-runtime-migrate.mjs` moves (locks are short-lived and expire on their own). */
+export const MIGRATED_TASK_RUNTIME_FILES = Object.freeze(["assignments.json", "events.jsonl", "events.jsonl.1", "run.json", "intake.json", "requirement.md"]);
+
+export const isTaskId = (value) => typeof value === "string" && ID_PATTERN.test(value);
+const safeTaskId = (taskId) => { if (!isTaskId(taskId)) throw new Error(`Invalid task id: ${taskId}`); return taskId; };
+const safeName = (name) => { if (!Object.hasOwn(TASK_RUNTIME_FILES, name)) throw new Error(`Unknown task runtime file: ${name}`); return name; };
+
+/** Throw when `path` exists and is a symlink (a planted link must not redirect reads or writes). */
+const refuseSymlink = (path) => {
+  try { if (lstatSync(path).isSymbolicLink()) throw new Error(`Task runtime path crosses symlink: ${path}`); }
+  catch (error) { if (error?.code !== "ENOENT") throw error; }
+};
+
+/** Join `parts` under `root`, refusing any symlinked component. */
+const safeJoin = (root, parts) => {
+  let path = resolve(root);
+  for (const part of parts) { path = join(path, part); refuseSymlink(path); }
+  return path;
+};
+
+/** `.agents/data/tasks/<taskId>/runtime`, every component checked for symlinks. */
+export function taskRuntimeDir(root, taskId) {
+  return safeJoin(root, [".agents", "data", "tasks", safeTaskId(taskId), "runtime"]);
+}
+
+/** The current location of one runtime file (`name` from TASK_RUNTIME_FILES). */
+export function taskRuntimePath(root, taskId, name) {
+  return safeJoin(root, [".agents", "data", "tasks", safeTaskId(taskId), "runtime", safeName(name)]);
+}
+
+/** Where an older aidlc-kit kept the same runtime file. */
+export function legacyTaskRuntimePath(root, taskId, name) {
+  return safeJoin(root, [".agents", "data", ...TASK_RUNTIME_FILES[safeName(name)](safeTaskId(taskId))]);
+}
+
+/** True when `path` is a regular (non-symlink) file. */
+export const isRegularFile = (path) => {
+  try { const stat = lstatSync(path); return stat.isFile() && !stat.isSymbolicLink(); } catch (error) { if (error?.code === "ENOENT") return false; throw error; }
+};
+
+/** Read location of a runtime file: the current path when it exists, else the
+ * legacy path when that exists, else the current path (for a clean ENOENT). */
+export function resolveTaskRuntimeRead(root, taskId, name) {
+  const current = taskRuntimePath(root, taskId, name);
+  if (isRegularFile(current)) return current;
+  const legacy = legacyTaskRuntimePath(root, taskId, name);
+  return isRegularFile(legacy) ? legacy : current;
+}
+
+/** Create the runtime directory (0700, like the task directory an intake creates) and return it. */
+export function ensureTaskRuntimeDir(root, taskId) {
+  const directory = taskRuntimeDir(root, taskId);
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  refuseSymlink(directory);
+  return directory;
+}

package/dist/assets/.agents/aidlc/scripts/loop-entry.mjs

@@ -1,90 +1,185 @@
 #!/usr/bin/env node
-import { execFileSync } from "node:child_process";
-import { randomUUID } from "node:crypto";
-import { existsSync, readFileSync } from "node:fs";
+/**
+ * Loop entry point shared by `aidlc-kit loop`, the web dashboard, and operators.
+ *
+ *   start         start the singleton loop daemon for the configured mode (local or fleet)
+ *   intake        create a loop-owned task from a stdin requirement (≤ 8192 bytes) without running it
+ *   status        print the canonical task, loop record/checkpoint, and next action
+ *   worker-image  build and record a provider worker image
+ *   env           report the daemon environment: providers, env file, each variable's
+ *                 source (shell/file/derived) and missing values; secrets are never
+ *                 printed. `env [root] [--json]`; exits 1 when the daemon could not start.
+ *   leases        list loop leases, locks and claims: who holds what, until when,
+ *                 what it blocks, and how to clear it. Works with any loop mode.
+ *                 `leases [task-id] [root] [--json] [--clear-stale]`; --clear-stale
+ *                 removes only stale/old-corrupt lease, lock and guard files.
+ *   migrate-data  move per-task runtime files of older versions (loop assignments,
+ *                 events, run records, intake) under .agents/data/tasks/<id>/runtime/.
+ *                 `migrate-data [root] [--dry-run] [--json]`; idempotent, never
+ *                 overwrites or deletes (the daemon also runs it at start).
+ * Dashboard JSON actions (fleet authority; local dashboards read local state in-process):
+ *   tasks | task <id> | gate <id> | resume-task <id> | approve <id> (source on stdin,
+ *   reviewer credential only from AIDLC_FLEET_REVIEWER_TOKEN of this process) |
+ *   feedback <id> (JSON `{ reason, source }` on stdin; keeps the task at its gate
+ *   and never needs the reviewer credential)
+ *
+ * Positional arguments: [action, taskId, root, mode, provider, tag, title].
+ * Gate approval for local tasks stays on the trusted terminal (`loop-gate.mjs`).
+ */
+import { readFileSync } from "node:fs";
 import { resolve, join } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { stdin, stdout } from "node:process";
 import { requireLocalAuthority } from "./lib/authority.mjs";
 import { isLoopProvider } from "./lib/loop-drivers.mjs";
-import { prepareLoopIntake } from "./lib/loop-intake.mjs";
+import { createLoopAuthority } from "./lib/loop-authority.mjs";
+import { runLoopDaemon } from "./lib/loop-daemon.mjs";
+import { streamLog } from "./lib/loop-stream.mjs";
 import * as localSupervisor from "./lib/loop-supervisor-run-local.mjs";
-import { loadTask } from "./lib/store.mjs";
+import { buildWorkerImage, defaultWorkerImageTag, recordWorkerImage } from "./lib/loop-worker-image.mjs";
+import { formatLeases, runLeases } from "./lib/loop-leases.mjs";
+import { migrateAllTaskRuntime } from "./lib/task-runtime-migrate.mjs";
+import { formatLoopEnvReport, loadLoopEnv, publicReport } from "./lib/loop-env.mjs";
+import { callRemoteTool } from "./lib/remote-state-client.mjs";
 
-const [action, taskArg, rootArg, modeArg] = process.argv.slice(2);
+const [action, taskArg, rootArg, modeArg, providerArg, tagArg, titleArg] = process.argv.slice(2);
 const root = resolve(rootArg || ".");
-const readRequirement = async () => {
-  if (stdin.isTTY) { const rl = createInterface({ input: stdin, output: stdout }); try { return await rl.question("Requirement: "); } finally { rl.close(); } }
-  const chunks = []; for await (const chunk of stdin) { chunks.push(chunk); if (chunks.reduce((n, c) => n + c.length, 0) > 8192) throw new Error("Requirement exceeds 8192 bytes"); } return Buffer.concat(chunks).toString("utf8");
+const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const ACTIONS = ["start", "resume", "status", "intake", "tasks", "task", "gate", "resume-task", "approve", "feedback"];
+const readStdin = async (prompt) => {
+  if (stdin.isTTY) { const rl = createInterface({ input: stdin, output: stdout }); try { return await rl.question(prompt); } finally { rl.close(); } }
+  const chunks = []; for await (const chunk of stdin) { chunks.push(chunk); if (chunks.reduce((n, c) => n + c.length, 0) > 8192) throw new Error("Input exceeds 8192 bytes"); } return Buffer.concat(chunks).toString("utf8");
 };
+const requireTaskId = () => { if (!ID.test(taskArg ?? "")) throw new Error("Valid task ID required"); return taskArg; };
+const print = (value) => console.log(JSON.stringify(value, null, 2));
+
+/** `leases [task-id] [root] [--json] [--clear-stale]`; empty positionals are skipped. */
+async function runLeasesAction(argv) {
+  const flagSet = new Set(argv.filter((value) => value.startsWith("--")));
+  for (const flag of flagSet) if (!["--json", "--clear-stale"].includes(flag)) throw new Error(`Unknown leases option: ${flag}`);
+  const [taskValue = "", rootValue = ""] = argv.filter((value) => !value.startsWith("--"));
+  if (taskValue && !ID.test(taskValue)) throw new Error("Valid task ID required");
+  const leasesRoot = resolve(rootValue || ".");
+  let config = null;
+  try { config = JSON.parse(readFileSync(join(leasesRoot, ".agents", "config.json"), "utf8")); } catch { config = null; }
+  const env = process.env;
+  const fleetReader = config?.loop?.mode === "fleet" && env.AIDLC_FLEET_URL && env.AIDLC_FLEET_TOKEN && env.AIDLC_FLEET_WORKSPACE
+    ? () => callRemoteTool({ url: env.AIDLC_FLEET_URL, token: env.AIDLC_FLEET_TOKEN }, "fleet_get", { workspace: env.AIDLC_FLEET_WORKSPACE })
+    : undefined;
+  const report = await runLeases({ root: leasesRoot, taskId: taskValue || undefined, clearStale: flagSet.has("--clear-stale"), fleetReader });
+  if (config?.loop?.mode === "fleet" && !fleetReader) report.fleet = { revision: null, entries: [], error: "lead credential not set (AIDLC_FLEET_URL, AIDLC_FLEET_TOKEN, AIDLC_FLEET_WORKSPACE); fleet leases not shown" };
+  if (flagSet.has("--json")) print(report);
+  else console.log(formatLeases(report));
+}
+
+/** `migrate-data [root] [--dry-run] [--json]`: move pre-runtime per-task files under `runtime/`. */
+function runMigrateDataAction(argv) {
+  const flagSet = new Set(argv.filter((value) => value.startsWith("--")));
+  for (const flag of flagSet) if (!["--json", "--dry-run"].includes(flag)) throw new Error(`Unknown migrate-data option: ${flag}`);
+  const [rootValue = ""] = argv.filter((value) => !value.startsWith("--"));
+  const migrateRoot = resolve(rootValue || ".");
+  const result = migrateAllTaskRuntime(migrateRoot, { dryRun: flagSet.has("--dry-run") });
+  if (flagSet.has("--json")) { print({ schemaVersion: 1, root: migrateRoot, ...result }); return; }
+  const verb = result.dryRun ? "would move" : "moved";
+  if (!result.entries.length) { console.log(`Nothing to migrate: every task runtime file is already under .agents/data/tasks/<id>/runtime/ (${migrateRoot})`); return; }
+  for (const entry of result.entries) console.log(`${entry.action === "skipped" ? "skipped" : verb}: ${entry.from} -> ${entry.to}${entry.reason ? ` (${entry.reason})` : ""}`);
+  console.log(`${result.dryRun ? "Would move" : "Moved"} ${result.entries.filter((entry) => entry.action !== "skipped").length} file(s), skipped ${result.skipped}.`);
+}
+
+/** `env [root] [--json]`: the local daemon environment report (no secret values). */
+function runEnvAction(argv) {
+  const flagSet = new Set(argv.filter((value) => value.startsWith("--")));
+  for (const flag of flagSet) if (flag !== "--json") throw new Error(`Unknown env option: ${flag}`);
+  const [rootValue = ""] = argv.filter((value) => !value.startsWith("--"));
+  const envRoot = resolve(rootValue || ".");
+  let config = null;
+  try { config = JSON.parse(readFileSync(join(envRoot, ".agents", "config.json"), "utf8")); } catch { config = null; }
+  const report = publicReport(loadLoopEnv({ root: envRoot, config }));
+  if (flagSet.has("--json")) print(report); else console.log(formatLoopEnvReport(report));
+  if (!report.ok) process.exitCode = 1;
+}
+
 try {
-  if (!["start", "resume", "status"].includes(action)) throw new Error("Expected loop start, resume, or status");
-  const config = JSON.parse(readFileSync(join(root, ".agents", "config.json"), "utf8"));
-  const mode = modeArg || config.loop?.mode || "off";
-  if (!["local", "fleet"].includes(mode)) throw new Error("Loop mode is off; configure an enabled loop mode first");
-  if (mode !== config.loop?.mode) throw new Error("Requested mode does not match configured authority");
-  const agent = config.loop?.agents?.lead;
-  const workers = config.loop?.agents?.workers ?? {};
-  if (!isLoopProvider(agent) || !Object.keys(workers).length || Object.entries(workers).some(([, value]) => !isLoopProvider(value))) throw new Error("Loop requires a configured lead and worker providers");
-  const taskId = taskArg || (action === "start" ? `loop-${randomUUID()}` : "");
-  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(taskId)) throw new Error("Valid task ID required");
-  if (mode === "fleet") {
-    const { callRemoteTool } = await import("./lib/remote-state-client.mjs");
-    const { createFleetRemoteRepository } = await import("./lib/loop-fleet-remote.mjs");
-    const { runFleetCli } = await import("./lib/loop-fleet-cli.mjs");
-    const { readIntegrationCommit } = await import("./remote-state.mjs");
-    const requiredEnv = (name) => { const value = process.env[name]; if (typeof value !== "string" || !value.trim()) throw new Error(`Fleet loop requires ${name} for the configured remote authority`); return value; };
-    const url = requiredEnv("AIDLC_FLEET_URL"), workspace = requiredEnv("AIDLC_FLEET_WORKSPACE"), token = requiredEnv("AIDLC_FLEET_TOKEN");
-    const integrationBranch = requiredEnv("AIDLC_FLEET_INTEGRATION_BRANCH");
-    if (process.env.AIDLC_FLEET_PROJECT_ROOT && resolve(process.env.AIDLC_FLEET_PROJECT_ROOT) !== root) throw new Error("AIDLC_FLEET_PROJECT_ROOT does not match the loop root; refusing to run");
-    if (process.env.AIDLC_FLEET_WORKER_IDS && process.env.AIDLC_FLEET_WORKER_IDS.split(",").map((value) => value.trim()).filter(Boolean).join(",") !== Object.keys(workers).join(",")) throw new Error("AIDLC_FLEET_WORKER_IDS does not match the configured loop workers");
-    if (process.env.AIDLC_FLEET_WORKER_PROVIDERS && process.env.AIDLC_FLEET_WORKER_PROVIDERS !== JSON.stringify(workers)) throw new Error("AIDLC_FLEET_WORKER_PROVIDERS does not match the configured loop workers");
-    const env = { ...process.env, AIDLC_FLEET_PROJECT_ROOT: root, AIDLC_FLEET_WORKER_IDS: Object.keys(workers).join(","), AIDLC_FLEET_WORKER_PROVIDERS: JSON.stringify(workers), AIDLC_FLEET_AGENT: agent };
-    const remoteState = join(root, ".agents/aidlc/scripts/remote-state.mjs");
-    if (!existsSync(remoteState)) throw new Error(`Remote lifecycle CLI is missing: ${remoteState}`);
-    const callTool = ({ url: serviceUrl, token: serviceToken, name, args }) => callRemoteTool({ url: serviceUrl, token: serviceToken }, name, args);
-    const repository = createFleetRemoteRepository({ callTool, url, token, workspace, root });
-    if (action === "status") {
-      let snapshot = null;
-      try { snapshot = await repository.readTask({ taskId }); } catch (error) { if (!String(error?.message ?? error).includes("task not found")) throw error; }
-      const checkpoint = await repository.readGateCheckpoint({ taskId });
-      console.log(JSON.stringify({ taskId, authority: "fleet", task: snapshot?.task ?? null, nextAction: snapshot?.nextAction ?? null, checkpoint }, null, 2));
+  if (action === "env") {
+    runEnvAction(process.argv.slice(3));
+  } else if (action === "leases") {
+    await runLeasesAction(process.argv.slice(3));
+  } else if (action === "migrate-data") {
+    runMigrateDataAction(process.argv.slice(3));
+  } else if (action === "worker-image") {
+    // Build (or rebuild) a worker image without requiring loop configuration.
+    const provider = providerArg || "opencode";
+    if (!isLoopProvider(provider)) throw new Error("Expected --provider codex, claude, or opencode");
+    const image = tagArg || defaultWorkerImageTag(provider);
+    buildWorkerImage({ root, provider, image });
+    recordWorkerImage({ root, provider, image });
+    console.log(`Built worker image: ${image}`);
+    console.log("Recorded worker image; the loop supervisor will use it automatically.");
+  } else {
+    if (!ACTIONS.includes(action)) throw new Error("Expected loop start, status, intake, env, leases, migrate-data, or worker-image");
+    const config = JSON.parse(readFileSync(join(root, ".agents", "config.json"), "utf8"));
+    const mode = modeArg || config.loop?.mode || "off";
+    if (!["local", "fleet"].includes(mode)) throw new Error("Loop mode is off; configure an enabled loop mode first");
+    if (mode !== config.loop?.mode) throw new Error("Requested mode does not match configured authority");
+    const agent = config.loop?.agents?.lead;
+    const workers = config.loop?.agents?.workers ?? {};
+    if (!isLoopProvider(agent) || !Object.keys(workers).length || Object.entries(workers).some(([, value]) => !isLoopProvider(value))) throw new Error("Loop requires a configured lead and worker providers");
+    if (action === "resume") throw new Error("loop resume is removed; the daemon auto-resumes actionable tasks — run 'loop start', and re-activate a paused task from the dashboard (resume) or with the task status command");
+    if (mode === "local") requireLocalAuthority();
+    if (mode === "local" && action === "start") {
+      // Zero-config start: shell > AIDLC env file > values derived from the providers' own config.
+      const loaded = loadLoopEnv({ root, config });
+      for (const problem of loaded.problems) process.stderr.write(`loop: ${problem.level === "error" ? "error" : "warning"}: ${problem.message}\n`);
+      if (!loaded.ok) throw new Error("environment is incomplete; fix the errors above (check with: aidlc-kit loop env)");
+      Object.assign(process.env, loaded.applied);
+    }
+    if (mode === "local" && action === "status") {
+      const supervisor = await localSupervisor.createIsolatedLocalSupervisor({ root, taskId: requireTaskId(), agent, workers, workerImages: config.loop?.workerImage, onEvent: streamLog });
+      print(await supervisor.status());
     } else {
-      if (action === "resume") {
-        const recordPath = join(root, ".agents/data/tasks", taskId, "loop-intake.json");
-        if (!existsSync(recordPath)) throw new Error("Loop record missing; use start");
-        const record = JSON.parse(readFileSync(recordPath, "utf8"));
-        if (record.taskId !== taskId || record.authority !== "fleet") throw new Error("Loop record authority mismatch; use the recorded authority and task");
-      }
-      await callRemoteTool({ url, token }, "fleet_get", { workspace });
-      await readIntegrationCommit({ projectRoot: root, integrationBranch, gitRemote: env.AIDLC_FLEET_GIT_REMOTE ?? "origin" });
+      const authority = await createLoopAuthority({ root, config });
       if (action === "start") {
-        const requirement = await readRequirement();
-        const readTask = async (id) => { try { return (await callRemoteTool({ url, token }, "task_get", { workspace, taskId: id, clientProjectRoot: root })).task; } catch { return null; } };
-        const current = await callRemoteTool({ url, token }, "state_get", { workspace });
-        const actionable = Object.values(current?.state?.tasks ?? {}).filter((task) => task.id !== taskId && task.status === "active" && !task.handoff);
-        if (actionable.length) throw new Error(`Task create is blocked while other work is actionable: ${actionable.map((task) => task.id).join(", ")}`);
-        await prepareLoopIntake({ root, taskId, requirement, authority: "fleet", readTask, createTask: async ({ taskId: id, title }) => {
-          const claim = await repository.claimLead({ taskId: id, leaseMs: 60000 });
-          try {
-            execFileSync(process.execPath, [remoteState, "task", "create", id, "--title", title], { cwd: root, encoding: "utf8", env: { ...env, AIDLC_FLEET_LEAD_EPOCH: String(claim.epoch), AIDLC_FLEET_LEAD_OWNER_TOKEN: repository.leadOwnerToken() } });
-          } finally { await repository.releaseLead({ taskId: id, epoch: claim.epoch }); }
-        } });
+        // Two-stage shutdown: 1st signal stops after the current turn, 2nd cancels
+        // the in-flight agent turn, 3rd exits immediately. Runs end as `stopped`
+        // (tasks are not paused) and resume on the next daemon start.
+        const stop = new AbortController(), cancel = new AbortController();
+        let received = 0;
+        const onSignal = () => {
+          received += 1;
+          if (received === 1) { process.stderr.write("\nloop: stopping after the current turn — send the signal again (Ctrl-C) to cancel it\n"); stop.abort(); }
+          else if (received === 2) { process.stderr.write("\nloop: cancelling the in-flight turn — send the signal again to exit immediately\n"); cancel.abort(); }
+          else process.exit(130);
+        };
+        for (const name of ["SIGINT", "SIGTERM"]) process.on(name, onSignal);
+        if (typeof authority.preflight === "function") await authority.preflight();
+        print(await runLoopDaemon({ root, authority, pollMs: config.loop?.pollMs, signal: stop.signal, cancelSignal: cancel.signal, onEvent: streamLog }));
+      } else if (action === "intake") {
+        print(await authority.intake({ requirement: await readStdin("Requirement: "), taskId: taskArg || undefined, title: titleArg || undefined }));
+      } else if (action === "resume-task") {
+        print(await authority.resumeTask(requireTaskId()));
+      } else if (mode !== "fleet") {
+        throw new Error(`loop ${action} is a fleet dashboard action; local dashboards read canonical local state directly`);
+      } else if (action === "status") {
+        const taskId = requireTaskId();
+        const snapshot = await authority.getTask(taskId);
+        print({ taskId, authority: "fleet", task: snapshot.task, nextAction: snapshot.nextAction, checkpoint: await authority.repository.readGateCheckpoint({ taskId }) });
+      } else if (action === "tasks") {
+        print({ ok: true, authority: "fleet", tasks: await authority.listTasks() });
+      } else if (action === "task") {
+        print({ ok: true, authority: "fleet", ...(await authority.getTask(requireTaskId())) });
+      } else if (action === "gate") {
+        print({ ok: true, authority: "fleet", ...(await authority.gate(requireTaskId())) });
+      } else if (action === "approve") {
+        const taskId = requireTaskId();
+        print(await authority.approve({ taskId, source: (await readStdin("Approval source: ")).trim(), reviewerToken: process.env.AIDLC_FLEET_REVIEWER_TOKEN }));
+      } else if (action === "feedback") {
+        // Human guidance that keeps the task at its current gate; no reviewer credential is involved.
+        const taskId = requireTaskId();
+        let input; try { input = JSON.parse(await readStdin("Feedback JSON: ")); } catch { throw new Error("Feedback must be a JSON object { reason, source }"); }
+        const reason = typeof input?.reason === "string" ? input.reason.trim() : "", source = typeof input?.source === "string" ? input.source.trim() : "";
+        if (!input || typeof input !== "object" || Array.isArray(input) || !reason || !source) throw new Error("Feedback must be a JSON object { reason, source } with non-empty strings");
+        print(await authority.feedback({ taskId, reason, source }));
       }
-      await runFleetCli(["supervisor", taskId], { callTool, env, out: (line) => console.log(line) });
     }
-  } else {
-    requireLocalAuthority();
-    // The factory contract guarantees that the dispatcher is actually wired into
-    // the supervisor, not merely present in the package. No host fallback.
-    if (typeof localSupervisor.createIsolatedLocalSupervisor !== "function") throw new Error("Isolated local worker dispatcher is not integrated; loop execution is unavailable");
-    const supervisor = await localSupervisor.createIsolatedLocalSupervisor({ root, taskId, agent, workers: config.loop.agents.workers });
-    if (action === "status") {
-      console.log(JSON.stringify(await supervisor.status(), null, 2));
-    } else if (action === "start") {
-      const requirement = await readRequirement();
-      await prepareLoopIntake({ root, taskId, requirement, authority: "local", readTask: async (id) => loadTask(root, id), createTask: async ({ taskId: id, title }) => { execFileSync(process.execPath, [join(root, ".agents/aidlc/scripts/state.mjs"), "task", "create", id, "--title", title, "--root", root], { stdio: ["ignore", "pipe", "pipe"] }); } });
-      console.log(JSON.stringify(await supervisor.start(), null, 2));
-    } else console.log(JSON.stringify(await supervisor.resume(), null, 2));
   }
 } catch (error) { console.error(`loop: ${error.message}`); process.exitCode = 1; }