@felixdotgo/aidlc-kit 0.1.1 → 0.3.0

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

@@ -6,11 +6,15 @@ import { createHash, randomUUID } from "node:crypto";
 import { execFileSync } from "node:child_process";
 import { closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
-import { acquireLoopLease, assertLoopPath, readLiveLease } from "./loop-lease.mjs";
+import { acquireTaskLease, heldTaskLease, readLiveLease, readTaskLease } from "./loop-lease.mjs";
+import { resolveTaskRuntimeRead, taskRuntimePath } from "./task-runtime.mjs";
+import { migrateTaskRuntime } from "./task-runtime-migrate.mjs";
+import { explainHolder } from "./loop-holder.mjs";
 import { isLoopProvider, LOOP_PROVIDER_LIST } from "./loop-drivers.mjs";
+import { isLoopOperationalPath } from "./loop-git.mjs";
 
 export const DEFAULT_LIMITS = Object.freeze({ maxTurns: 12, turnTimeoutMs: 600000, maxStallTurns: 2 });
-const states = new Set(["running", "gate", "paused", "blocked", "terminal", "complete"]);
+const states = new Set(["running", "gate", "paused", "blocked", "terminal", "complete", "stopped"]);
 const hash = (value) => createHash("sha256").update(value).digest("hex");
 const iso = () => new Date().toISOString();
 const bounded = (value, name, max) => { const n = Number(value); if (!Number.isSafeInteger(n) || n < 1 || n > max) throw new Error(`${name} must be an integer from 1 to ${max}`); return n; };
@@ -34,7 +38,10 @@ export function validateRoot(root) {
   return absolute;
 }
 
-export const loopRecordPath = (root, taskId) => assertLoopPath(root, taskId);
+/** Write location of the loop run record (`.agents/data/tasks/<task>/runtime/run.json`). */
+export const loopRecordPath = (root, taskId) => taskRuntimePath(root, taskId, "run.json");
+/** Read location: the runtime record, else the pre-runtime `.agents/data/loop/<task>.json`. */
+export const loopRecordReadPath = (root, taskId) => resolveTaskRuntimeRead(root, taskId, "run.json");
 
 function validateRecord(value, taskId) {
   if (!value || value.schemaVersion !== 1 || value.taskId !== taskId || typeof value.runId !== "string" || !value.runId || !isLoopProvider(value.agent) || !states.has(value.status) || !Number.isSafeInteger(value.iteration) || value.iteration < 0 || !Number.isSafeInteger(value.stallTurns) || value.stallTurns < 0 || (value.sessionId !== null && (typeof value.sessionId !== "string" || !value.sessionId)) || !value.limits || !value.updatedAt || Number.isNaN(Date.parse(value.updatedAt))) throw new Error(`Corrupt loop run record for ${taskId}`);
@@ -45,7 +52,7 @@ function validateRecord(value, taskId) {
 }
 
 export function readLoopRecord(root, taskId) {
-  const path = loopRecordPath(root, taskId);
+  const path = loopRecordReadPath(root, taskId);
   try { lstatSync(path); } catch (error) { if (error?.code === "ENOENT") return null; throw error; }
   let value;
   try { value = JSON.parse(readFileSync(path, "utf8")); }
@@ -55,6 +62,7 @@ export function readLoopRecord(root, taskId) {
 
 export function writeLoopRecord(root, record) {
   validateRecord(record, record.taskId);
+  migrateTaskRuntime(root, record.taskId, { names: ["run.json"] });
   const path = loopRecordPath(root, record.taskId);
   mkdirSync(dirname(path), { recursive: true });
   const temporary = `${path}.tmp-${process.pid}-${randomUUID()}`;
@@ -114,7 +122,7 @@ function worktreeSignal(root) {
     const status = entry.slice(0, 2);
     let name = entry.slice(3);
     if (/^[RC]/.test(status) || /[RC]$/.test(status)) name = entries[++i] ?? name;
-    if (name.startsWith(".agents/data/loop/")) continue;
+    if (isLoopOperationalPath(name)) continue;
     const path = resolve(root, name);
     if (!path.startsWith(`${root}/`)) return { kind: "unknown", reason: "unsafe changed path" };
     try {
@@ -152,9 +160,31 @@ export const classifyAction = (action) => {
 };
 
 function approvalCount(task) { return task.evidence.filter((item) => item.kind === "approval" && item.result === "pass").length; }
+function pendingFeedback(task) {
+  const evidence = Array.isArray(task?.evidence) ? task.evidence : [];
+  const pending = [];
+  for (let i = 0; i < evidence.length; i++) {
+    const entry = evidence[i];
+    if (entry?.kind !== "diagnostic" || typeof entry.detail !== "string") continue;
+    const match = entry.detail.match(/^Cancelled gate wait at (G0_confirm|G1_review|G2_codereview): /);
+    if (!match) continue;
+    const approvedAfter = evidence.slice(i + 1).some((later) => later?.kind === "approval" && later.result === "pass" && later.gate === match[1]);
+    if (!approvedAfter) pending.push(entry.detail);
+  }
+  return pending;
+}
 function outputStop(record, action, gateView) { return { taskId: record.taskId, runId: record.runId, status: record.status, iteration: record.iteration, sessionId: record.sessionId, stopReason: record.stopReason, nextAction: action, ...(gateView ? { gateView } : {}) }; }
 
-export async function runLoop({ root: rootInput, taskId, agent, mode = "run", limits: limitInput, driver, onEvent = () => {}, preflight = false, precondition }) {
+/**
+ * `signal` requests a graceful stop at the next turn boundary; `cancelSignal`
+ * additionally cancels the in-flight agent turn. Either way the run ends as
+ * `stopped` (the canonical task is NOT paused) and a later resume continues
+ * from fresh canonical nextAction. A failure observed while stopping is a
+ * shutdown side effect (a terminal Ctrl-C also reaches the agent child), not a
+ * transport failure, so it never pauses the task.
+ */
+export async function runLoop({ root: rootInput, taskId, agent, mode = "run", limits: limitInput, driver, dispatchBuild, onEvent = () => {}, preflight = false, precondition, signal: stopSignal, cancelSignal }) {
+  const stopping = () => Boolean(stopSignal?.aborted || cancelSignal?.aborted);
   const root = validateRoot(rootInput);
   // --- Validate mode and load/create the loop record -------------------------
   let record = readLoopRecord(root, taskId);
@@ -171,7 +201,16 @@ export async function runLoop({ root: rootInput, taskId, agent, mode = "run", li
   if (preflight) checkAgent(record?.agent ?? agent, root);
   if (!record) record = { schemaVersion: 1, taskId, runId: randomUUID(), agent, status: "running", sessionId: null, iteration: 0, stallTurns: 0, limits, lastFingerprint: null, checkpoint: null, stopReason: null, pausedByLoop: false, updatedAt: iso() };
   else { const prior = { iteration: record.iteration, status: record.status, stopReason: record.stopReason, limits: record.limits }; record.limits = limits; record.stallTurns = 0; onEvent({ type: "resume", prior }); }
-  const release = acquireLoopLease(root, taskId, record.runId);
+  // The task lease: shared with the supervisor that drives this run (activity
+  // flips waiting -> turn -> waiting), or acquired here for a manual
+  // `loop.mjs run|resume` (activity turn). While activity is "turn",
+  // `state.mjs gate approve` refuses to approve.
+  const shared = heldTaskLease(root, taskId);
+  const lease = shared ?? acquireTaskLease(root, taskId, { activity: "turn", label: "loop runner", purpose: `loop run ${record.runId}`, onWarning: onEvent });
+  if (shared) {
+    try { shared.setActivity("turn"); }
+    catch (error) { try { shared.setActivity("waiting"); } catch { /* the next heartbeat writes the requested activity */ } throw error; }
+  }
   try {
     let current = readCanonical(root, taskId);
     if (precondition) {
@@ -186,6 +225,10 @@ export async function runLoop({ root: rootInput, taskId, agent, mode = "run", li
       envelope(root, "state.mjs", ["task", "status", taskId, "--status", "active"]);
       record.pausedByLoop = false;
       current = readCanonical(root, taskId);
+    } else if (mode === "resume" && record.pausedByLoop && current.task.status === "active") {
+      // A human (CLI or dashboard) already re-activated the task: the loop no
+      // longer owns that pause, so a later human pause must not be auto-undone.
+      record.pausedByLoop = false;
     }
     const initial = fingerprint(root, current.task, current.action);
     if (mode === "resume" && record.lastFingerprint && record.lastFingerprint !== initial.digest) onEvent({ type: "context_changed", message: "Canonical task context changed since the last checkpoint; continuing from fresh nextAction", previousCheckpointAt: record.checkpoint?.capturedAt ?? null });
@@ -193,7 +236,12 @@ export async function runLoop({ root: rootInput, taskId, agent, mode = "run", li
     record.checkpoint = checkpoint(current.task, current.action, initial.tree, record.iteration);
     record.status = "running"; record.stopReason = null; record.updatedAt = iso(); writeLoopRecord(root, record);
     // --- Main turn loop --------------------------------------------------------
+    // maxTurns bounds one runLoop invocation (a supervised run), not the task's
+    // lifetime: record.iteration stays a cumulative observability counter, so a
+    // long multi-gate task is not permanently re-paused on every resume.
+    let runTurns = 0;
   for (;;) {
+      lease.assertOwned();
       const kind = classifyAction(current.action);
       if (kind !== "run_phase") {
         record.status = kind === "await_user" ? "gate" : kind;
@@ -202,39 +250,82 @@ export async function runLoop({ root: rootInput, taskId, agent, mode = "run", li
         const gateView = kind === "await_user" ? cli(root, "gate-view.mjs", [taskId]).trim() : undefined;
         return outputStop(record, current.action, gateView);
       }
-      if (record.iteration >= limits.maxTurns) return pause("turn limit reached");
+      if (stopping()) return stop(cancelSignal?.aborted ? "daemon cancelled the run" : "daemon shutdown");
+      if (runTurns >= limits.maxTurns) return pause("turn limit reached");
+      if (dispatchBuild && current.task.phase === "build" && current.task.tasks.some((item) => item.status === "todo" || item.status === "in_progress")) {
+        try {
+          await dispatchBuild({ root, taskId, task: current.task, action: current.action, record });
+        } catch (error) {
+          if (stopping()) return stop("daemon shutdown interrupted build dispatch");
+          return pause(`build dispatch failure: ${error.message}`);
+        }
+        const refreshed = readCanonical(root, taskId);
+        const signal = fingerprint(root, refreshed.task, refreshed.action);
+        record.iteration += 1; runTurns += 1;
+        record.stallTurns = signal.digest === record.lastFingerprint ? record.stallTurns + 1 : 0;
+        record.lastFingerprint = signal.digest;
+        record.checkpoint = checkpoint(refreshed.task, refreshed.action, signal.tree, record.iteration);
+        record.updatedAt = iso(); writeLoopRecord(root, record);
+        current = refreshed;
+        if (stopping()) continue; // the loop top records `stopped` (or the reached stop) instead of a stall pause
+        if (classifyAction(current.action) === "run_phase" && record.stallTurns >= limits.maxStallTurns) return pause(`${record.stallTurns} consecutive turns without observable progress`);
+        continue;
+      }
       let prompt;
       try {
         const packet = JSON.parse(cli(root, "context.mjs", [taskId, "--phase", current.action.phase, ...(current.action.itemId ? ["--item", current.action.itemId] : []), "--format", "json"]));
         if (typeof packet?.content !== "string" || !packet.content.trim()) throw new Error("Context packet was empty or invalid");
         prompt = packet.content;
       } catch {
+        // A terminal Ctrl-C also kills the context.mjs child: that is a shutdown, not a broken packet.
+        if (stopping()) return stop("daemon shutdown interrupted context generation");
         // No driver has started for this turn, so it is safe to resume after repairing context.
         // Do not persist arbitrary subprocess output or malformed context in the stop reason.
         return pause("context packet generation or validation failed; inspect context.mjs and resume after repair");
       }
+      const feedback = pendingFeedback(current.task);
+      if (feedback.length) {
+        prompt = `Human feedback (revise the current review artifact accordingly, then re-present the gate):\n${feedback.map((text) => `- ${text}`).join("\n")}\n\n${prompt}`;
+      }
       const beforeApprovals = approvalCount(current.task);
+      // Live-log context: every event of this lead turn names its actor, phase, and item.
+      const turnContext = { taskId, actor: "lead", phase: current.action.phase, ...(typeof current.action.itemId === "string" && current.action.itemId ? { itemId: current.action.itemId } : {}) };
+      const leadEvent = (event) => onEvent(event && typeof event === "object" && !Array.isArray(event) ? { ...turnContext, ...event } : event);
+      leadEvent({ type: "turn_start", iteration: record.iteration, agent: record.agent });
       let observedId = record.sessionId;
       try {
-        const result = await driver({ agent: record.agent, root, sessionId: record.sessionId ?? undefined, prompt: `${prompt}\n\nLoop supervisor: complete the current authorized phase or item. Use canonical lifecycle commands for evidence and gates. Never approve a human gate. Stop at a gate and report progress.`, timeoutMs: limits.turnTimeoutMs, onSessionId: (id) => { if (typeof id !== "string" || !id) throw new Error("Invalid agent session id"); observedId = id; record.sessionId = id; record.updatedAt = iso(); writeLoopRecord(root, record); }, onEvent: (event) => { onEvent(event); if (event?.type === "lifecycle_command") { const observed = readCanonical(root, taskId); const signal = fingerprint(root, observed.task, observed.action); record.checkpoint = checkpoint(observed.task, observed.action, signal.tree, record.iteration); record.updatedAt = iso(); writeLoopRecord(root, record); } } });
+        const result = await driver({ agent: record.agent, root, sessionId: record.sessionId ?? undefined, prompt: `${prompt}\n\nLoop supervisor: complete the current authorized phase or item. Use canonical lifecycle commands for evidence and gates. Never approve a human gate. Stop at a gate and report progress.`, timeoutMs: limits.turnTimeoutMs, ...(cancelSignal ? { signal: cancelSignal } : {}), onSessionId: (id) => { if (typeof id !== "string" || !id) throw new Error("Invalid agent session id"); observedId = id; record.sessionId = id; record.updatedAt = iso(); writeLoopRecord(root, record); }, onEvent: (event) => { leadEvent(event); if (event?.type === "lifecycle_command") { const observed = readCanonical(root, taskId); const signal = fingerprint(root, observed.task, observed.action); record.checkpoint = checkpoint(observed.task, observed.action, signal.tree, record.iteration); record.updatedAt = iso(); writeLoopRecord(root, record); } } });
         if (!observedId && result?.sessionId) { observedId = result.sessionId; record.sessionId = observedId; record.updatedAt = iso(); writeLoopRecord(root, record); }
         if (!observedId) throw new Error("Agent turn ended without a resumable session id");
       } catch (error) {
         current = readCanonical(root, taskId);
         if (classifyAction(current.action) === "await_user") continue;
+        if (stopping()) return stop(cancelSignal?.aborted ? "daemon cancelled the in-flight turn" : "daemon shutdown interrupted the turn");
         return pause(`agent transport failure: ${error.message}`);
       }
+      leadEvent({ type: "turn_end", iteration: record.iteration });
       const refreshed = readCanonical(root, taskId);
       if (approvalCount(refreshed.task) !== beforeApprovals) return pause("Approval evidence changed during an agent turn");
       const signal = fingerprint(root, refreshed.task, refreshed.action);
-      record.iteration += 1;
+      record.iteration += 1; runTurns += 1;
       record.stallTurns = signal.digest === record.lastFingerprint ? record.stallTurns + 1 : 0;
       record.lastFingerprint = signal.digest;
       record.checkpoint = checkpoint(refreshed.task, refreshed.action, signal.tree, record.iteration);
       record.updatedAt = iso(); writeLoopRecord(root, record);
       current = refreshed;
+      if (stopping()) continue; // the loop top records `stopped` (or the reached stop) instead of a stall pause
       if (classifyAction(current.action) === "run_phase" && record.stallTurns >= limits.maxStallTurns) return pause(`${record.stallTurns} consecutive turns without observable progress`);
     }
+    function stop(reason) {
+      const stopped = readCanonical(root, taskId);
+      const signal = fingerprint(root, stopped.task, stopped.action);
+      record.status = "stopped"; record.stopReason = reason;
+      record.lastFingerprint = signal.digest;
+      record.checkpoint = checkpoint(stopped.task, stopped.action, signal.tree, record.iteration, reason);
+      record.updatedAt = iso(); writeLoopRecord(root, record);
+      onEvent({ type: "loop_stopped", taskId, reason });
+      return outputStop(record, stopped.action);
+    }
     function pause(reason) {
       const fresh = readCanonical(root, taskId);
       record.status = "paused"; record.stopReason = reason;
@@ -249,12 +340,23 @@ export async function runLoop({ root: rootInput, taskId, agent, mode = "run", li
       record.updatedAt = iso(); writeLoopRecord(root, record);
       return outputStop(record, stopped.action);
     }
-  } finally { release(); }
+  } finally {
+    if (!shared) lease.release();
+    else {
+      // Back to "waiting" so a human can approve the gate this run stopped at.
+      // If the write fails (guard timeout), the requested activity is kept and
+      // written by the next heartbeat; a lost lease is reported by the
+      // supervisor's next assertOwned.
+      try { shared.setActivity("waiting"); } catch (error) { onEvent({ type: "diagnostic", message: `Task lease not yet returned to waiting (retried by the next heartbeat): ${error.message}` }); }
+    }
+  }
 }
 
 export function loopStatus(rootInput, taskId) {
   const root = validateRoot(rootInput);
   const record = readLoopRecord(root, taskId);
   const current = readCanonical(root, taskId);
-  return { record, liveLease: readLiveLease(root, taskId), nextAction: current.action };
+  const entry = readTaskLease(root, taskId);
+  const lease = { state: entry.state, path: entry.path, holder: entry.holder, reason: entry.reason, ...explainHolder(entry) };
+  return { record, liveLease: entry.state === "corrupt" ? null : readLiveLease(root, taskId), lease, nextAction: current.action };
 }

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

@@ -0,0 +1,117 @@
+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();
+
+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; }
+    rotate(path, EVENT_LOG_MAX_BYTES);
+    const record = event && typeof event === "object" && !Array.isArray(event) && !("at" in event) ? { at: new Date().toISOString(), ...event } : event;
+    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);
+  if (!event || typeof event.type !== "string") return;
+  switch (event.type) {
+    case "turn_start":
+      process.stderr.write(`\n━━ turn ${Number(event.iteration ?? 0) + 1} · phase ${event.phase ?? "?"} · agent ${event.agent ?? "?"} ━━\n`);
+      break;
+    case "turn_end":
+      process.stderr.write(`━━ turn done ━━\n`);
+      break;
+    case "agent_text":
+      process.stderr.write(`${event.text ?? ""}\n`);
+      break;
+    case "agent_tool":
+      process.stderr.write(`  › tool: ${event.tool ?? "?"}${withSummary(event, " · ")}\n`);
+      break;
+    case "lifecycle_command":
+      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`);
+      break;
+    case "loop_stopped":
+      process.stderr.write(`  ■ ${event.taskId ?? "?"} stopped: ${event.reason ?? ""}\n`);
+      break;
+    case "gate":
+      process.stderr.write(`\n${event.gateView ?? `Gate ${event.gate ?? "?"} reached — approve from the trusted terminal.`}\n`);
+      break;
+    case "worker_image_build":
+      process.stderr.write(`\n▶ building worker image ${event.image ?? "?"} (provider ${event.provider ?? "?"})…\n`);
+      break;
+    default:
+      break;
+  }
+}

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 {