@felixdotgo/aidlc-kit 0.1.1 → 0.3.0

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

@@ -0,0 +1,376 @@
+// One holder-file primitive for every local loop lease and lock.
+//
+// Vocabulary (shown to users):
+//   lock  — short mutex held only while a file is read-modified-written.
+//   lease — process ownership (the loop daemon, a task's loop run).
+//   claim — a worker's ownership of an item/paths (local assignment, fleet job).
+//
+// A holder file is JSON v2:
+//   {schemaVersion:2, kind:"lease"|"lock", scope, pid, host, command, purpose,
+//    activity, token, startedAt, heartbeatAt, expiresAt}
+// It is live when expiresAt is in the future AND, on the same host, its pid is
+// alive. A holder on another host is judged by TTL only. v1 files (written by
+// older versions) are still read; their liveness is the old pid probe.
+// Reclaims, heartbeats, and releases are serialized by `<path>.guard`.
+import { randomUUID } from "node:crypto";
+import { closeSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { hostname } from "node:os";
+import { basename, dirname } from "node:path";
+
+export const LEASE_TTL_MS = 60000;
+export const LEASE_HEARTBEAT_MS = 15000;
+export const LOCK_TTL_MS = 30000;
+export const GUARD_STALE_MS = 10000;
+export const GUARD_WAIT_MS = 5000;
+export const LEASES_COMMAND = "node .agents/aidlc/scripts/loop-entry.mjs leases";
+export const CLEAR_STALE_COMMAND = `${LEASES_COMMAND} --clear-stale`;
+
+const KINDS = new Set(["lease", "lock"]);
+const sleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+const iso = (ms) => new Date(ms).toISOString();
+const isIso = (value) => typeof value === "string" && !Number.isNaN(Date.parse(value));
+const ignoreMissing = (action) => { try { return action(); } catch (error) { if (error?.code !== "ENOENT") throw error; return undefined; } };
+
+export const currentHost = () => hostname();
+
+export function pidAlive(pid) {
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return error?.code !== "ESRCH"; }
+}
+
+export function formatAge(ms) {
+  if (!Number.isFinite(ms)) return "unknown";
+  const seconds = Math.max(0, Math.round(ms / 1000));
+  if (seconds < 120) return `${seconds}s`;
+  const minutes = Math.round(seconds / 60);
+  if (minutes < 120) return `${minutes}m`;
+  return `${Math.round(minutes / 60)}h`;
+}
+
+function defaultCommand() {
+  const script = process.argv[1] ? basename(process.argv[1]) : "node";
+  return [script, ...process.argv.slice(2, 4)].join(" ").slice(0, 120);
+}
+
+/** Error raised by acquire when a holder blocks the caller. `code` is
+ * HOLDER_BUSY (live holder) or HOLDER_CORRUPT (unreadable, recent file). */
+export class HolderError extends Error {
+  constructor(message, code, entry) { super(message); this.name = "HolderError"; this.code = code; this.entry = entry; }
+}
+
+function validV2(value) {
+  return value && value.schemaVersion === 2 && KINDS.has(value.kind) && typeof value.scope === "string" && value.scope
+    && Number.isSafeInteger(value.pid) && value.pid > 0 && typeof value.host === "string" && value.host
+    && typeof value.token === "string" && value.token && isIso(value.startedAt) && isIso(value.heartbeatAt) && isIso(value.expiresAt)
+    && (value.activity === null || value.activity === undefined || typeof value.activity === "string");
+}
+
+// Any older holder shape that carries a positive pid and a token (loop lease
+// v1, supervisor lease, daemon lock v1, assignment lock). Liveness is pid-only.
+function validV1(value) {
+  return value && value.schemaVersion !== 2 && Number.isSafeInteger(value.pid) && value.pid > 0 && typeof value.token === "string" && value.token;
+}
+
+/** Inspect a holder file without changing it.
+ * Returns `{state: "absent"|"live"|"stale"|"corrupt", path, holder, version,
+ * reason, ageMs, reclaimable}`. `reclaimable` is true for stale holders and for
+ * corrupt files older than `ttlMs` (default: lease TTL). */
+export function readHolder(path, { ttlMs = LEASE_TTL_MS, now = Date.now() } = {}) {
+  let stat;
+  try { stat = lstatSync(path); }
+  catch (error) { if (error?.code === "ENOENT") return { state: "absent", path, holder: null, version: null, reason: "no holder file", ageMs: null, reclaimable: false }; throw error; }
+  if (stat.isSymbolicLink()) throw new Error(`Holder file is a symlink: ${path}`);
+  const ageMs = now - stat.mtimeMs;
+  let raw;
+  try { raw = readFileSync(path, "utf8"); }
+  catch (error) { if (error?.code === "ENOENT") return { state: "absent", path, holder: null, version: null, reason: "no holder file", ageMs: null, reclaimable: false }; throw error; }
+  let value;
+  try { value = JSON.parse(raw); } catch { value = null; }
+  if (validV2(value)) {
+    const expired = Date.parse(value.expiresAt) <= now;
+    const sameHost = value.host === currentHost();
+    const dead = sameHost && !pidAlive(value.pid);
+    const reason = expired ? `expired ${formatAge(now - Date.parse(value.expiresAt))} ago` : dead ? `pid ${value.pid} is not running` : "held";
+    const state = expired || dead ? "stale" : "live";
+    return { state, path, holder: value, version: 2, reason, ageMs, reclaimable: state === "stale" };
+  }
+  if (validV1(value)) {
+    const live = pidAlive(value.pid);
+    return { state: live ? "live" : "stale", path, holder: value, version: 1, reason: live ? "held (v1 file, pid probe only)" : `pid ${value.pid} is not running (v1 file)`, ageMs, reclaimable: !live };
+  }
+  return { state: "corrupt", path, holder: null, version: null, reason: raw.trim() ? "unreadable holder file" : "empty holder file", ageMs, reclaimable: ageMs > ttlMs };
+}
+
+/** Human explanation of a `readHolder` entry: `{ summary, remedy }`. */
+export function explainHolder(entry) {
+  const holder = entry?.holder;
+  if (!entry || entry.state === "absent") return { summary: `No holder at ${entry?.path ?? "(unknown)"}`, remedy: null };
+  if (entry.state === "corrupt") {
+    return {
+      summary: `Corrupt holder file ${entry.path} (modified ${formatAge(entry.ageMs)} ago)`,
+      remedy: entry.reclaimable ? `It is older than its TTL: reclaimed automatically on the next acquire, or run: ${CLEAR_STALE_COMMAND}` : `It becomes reclaimable once older than its TTL; if no loop process is running, run: ${CLEAR_STALE_COMMAND} after that`,
+    };
+  }
+  const kind = holder.kind ?? "holder";
+  const scope = holder.scope ?? (holder.taskId ? `task:${holder.taskId}` : basename(entry.path));
+  const where = holder.host ? ` on ${holder.host}` : "";
+  const detail = [holder.command, holder.activity].filter(Boolean).join(", ");
+  const since = holder.startedAt ?? holder.createdAt;
+  const parts = [`${kind} ${scope} is held by pid ${holder.pid}${where}${detail ? ` (${detail})` : ""}`];
+  if (since) parts.push(`since ${typeof since === "number" ? iso(since) : since}`);
+  if (holder.expiresAt) parts.push(`expires ${holder.expiresAt}`);
+  if (entry.state === "stale") {
+    return { summary: `Stale ${parts.join(", ")} — ${entry.reason}`, remedy: `Reclaimed automatically on the next acquire, or run: ${CLEAR_STALE_COMMAND}` };
+  }
+  return { summary: parts.join(", "), remedy: `Inspect: ${LEASES_COMMAND}` };
+}
+
+/** One-line message for a holder that blocks the caller. */
+export function describeHolder(entry) {
+  const { summary, remedy } = explainHolder(entry);
+  return remedy ? `${summary}. ${remedy}` : summary;
+}
+
+// ---------------------------------------------------------------- guard ----
+
+/** Inspect a `<path>.guard` file: null when absent, else `{ live, token, ageMs }`. */
+export function readGuard(path, now = Date.now()) { return guardLive(path, now); }
+
+function guardLive(path, now) {
+  let stat;
+  try { stat = lstatSync(path); } catch (error) { if (error?.code === "ENOENT") return null; throw error; }
+  const ageMs = now - stat.mtimeMs;
+  let pid = null, token = null;
+  try {
+    const value = JSON.parse(readFileSync(path, "utf8"));
+    if (Number.isSafeInteger(value)) pid = value;
+    else if (value && Number.isSafeInteger(value.pid)) { pid = value.pid; token = typeof value.token === "string" ? value.token : null; }
+  } catch (error) { if (error?.code === "ENOENT") return null; }
+  // A guard is live only while its pid runs and it is younger than 10s; an
+  // unreadable guard is judged by age alone.
+  const live = ageMs < GUARD_STALE_MS && (pid === null || pidAlive(pid));
+  return { live, token, ageMs };
+}
+
+/** Run `action` while holding `<path>.guard`. Waits up to 5s for a live guard;
+ * an abandoned guard (dead pid or older than 10s) is removed. */
+export function withHolderGuard(path, action, { waitMs = GUARD_WAIT_MS } = {}) {
+  const guard = `${path}.guard`;
+  mkdirSync(dirname(guard), { recursive: true });
+  const token = randomUUID();
+  const deadline = Date.now() + waitMs;
+  for (;;) {
+    try {
+      const fd = openSync(guard, "wx", 0o600);
+      try { writeFileSync(fd, `${JSON.stringify({ pid: process.pid, token, createdAt: new Date().toISOString() })}\n`); }
+      finally { closeSync(fd); }
+      break;
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+      const observed = guardLive(guard, Date.now());
+      if (!observed) continue;
+      if (!observed.live) {
+        const again = guardLive(guard, Date.now());
+        if (again && !again.live && again.token === observed.token) ignoreMissing(() => unlinkSync(guard));
+        continue;
+      }
+      if (Date.now() >= deadline) throw new Error(`Timed out waiting for holder guard ${guard}; if no loop process is running, run: ${CLEAR_STALE_COMMAND}`);
+      sleep(10);
+    }
+  }
+  try { return action(); }
+  finally {
+    let current = null;
+    try { current = JSON.parse(readFileSync(guard, "utf8")); } catch { current = null; }
+    if (current?.token === token) ignoreMissing(() => unlinkSync(guard));
+  }
+}
+
+// ---------------------------------------------------------------- write ----
+
+// A complete, fsynced temp file next to `path`; removed again if writing fails.
+function writeTemporary(path, value) {
+  const temporary = `${path}.tmp-${process.pid}-${randomUUID()}`;
+  const fd = openSync(temporary, "wx", 0o600);
+  try { writeFileSync(fd, `${JSON.stringify(value)}\n`); fsyncSync(fd); }
+  catch (error) { closeSync(fd); ignoreMissing(() => unlinkSync(temporary)); throw error; }
+  closeSync(fd);
+  return temporary;
+}
+
+function createExclusive(path, value) {
+  // Write a complete temp file, then hard-link it into place so readers never
+  // observe a partial holder and an existing holder is never overwritten.
+  const temporary = writeTemporary(path, value);
+  try { linkSync(temporary, path); }
+  catch (error) {
+    if (error?.code === "EEXIST") throw error;
+    // Filesystems without hard links: fall back to an exclusive create.
+    const direct = openSync(path, "wx", 0o600);
+    try { writeFileSync(direct, `${JSON.stringify(value)}\n`); fsyncSync(direct); } finally { closeSync(direct); }
+  } finally { ignoreMissing(() => unlinkSync(temporary)); }
+}
+
+function replaceAtomic(path, value) {
+  const temporary = writeTemporary(path, value);
+  try { renameSync(temporary, path); }
+  catch (error) { ignoreMissing(() => unlinkSync(temporary)); throw error; }
+}
+
+function readOwnToken(path) {
+  try {
+    const value = JSON.parse(readFileSync(path, "utf8"));
+    return validV2(value) ? value : null;
+  } catch { return null; }
+}
+
+/** Remove a stale or old-corrupt holder after re-reading it under the guard.
+ * Never removes a live holder. Returns the removed entry or null. */
+export function clearStaleHolder(path, { ttlMs = LEASE_TTL_MS } = {}) {
+  return withHolderGuard(path, () => {
+    const entry = readHolder(path, { ttlMs });
+    if (!entry.reclaimable) return null;
+    ignoreMissing(() => unlinkSync(path));
+    return entry;
+  });
+}
+
+/** Acquire a holder file.
+ * Options: path, kind ("lease"|"lock"), scope, ttlMs, heartbeatMs (leases),
+ * purpose, command, activity, waitMs (keep retrying a live holder), onWarning,
+ * onLost(reason) (called once when a heartbeat finds the holder taken over or
+ * removed), busyMessage(entry) to customize the HOLDER_BUSY error text.
+ * Returns `{ token, path, holder(), heartbeat(), setActivity(a), assertOwned(),
+ * release() }`. */
+export function acquireHolder({
+  path, kind, scope, ttlMs = kind === "lock" ? LOCK_TTL_MS : LEASE_TTL_MS,
+  heartbeatMs = kind === "lease" ? LEASE_HEARTBEAT_MS : 0, purpose = "", command = defaultCommand(),
+  activity = null, waitMs = 0, onWarning = () => {}, onLost = () => {}, busyMessage = null,
+}) {
+  if (!KINDS.has(kind)) throw new Error(`Invalid holder kind: ${kind}`);
+  if (typeof scope !== "string" || !scope) throw new Error("Holder scope is required");
+  if (!Number.isSafeInteger(ttlMs) || ttlMs < 1000) throw new Error("Holder ttlMs must be at least 1000");
+  mkdirSync(dirname(path), { recursive: true });
+  const token = randomUUID();
+  const startedAt = new Date().toISOString();
+  let current = null;
+  let lost = null;
+  // The last requested activity. Every renewal writes it, so a setActivity
+  // whose write failed (guard timeout) still converges on the next heartbeat.
+  let desiredActivity = activity;
+  let timer = null;
+  const build = (patch = {}) => {
+    const now = Date.now();
+    return { schemaVersion: 2, kind, scope, pid: process.pid, host: currentHost(), command, purpose, activity, token, startedAt, ...current, ...patch, activity: desiredActivity, heartbeatAt: iso(now), expiresAt: iso(now + ttlMs) };
+  };
+  const deadline = Date.now() + waitMs;
+  for (;;) {
+    const outcome = withHolderGuard(path, () => {
+      const entry = readHolder(path, { ttlMs });
+      if (entry.state === "live") return { blocked: entry };
+      if (entry.state === "corrupt" && !entry.reclaimable) {
+        throw new HolderError(`Corrupt ${kind} file ${path} (modified ${formatAge(entry.ageMs)} ago); it is reclaimed automatically once older than ${formatAge(ttlMs)}. If no loop process is running, run: ${CLEAR_STALE_COMMAND} after that`, "HOLDER_CORRUPT", entry);
+      }
+      if (entry.state === "stale" && entry.version === 2 && entry.holder.scope !== scope) throw new Error(`Conflicting holder scope in ${path}: ${entry.holder.scope} (expected ${scope})`);
+      if (entry.state !== "absent") {
+        ignoreMissing(() => unlinkSync(path));
+        onWarning({ type: "holder_reclaimed", path, previous: entry.holder, reason: entry.reason });
+      }
+      const value = build();
+      createExclusive(path, value);
+      return { value };
+    });
+    if (outcome.value) { current = outcome.value; break; }
+    if (Date.now() >= deadline) {
+      const message = busyMessage ? busyMessage(outcome.blocked) : describeHolder(outcome.blocked);
+      throw new HolderError(message, "HOLDER_BUSY", outcome.blocked);
+    }
+    sleep(10);
+  }
+
+  const lose = (reason) => {
+    const first = lost === null;
+    lost ??= reason;
+    if (timer) { clearInterval(timer); timer = null; }
+    if (first && reason !== "released") { try { onLost(reason); } catch (error) { onWarning({ type: "holder_lost_callback_failed", path, error: error.message }); } }
+  };
+  const renew = (patch) => withHolderGuard(path, () => {
+    const onDisk = readOwnToken(path);
+    if (!onDisk || onDisk.token !== token || onDisk.pid !== process.pid) {
+      const entry = readHolder(path, { ttlMs });
+      lose(entry.state === "absent" ? `${kind} file ${path} was removed` : `${kind} ${scope} was taken over: ${describeHolder(entry)}`);
+      return false;
+    }
+    const next = build(patch);
+    replaceAtomic(path, next);
+    current = next;
+    return true;
+  });
+  const handle = {
+    token,
+    path,
+    holder: () => current,
+    heartbeat() {
+      if (lost) return false;
+      try { return renew(); }
+      catch (error) { onWarning({ type: "holder_heartbeat_failed", path, error: error.message }); return false; }
+    },
+    setActivity(next) {
+      handle.assertOwned();
+      desiredActivity = next;
+      if (!renew()) handle.assertOwned();
+    },
+    assertOwned() {
+      if (lost) throw new Error(`${kind} ownership lost: ${lost}`);
+      const onDisk = readOwnToken(path);
+      if (!onDisk || onDisk.token !== token || onDisk.pid !== process.pid) {
+        const entry = readHolder(path, { ttlMs });
+        lose(entry.state === "absent" ? `${kind} file ${path} was removed` : `${kind} ${scope} was taken over: ${describeHolder(entry)}`);
+        throw new Error(`${kind} ownership lost: ${lost}`);
+      }
+      // An expired holder can be reclaimed by anyone; renew under the guard
+      // (which also re-checks the token) before allowing a mutation.
+      if (Date.parse(onDisk.expiresAt) <= Date.now() && !renew()) throw new Error(`${kind} ownership lost: ${lost}`);
+    },
+    release() {
+      if (timer) { clearInterval(timer); timer = null; }
+      if (lost === "released") return;
+      try {
+        withHolderGuard(path, () => {
+          if (readOwnToken(path)?.token === token) ignoreMissing(() => unlinkSync(path));
+        });
+      } finally { lost = "released"; }
+    },
+  };
+  if (heartbeatMs > 0) {
+    timer = setInterval(() => { handle.heartbeat(); }, heartbeatMs);
+    timer.unref?.();
+  }
+  return handle;
+}
+
+// ---------------------------------------------------------------- fleet ----
+
+const FLEET_EXPLANATIONS = [
+  [/stale or expired lead claim/, "the lead lease (run_claim) is no longer valid: the `loop start` process on the lead machine stopped, lost its connection, or another lead took over; restart the loop on the lead machine"],
+  [/stale or expired bound supervisor claim|stale or expired supervisor claim/, "the fleet supervisor lease expired or was taken over; only one `loop start` may supervise a task, restart it on one machine"],
+  [/supervisor or prior lead claim is held/, "another `loop start` still holds the supervisor or lead lease for this task; stop it or wait for its lease to expire (5 minutes without heartbeat)"],
+  [/lead claim is held/, "another lead holds the lead lease (run_claim) for this task; stop it or wait for its lease to expire (5 minutes without heartbeat)"],
+  [/stale or expired job claim/, "this worker's job claim expired or was reassigned; its result is not accepted, the lead must reconcile the job"],
+  [/expired job lease requires lead reconciliation|job requires lead reconciliation/, "the job claim expired before the worker reported; the lead must reconcile the job before it can be retried"],
+  [/job lease is held/, "a worker still holds the job claim for this item; wait for it to report or for its claim to expire"],
+  [/job lead lease is stale/, "the job was created under an older lead lease; the current lead must reconcile it"],
+  [/item already has an active job/, "a job claim for this item is already active; reconcile it before creating another"],
+];
+
+/** Wrap a coordination-service FleetConflict message with an explanation and
+ * an inspect command, keeping the original text in parentheses. Unknown
+ * messages are returned unchanged. */
+export function explainFleetConflict(message) {
+  const text = String(message ?? "");
+  if (text.includes(`Inspect: ${LEASES_COMMAND}`)) return text;
+  for (const [pattern, explanation] of FLEET_EXPLANATIONS) {
+    if (pattern.test(text)) return `Fleet conflict: ${explanation}. Inspect: ${LEASES_COMMAND} (${text})`;
+  }
+  return text;
+}

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

@@ -1,12 +1,34 @@
 import { createHash } from "node:crypto";
 import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { ensureTaskRuntimeDir, resolveTaskRuntimeRead } from "./task-runtime.mjs";
+import { migrateTaskRuntime } from "./task-runtime-migrate.mjs";
 
 const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 const digest = (value) => createHash("sha256").update(value).digest("hex");
 
+const firstLine = (text) => {
+  if (typeof text !== "string") return "";
+  return text.split(/\r?\n/).map((line) => line.trim()).find((line) => line.length > 0) ?? "";
+};
+
+const slugify = (text) => {
+  const slug = text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+/, "").slice(0, 127).replace(/-+$/, "");
+  return slug || "loop-task";
+};
+
+/** Derive a memorable task id (kebab-case slug) and a descriptive title from the
+ * requirement's first non-empty line, replacing the opaque `loop-<uuid>` id and
+ * the unhelpful `Loop task <id>` title. */
+export function deriveTaskIdentity(requirement) {
+  // The dashboard editor writes Markdown: drop a leading heading/list/quote marker,
+  // bold markers, and backticks ("__" stays: it is common in identifiers) so "# Fix login" titles the task "Fix login".
+  const line = firstLine(requirement).replace(/^(?:#{1,6}(?:\s+|$)|[-*+]\s+|\d+[.)]\s+|>\s*)/, "").replace(/(\*\*|`)/g, "").trim();
+  return { slug: slugify(line), title: line ? line.slice(0, 256) : "Loop task" };
+}
+
 /** Prepare a durable, idempotent intake without treating it as lifecycle state. */
-export async function prepareLoopIntake({ root, taskId, requirement, authority, createTask, readTask }) {
+export async function prepareLoopIntake({ root, taskId, requirement, authority, createTask, readTask, title }) {
   if (!ID.test(taskId ?? "")) throw new Error("Invalid task ID");
   if (!["local", "fleet"].includes(authority)) throw new Error("Invalid loop authority");
   if (typeof requirement !== "string" || !requirement.trim() || Buffer.byteLength(requirement) > 8192) throw new Error("Requirement must contain 1–8192 bytes");
@@ -21,7 +43,11 @@ export async function prepareLoopIntake({ root, taskId, requirement, authority,
   if (!existsSync(directory)) mkdirSync(directory, { mode: 0o700 });
   const stat = lstatSync(directory);
   if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("Unsafe task directory");
-  const recordPath = join(directory, "loop-intake.json");
+  // Intake files live under runtime/ (the task directory root is for review
+  // artifacts); a pre-runtime loop-intake.json/requirement.md moves there first.
+  migrateTaskRuntime(project, taskId, { names: ["intake.json", "requirement.md"] });
+  ensureTaskRuntimeDir(project, taskId);
+  const recordPath = resolveTaskRuntimeRead(project, taskId, "intake.json");
   const record = { schemaVersion: 1, taskId, authority, requirementHash: digest(requirement) };
   if (!existsSync(recordPath) && await readTask(taskId)) throw new Error("Existing task has no matching loop intake record");
   try { writeFileSync(recordPath, `${JSON.stringify(record)}\n`, { flag: "wx", mode: 0o600 }); }
@@ -32,20 +58,20 @@ export async function prepareLoopIntake({ root, taskId, requirement, authority,
     let current; try { current = JSON.parse(readFileSync(recordPath, "utf8")); } catch { throw new Error("Invalid intake record"); }
     if (JSON.stringify(current) !== JSON.stringify(record)) throw new Error("Existing intake has different authority or requirement");
   }
-  const requirementPath = join(directory, "requirement.md");
+  const requirementPath = resolveTaskRuntimeRead(project, taskId, "requirement.md");
   try { writeFileSync(requirementPath, requirement, { flag: "wx", mode: 0o600 }); }
   catch (error) {
     if (error?.code !== "EEXIST") throw error;
     const existing = lstatSync(requirementPath);
     if (!existing.isFile() || existing.isSymbolicLink() || digest(readFileSync(requirementPath, "utf8")) !== record.requirementHash) throw new Error("Existing requirement does not match intake");
   }
-  const title = `Loop task ${taskId}`;
+  const titleText = typeof title === "string" && title.trim() ? title.trim().slice(0, 256) : deriveTaskIdentity(requirement).title;
   let task = await readTask(taskId);
   if (!task) {
-    try { await createTask({ taskId, title }); }
-    catch (error) { task = await readTask(taskId); if (!task || task.title !== title) throw error; }
+    try { await createTask({ taskId, title: titleText }); }
+    catch (error) { task = await readTask(taskId); if (!task || task.title !== titleText) throw error; }
     task ??= await readTask(taskId);
   }
-  if (!task || task.id !== taskId || task.title !== title) throw new Error("Existing task conflicts with intake");
+  if (!task || task.id !== taskId || task.title !== titleText) throw new Error("Existing task conflicts with intake");
   return { taskId, authority, requirementPath };
 }

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

@@ -1,9 +1,8 @@
-import { randomUUID } from "node:crypto";
-import { closeSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { lstatSync, unlinkSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { acquireHolder, clearStaleHolder, describeHolder, GUARD_STALE_MS, LEASE_TTL_MS, readHolder } from "./loop-holder.mjs";
 
 const idPattern = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
-const sleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 export function assertLoopPath(root, taskId, suffix = ".json") {
   if (!idPattern.test(taskId)) throw new Error(`Invalid task id: ${taskId}`);
   const base = resolve(root);
@@ -17,73 +16,80 @@ export function assertLoopPath(root, taskId, suffix = ".json") {
 }
 
 export const loopLeasePath = (root, taskId) => assertLoopPath(root, taskId, ".lease");
-const guardPath = (root, taskId) => assertLoopPath(root, taskId, ".lease.guard");
 
-function parseLease(path) {
-  let value;
-  try { value = JSON.parse(readFileSync(path, "utf8")); }
-  catch (error) { throw new Error(`Corrupt loop lease: ${path}: ${error.message}`); }
-  if (!value || value.schemaVersion !== 1 || !idPattern.test(value.taskId) || typeof value.runId !== "string" || !value.runId || !Number.isInteger(value.pid) || value.pid < 1 || typeof value.token !== "string" || !value.token || typeof value.createdAt !== "string" || Number.isNaN(Date.parse(value.createdAt))) throw new Error(`Corrupt loop lease: ${path}`);
-  return value;
+// Task lease handles held by this process, so a supervisor's lease is shared
+// with the runLoop it drives instead of being acquired twice.
+const held = new Map();
+const heldKey = (root, taskId) => `${resolve(root)}\0${taskId}`;
+
+function checkScope(entry, taskId) {
+  const holder = entry.holder;
+  if (!holder) return;
+  const scope = entry.version === 2 ? holder.scope : holder.taskId ? `task:${holder.taskId}` : null;
+  if (scope && scope !== `task:${taskId}`) throw new Error(`Conflicting loop lease in ${entry.path}: ${scope}`);
+}
+
+/** Inspect the task lease (`loop/<task>.lease`) without changing it; see
+ * `readHolder` in loop-holder.mjs. */
+export function readTaskLease(root, taskId) {
+  const entry = readHolder(loopLeasePath(root, taskId), { ttlMs: LEASE_TTL_MS });
+  checkScope(entry, taskId);
+  return entry;
 }
 
-function alive(pid) {
-  try { process.kill(pid, 0); return true; }
-  catch (error) { if (error?.code === "ESRCH") return false; return true; }
+/** The live task lease holder while a loop turn runs (activity "turn"), else
+ * null. A supervisor waiting at a human gate (activity "waiting") does not
+ * count, so gate approval stays available. A v1 runner lease counts when its
+ * pid is alive. A corrupt lease fails closed. */
+export function readLiveLease(root, taskId) {
+  const entry = readTaskLease(root, taskId);
+  if (entry.state === "corrupt") throw new Error(`Corrupt loop lease: ${describeHolder(entry)}`);
+  if (entry.state !== "live") return null;
+  if (entry.version === 2 && entry.holder.activity !== "turn") return null;
+  return entry.holder;
 }
 
-function withGuard(root, taskId, action) {
-  const path = guardPath(root, taskId);
-  mkdirSync(dirname(path), { recursive: true });
-  const guard = { schemaVersion: 1, taskId, runId: "guard", pid: process.pid, token: randomUUID(), createdAt: new Date().toISOString() };
-  const deadline = Date.now() + 5000;
-  for (;;) {
-    try {
-      const fd = openSync(path, "wx", 0o600);
-      try { writeFileSync(fd, `${JSON.stringify(guard)}\n`); fsyncSync(fd); } finally { closeSync(fd); }
-      break;
-    } catch (error) {
-      if (error?.code !== "EEXIST") throw error;
-      const current = parseLease(path);
-      if (current.taskId !== taskId) throw new Error(`Conflicting loop lease guard: ${path}`);
-      if (!alive(current.pid)) { try { if (parseLease(path).token === current.token) unlinkSync(path); } catch (unlinkError) { if (unlinkError?.code !== "ENOENT") throw unlinkError; } continue; }
-      if (Date.now() >= deadline) throw new Error(`Timed out waiting for loop lease guard: ${taskId}`);
-      sleep(10);
-    }
+// Older versions kept a separate `<task>.supervisor.lease` (+ `.supervisor.guard`).
+function migrateLegacySupervisorLease(root, taskId) {
+  const legacy = assertLoopPath(root, taskId, ".supervisor.lease");
+  const entry = readHolder(legacy, { ttlMs: LEASE_TTL_MS });
+  if (entry.state === "live") throw new Error(`A loop from a previous aidlc-kit version is still running for ${taskId} (pid ${entry.holder.pid}, ${legacy}); stop the loop daemon and any \`loop start\` before upgrading, then retry`);
+  if (entry.state !== "absent") {
+    const cleared = clearStaleHolder(legacy, { ttlMs: LEASE_TTL_MS });
+    if (!cleared && readHolder(legacy, { ttlMs: LEASE_TTL_MS }).state !== "absent") throw new Error(`${describeHolder(entry)} (legacy supervisor lease)`);
   }
-  try { return action(); }
-  finally { if (parseLease(path).token === guard.token) unlinkSync(path); }
+  const legacyGuard = assertLoopPath(root, taskId, ".supervisor.guard");
+  try { if (Date.now() - lstatSync(legacyGuard).mtimeMs > GUARD_STALE_MS) unlinkSync(legacyGuard); }
+  catch (error) { if (error?.code !== "ENOENT") throw error; }
 }
 
-export function readLiveLease(root, taskId) {
+/** Acquire the task lease. `activity` is "waiting" (supervisor between runs,
+ * human may approve gates) or "turn" (a loop run is executing; gate approval is
+ * refused). `label` names the caller in the busy error. Returns the holder
+ * handle (`assertOwned`, `setActivity`, `heartbeat`, `release`). */
+export function acquireTaskLease(root, taskId, { activity = "waiting", label = "loop", purpose = `loop ${activity}`, onWarning } = {}) {
   const path = loopLeasePath(root, taskId);
-  try { lstatSync(path); } catch (error) { if (error?.code === "ENOENT") return null; throw error; }
-  const lease = parseLease(path);
-  if (lease.taskId !== taskId) throw new Error(`Conflicting loop lease: ${path}`);
-  return alive(lease.pid) ? lease : null;
+  const key = heldKey(root, taskId);
+  if (held.has(key)) throw new Error(`Task ${taskId} already has a live ${label} in this process: ${describeHolder(readTaskLease(root, taskId))}`);
+  migrateLegacySupervisorLease(root, taskId);
+  const handle = acquireHolder({
+    path, kind: "lease", scope: `task:${taskId}`, activity, purpose, onWarning,
+    busyMessage: (entry) => `Task ${taskId} already has a live ${label} (pid ${entry.holder.pid}): ${describeHolder(entry)}`,
+  });
+  const release = handle.release;
+  handle.release = () => { if (held.get(key) === handle) held.delete(key); release(); };
+  held.set(key, handle);
+  return handle;
 }
 
+/** The task lease handle this process already holds, or null. */
+export function heldTaskLease(root, taskId) {
+  return held.get(heldKey(root, taskId)) ?? null;
+}
+
+/** Compatibility wrapper: acquire the task lease for a loop run (activity
+ * "turn") and return its release function. */
 export function acquireLoopLease(root, taskId, runId) {
-  const path = loopLeasePath(root, taskId);
-  mkdirSync(dirname(path), { recursive: true });
-  const lease = { schemaVersion: 1, taskId, runId, pid: process.pid, token: randomUUID(), createdAt: new Date().toISOString() };
-  return withGuard(root, taskId, () => {
-  for (let attempt = 0; attempt < 4; attempt++) {
-    try {
-      const fd = openSync(path, "wx", 0o600);
-      try { writeFileSync(fd, `${JSON.stringify(lease)}\n`); fsyncSync(fd); }
-      finally { closeSync(fd); }
-      return () => withGuard(root, taskId, () => { try { if (parseLease(path).token === lease.token) unlinkSync(path); } catch (error) { if (error?.code !== "ENOENT") throw error; } });
-    } catch (error) {
-      if (error?.code !== "EEXIST") throw error;
-      const existing = parseLease(path);
-      if (existing.taskId !== taskId) throw new Error(`Conflicting loop lease: ${path}`);
-      if (alive(existing.pid)) throw new Error(`Task ${taskId} already has a live loop runner (pid ${existing.pid})`);
-      // A dead owner may be reclaimed. A competing reclaimer may win; retry with wx.
-      try { if (parseLease(path).token === existing.token) unlinkSync(path); }
-      catch (unlinkError) { if (unlinkError?.code !== "ENOENT") throw unlinkError; }
-    }
-  }
-  throw new Error(`Could not acquire loop lease for ${taskId}`);
-  });
+  const handle = acquireTaskLease(root, taskId, { activity: "turn", label: "loop runner", purpose: `loop run ${runId}` });
+  return () => handle.release();
 }