@ngockhoale/ukit 3.4.29 → 3.4.31

package/template_project/.claude/ukit/runtime/resumable-run.mjs

@@ -697,6 +697,393 @@ export async function resumableRunSourceFingerprint(projectRoot, { indexGenerate
   };
 }
 
+// --- per-task execution claims (goal-loop duplicate-execution guard) -----------
+//
+// A goal-level run-all loop resumes by re-reading persisted state; without a
+// claim book, a stale resume (or two parallel resumes after a compact) can
+// execute the same task twice. A claim is `{ owner, heartbeat, ttlMs }` recorded
+// per safeTaskId in `.ukit/storage/runs/claims.json` — a SEPARATE file, so
+// previously written C10 records stay byte-compatible and their validation and
+// journaling semantics are untouched. Heartbeats keep a claim alive; a claim
+// whose heartbeat is older than its TTL may be taken over. Every mutation is
+// lock-scoped through the same withAsyncLock discipline as the record itself
+// and published with the atomic tmp+rename write. A lock-busy acquisition fails
+// CLOSED (no claim = no execution right): two claimers must never both proceed
+// on a contended lock.
+
+export const TASK_CLAIMS_SCHEMA_VERSION = 1;
+export const DEFAULT_TASK_CLAIM_TTL_MS = 15 * 60 * 1000;
+const CLAIM_OWNER_MAX = 128;
+
+export function taskClaimsPath(projectRoot) {
+  return path.join(buildRuntimePaths(projectRoot).storageRoot, 'runs', 'claims.json');
+}
+
+function normalizeClaimOwner(owner) {
+  const token = typeof owner === 'string' && owner.trim()
+    ? owner.trim().slice(0, CLAIM_OWNER_MAX)
+    : `pid-${process.pid}-${crypto.randomUUID().slice(0, 8)}`;
+  return token;
+}
+
+function claimActive(claim, now) {
+  const heartbeat = Number(claim?.heartbeat);
+  const ttl = Number(claim?.ttlMs);
+  return Number.isFinite(heartbeat) && Number.isFinite(ttl) && ttl >= 0
+    ? now - heartbeat <= ttl
+    : false;
+}
+
+// Read the claims map. Missing file → empty map; corrupt file → `ok:false`
+// (callers fail closed on mutations, report honestly on reads).
+async function readClaimsMap(projectRoot) {
+  try {
+    const parsed = JSON.parse(await fs.readFile(taskClaimsPath(projectRoot), 'utf8'));
+    const claims = isPlainObject(parsed?.claims) ? parsed.claims : {};
+    return { ok: true, claims };
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { ok: true, claims: {} };
+    return { ok: false, reason: 'claims-unreadable' };
+  }
+}
+
+async function writeClaimsMap(projectRoot, claims) {
+  const target = taskClaimsPath(projectRoot);
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  await writeJsonAtomic(target, { schemaVersion: TASK_CLAIMS_SCHEMA_VERSION, claims });
+}
+
+/**
+ * Claim exclusive execution of `taskId`. Idempotent for the SAME owner (the
+ * heartbeat is refreshed); a second owner inside the TTL gets
+ * `{ ok: false, reason: 'active-claim' }`; an expired claim can be taken over.
+ *
+ * @returns {Promise<{ok:true, claim:{owner,heartbeat,ttlMs}, refreshed?:boolean, tookOver?:boolean}
+ *   | {ok:false, reason:string, claim?:object}>}
+ */
+export async function acquireTaskClaim(projectRoot, taskId, {
+  owner = null,
+  sessionId = null,
+  ttlMs = DEFAULT_TASK_CLAIM_TTL_MS,
+  now = Date.now(),
+  deadlineMs = RUN_JOURNAL_LOCK_BUDGET_MS,
+} = {}) {
+  const key = safeTaskId(taskId);
+  const ownerToken = normalizeClaimOwner(owner);
+  const ttl = Number.isFinite(ttlMs) && ttlMs >= 0 ? ttlMs : DEFAULT_TASK_CLAIM_TTL_MS;
+  try {
+    const outcome = await withAsyncLock(taskClaimsPath(projectRoot), { deadlineMs }, async () => {
+      const read = await readClaimsMap(projectRoot);
+      if (!read.ok) return { ok: false, reason: read.reason };
+      const claims = read.claims;
+      const existing = claims[key];
+      if (isPlainObject(existing) && claimActive(existing, now)) {
+        if (existing.owner === ownerToken) {
+          claims[key] = { ...existing, heartbeat: now, ttlMs: existing.ttlMs ?? ttl };
+          await writeClaimsMap(projectRoot, claims);
+          return { ok: true, claim: { ...claims[key] }, refreshed: true };
+        }
+        return { ok: false, reason: 'active-claim', claim: { ...existing } };
+      }
+      // `generation` is the fencing token: every fresh grant or takeover bumps it, so a result
+      // committed by an owner whose claim lapsed can be told apart from the current holder's.
+      const generation = (Number(existing?.generation) || 0) + 1;
+      const claim = {
+        owner: ownerToken,
+        heartbeat: now,
+        ttlMs: ttl,
+        generation,
+        ...(sessionId ? { sessionId: String(sessionId) } : {}),
+      };
+      claims[key] = claim;
+      await writeClaimsMap(projectRoot, claims);
+      return {
+        ok: true,
+        claim: { ...claim },
+        ...(isPlainObject(existing) ? { tookOver: true } : {}),
+      };
+    });
+    // withAsyncLock wraps the callback result as { ok, value } — unwrap it; a
+    // lock failure (ok:false, no value) fails closed below.
+    if (outcome?.ok === true && isPlainObject(outcome.value)) return outcome.value;
+    return { ok: false, reason: outcome?.value?.reason ?? outcome?.reason ?? 'busy' };
+  } catch {
+    return { ok: false, reason: 'busy' }; // fail closed: no claim, no execution right
+  }
+}
+
+/** Refresh the heartbeat of a claim this owner still holds. Never creates one. */
+export async function heartbeatTaskClaim(projectRoot, taskId, {
+  owner = null,
+  now = Date.now(),
+  deadlineMs = RUN_JOURNAL_LOCK_BUDGET_MS,
+} = {}) {
+  const key = safeTaskId(taskId);
+  const ownerToken = normalizeClaimOwner(owner);
+  try {
+    const outcome = await withAsyncLock(taskClaimsPath(projectRoot), { deadlineMs }, async () => {
+      const read = await readClaimsMap(projectRoot);
+      if (!read.ok) return { ok: false, reason: read.reason };
+      const existing = read.claims[key];
+      if (!isPlainObject(existing)) return { ok: false, reason: 'no-claim' };
+      if (existing.owner !== ownerToken) return { ok: false, reason: 'owner-mismatch' };
+      read.claims[key] = { ...existing, heartbeat: now };
+      await writeClaimsMap(projectRoot, read.claims);
+      return { ok: true, claim: { ...read.claims[key] } };
+    });
+    if (outcome?.ok === true && isPlainObject(outcome.value)) return outcome.value;
+    return { ok: false, reason: outcome?.value?.reason ?? outcome?.reason ?? 'busy' };
+  } catch {
+    return { ok: false, reason: 'busy' };
+  }
+}
+
+/** Release a claim. Only the owner can remove it; absent claims release clean. */
+export async function releaseTaskClaim(projectRoot, taskId, {
+  owner = null,
+  deadlineMs = RUN_JOURNAL_LOCK_BUDGET_MS,
+} = {}) {
+  const key = safeTaskId(taskId);
+  const ownerToken = normalizeClaimOwner(owner);
+  try {
+    const outcome = await withAsyncLock(taskClaimsPath(projectRoot), { deadlineMs }, async () => {
+      const read = await readClaimsMap(projectRoot);
+      if (!read.ok) return { ok: false, reason: read.reason };
+      const existing = read.claims[key];
+      if (!isPlainObject(existing)) return { ok: true, released: false };
+      if (existing.owner !== ownerToken) return { ok: false, reason: 'owner-mismatch' };
+      delete read.claims[key];
+      await writeClaimsMap(projectRoot, read.claims);
+      return { ok: true, released: true };
+    });
+    if (outcome?.ok === true && isPlainObject(outcome.value)) return outcome.value;
+    return { ok: false, reason: outcome?.value?.reason ?? outcome?.reason ?? 'busy' };
+  } catch {
+    return { ok: false, reason: 'busy' };
+  }
+}
+
+/**
+ * Read one claim: `{ claimed: true, active, claim }` when present, else
+ * `{ claimed: false }`. Lock-free read — the atomic publish means a reader sees
+ * the old or the new map, never a torn one.
+ */
+export async function readTaskClaim(projectRoot, taskId, { now = Date.now() } = {}) {
+  const read = await readClaimsMap(projectRoot);
+  if (!read.ok) return { claimed: false, unreadable: true };
+  const existing = read.claims[safeTaskId(taskId)];
+  if (!isPlainObject(existing)) return { claimed: false };
+  return { claimed: true, active: claimActive(existing, now), claim: { ...existing } };
+}
+
+// ─── delegation → claim wiring ──────────────────────────────────────────────
+// The PreToolUse delegation guard acquires, the PostToolUse receipt hook releases. Only
+// write-capable executor agents claim (a reviewer/planner touching the same task must not
+// be blocked by — or block — the executor), and only a task id that names ONE task: the
+// FIRST `TASK-…` in the delegation text is the primary task (later ids are dependencies).
+export const CLAIMING_AGENT_TYPES = new Set(['feature-implementer', 'bug-debugger']);
+export const DELEGATED_CLAIM_TTL_MS = 30 * 60 * 1000;
+const DELEGATED_TASK_ID_RE = /\bTASK-(?:C\d+-)?\d+\b/gi;
+// A TASK id directly after an execution verb is the delegation's primary task; ids elsewhere in
+// the text are dependencies or context ("after TASK-001", "see TASK-004").
+const DELEGATED_PRIMARY_RE = /\b(?:execute|implement|run|do|fix|complete|finish|work\s+on|resume|retry|start)\s+(?:the\s+)?(?:task\s+)?(TASK-(?:C\d+-)?\d+)\b/i;
+
+function structuredTaskId(source) {
+  const meta = isPlainObject(source?.metadata) ? source.metadata : {};
+  const raw = source?.task_id ?? source?.taskId ?? meta.task_id ?? meta.taskId;
+  return typeof raw === 'string' && /^TASK-(?:C\d+-)?\d+$/i.test(raw.trim()) ? raw.trim().toUpperCase() : null;
+}
+
+/**
+ * Resolve the ONE task a delegation executes. Authority order: structured id field > id after an
+ * execution verb > the sole distinct id > (several ids, no verb) the first id the caller can
+ * validate against the task store. Anything unresolvable claims nothing rather than guessing.
+ */
+function resolveDelegatedTaskId(entry, isKnownTask) {
+  if (entry.structured) return entry.structured;
+  const verbLed = DELEGATED_PRIMARY_RE.exec(entry.text);
+  if (verbLed) return verbLed[1].toUpperCase();
+  const ids = [...new Set((entry.text.match(DELEGATED_TASK_ID_RE) || []).map((id) => id.toUpperCase()))];
+  if (ids.length === 1) return ids[0];
+  if (ids.length > 1 && typeof isKnownTask === 'function') return ids.find((id) => isKnownTask(id)) ?? null;
+  return null;
+}
+
+/** @returns {Array<{taskId:string, agent:string}>} */
+export function delegatedClaimTargets(toolInput, { isKnownTask = null } = {}) {
+  const input = isPlainObject(toolInput) ? toolInput : {};
+  const entries = Array.isArray(input.tasks) && input.tasks.length
+    ? input.tasks.map((t) => ({
+      agent: t?.agent || t?.subagent_type,
+      structured: structuredTaskId(t) || structuredTaskId(input),
+      text: [t?.task, t?.name, t?.prompt, t?.description].filter((v) => typeof v === 'string').join('\n'),
+    }))
+    : [{
+      agent: input.subagent_type || input.agent || input.agent_type,
+      structured: structuredTaskId(input),
+      text: [input.prompt, input.description, input.task].filter((v) => typeof v === 'string').join('\n'),
+    }];
+  const targets = [];
+  const seen = new Set();
+  for (const entry of entries) {
+    const agent = String(entry.agent ?? '').toLowerCase();
+    if (!CLAIMING_AGENT_TYPES.has(agent)) continue;
+    const taskId = resolveDelegatedTaskId(entry, isKnownTask);
+    if (taskId && !seen.has(taskId)) {
+      seen.add(taskId);
+      targets.push({ taskId, agent });
+    }
+  }
+  return targets;
+}
+
+/** Stable owner token for one delegation: the tool-call id, else the session id. */
+export function delegatedClaimOwner(payload) {
+  const id = payload?.tool_use_id || payload?.session_id;
+  return typeof id === 'string' && id ? `deleg:${id}` : null;
+}
+
+/**
+ * Lease renewal: a delegated agent that runs longer than the claim TTL keeps its claim alive
+ * through its own session activity. Any tool event of the owning session (the parent's hooks
+ * fire for subagent tool calls too) refreshes that session's active claims, so a LIVE task is
+ * never handed to a second agent by TTL alone; only a session that went silent for a full TTL
+ * loses its claim. Lock-free pre-check keeps the common call (nothing due) free of I/O writes.
+ */
+export async function renewSessionClaims(projectRoot, sessionId, {
+  now = Date.now(),
+  deadlineMs = RUN_JOURNAL_LOCK_BUDGET_MS,
+} = {}) {
+  const sid = typeof sessionId === 'string' ? sessionId : '';
+  if (!sid) return { renewed: 0 };
+  const due = (claim) => isPlainObject(claim) && claim.sessionId === sid && claimActive(claim, now)
+    && now - Number(claim.heartbeat) > Number(claim.ttlMs) / 10;
+  const peek = await readClaimsMap(projectRoot);
+  if (!peek.ok || !Object.values(peek.claims).some(due)) return { renewed: 0 };
+  try {
+    const outcome = await withAsyncLock(taskClaimsPath(projectRoot), { deadlineMs }, async () => {
+      const read = await readClaimsMap(projectRoot);
+      if (!read.ok) return { renewed: 0 };
+      let renewed = 0;
+      for (const [key, claim] of Object.entries(read.claims)) {
+        if (due(claim)) {
+          read.claims[key] = { ...claim, heartbeat: now };
+          renewed += 1;
+        }
+      }
+      if (renewed) await writeClaimsMap(projectRoot, read.claims);
+      return { renewed };
+    });
+    return outcome?.ok === true && isPlainObject(outcome.value) ? outcome.value : { renewed: 0 };
+  } catch {
+    return { renewed: 0 };
+  }
+}
+
+/**
+ * Fence check for result commits: true only while `owner` still holds an ACTIVE claim on the
+ * task (and, when given, at the same generation). An owner whose lease lapsed and was taken over
+ * must not commit — the new holder's generation differs.
+ */
+export async function verifyTaskClaimFence(projectRoot, taskId, { owner, generation = null, now = Date.now() } = {}) {
+  const read = await readTaskClaim(projectRoot, taskId, { now });
+  if (!read.claimed || !read.active) return false;
+  if (read.claim.owner !== owner) return false;
+  return generation === null || read.claim.generation === generation;
+}
+
+/**
+ * Count the ACTIVE claims in the registry — the `agents:none-running` exit
+ * predicate's input. Returns null only when the registry exists but cannot be
+ * read (unknown state must read as unmet, never as "none running").
+ */
+export async function countActiveTaskClaims(projectRoot, { now = Date.now() } = {}) {
+  const read = await readClaimsMap(projectRoot);
+  if (!read.ok) return null;
+  return Object.values(read.claims).filter((claim) => claimActive(claim, now)).length;
+}
+
+// --- Archive-time status snapshot ---------------------------------------------------
+// INDEX.md owns the task lifecycle; a task file's own `- Status:` header is executor-written
+// and goes stale (`ready`) once the task is archived. `archiveCycleSnapshot` persists the
+// verified terminal INDEX rows beside the archived task files (`archive/cycle-NN/INDEX.md`),
+// which is what the Stop predicate (stop-coordinator `evalFinalizedCycles`) reads. Idempotent,
+// crash-safe (run it BEFORE the INDEX reset; a retry after a partial archive just re-derives),
+// and fail-closed: a non-terminal live row is recorded as-is, never promoted.
+
+const TERMINAL_TASK_STATUSES = new Set(['done', 'cancelled_superseded']);
+
+function indexRows(text) {
+  const rows = new Map();
+  for (const line of String(text).split('\n')) {
+    const row = line.trim();
+    if (!/^\|\s*TASK-/i.test(row)) continue;
+    const cells = row.split('|').slice(1, -1).map((c) => c.trim()); // keep empty cells: columns must not shift
+    rows.set(String(cells[0]).toUpperCase(), { cells, status: String(cells[4] || '').toLowerCase() });
+  }
+  return rows;
+}
+
+/**
+ * Snapshot the live INDEX rows of the tasks that belong to `archive/cycle-<NN>/` (task files
+ * already moved there, or still in `tasks/` and about to move) and stamp each archived task
+ * header with its terminal INDEX status. Returns `{ ok, cycle, snapshotted, stamped, unchanged }`.
+ */
+export async function archiveCycleSnapshot(projectRoot, cycle) {
+  const nn = String(cycle).padStart(2, '0');
+  if (!/^\d{2,}$/.test(nn)) return { ok: false, reason: 'bad-cycle' };
+  const ai = path.join(projectRoot, 'docs', 'AI_HANDOFF');
+  const dir = path.join(ai, 'archive', `cycle-${nn}`);
+  const snapPath = path.join(dir, 'INDEX.md');
+  let live = new Map();
+  try { live = indexRows(await fs.readFile(path.join(ai, 'INDEX.md'), 'utf8')); } catch { /* header-only / missing → rely on prior snapshot */ }
+  let prior = new Map();
+  try { prior = indexRows(await fs.readFile(snapPath, 'utf8')); } catch { /* first run */ }
+  // Only task files already inside THIS cycle's archive folder are snapshotted (F3 moves them
+  // first). Task ids restart per cycle, so the live `tasks/` and live INDEX rows of a LATER
+  // cycle must never be attributed here: an existing snapshot row is immutable (prior wins);
+  // a live row only fills an id that has no snapshot row yet.
+  const ids = new Set();
+  try {
+    for (const f of await fs.readdir(dir)) {
+      if (/^TASK-[\w.-]+\.md$/i.test(f)) ids.add(f.replace(/\.md$/i, '').toUpperCase());
+    }
+  } catch { /* absent dir */ }
+  if (ids.size === 0) return { ok: false, reason: 'no-task-files' };
+  const merged = new Map();
+  for (const id of [...ids].sort()) {
+    const row = prior.get(id) || live.get(id);
+    if (row) merged.set(id, row);
+  }
+  const header = '# Archived INDEX snapshot (cycle ' + nn + ')\n\n'
+    + '| ID | Title | Priority | Size | Status | Owner | Reviewer | File |\n'
+    + '|----|-------|----------|------|--------|-------|----------|------|\n';
+  const body = [...merged.values()].map((r) => `| ${r.cells.join(' | ')} |`).join('\n');
+  const next = `${header}${body}${body ? '\n' : ''}`;
+  let unchanged = true;
+  let current = null;
+  try { current = await fs.readFile(snapPath, 'utf8'); } catch { /* none */ }
+  if (merged.size > 0 && current !== next) {
+    await fs.mkdir(dir, { recursive: true });
+    const tmp = `${snapPath}.${process.pid}.tmp`;
+    await fs.writeFile(tmp, next, 'utf8');
+    await fs.rename(tmp, snapPath);
+    unchanged = false;
+  }
+  let stamped = 0;
+  for (const [id, row] of merged) {
+    if (!TERMINAL_TASK_STATUSES.has(row.status)) continue;
+    const file = path.join(dir, `${id}.md`);
+    let text;
+    try { text = await fs.readFile(file, 'utf8'); } catch { continue; }
+    const m = text.match(/^(-\s*Status:\s*`?)([\w-]+)(`?)/im);
+    if (!m || m[2].toLowerCase() === row.status) continue;
+    await fs.writeFile(file, text.replace(m[0], `${m[1]}${row.status}${m[3]}`), 'utf8');
+    stamped += 1;
+  }
+  return { ok: true, cycle: nn, snapshotted: merged.size, stamped, unchanged: unchanged && stamped === 0 };
+}
+
 // --- CLI (diagnostics) ---------------------------------------------------------
 
 function parseCliFlags(argv) {
@@ -762,8 +1149,38 @@ async function main() {
     if (!result.ok && !result.journaled) process.exitCode = 3;
     return;
   }
+  if (command === 'archive-cycle' && taskId) {
+    const result = await archiveCycleSnapshot(projectRoot, taskId);
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    if (!result.ok) process.exitCode = 3;
+    return;
+  }
+  if ((command === 'claim' || command === 'release') && taskId) {
+    // Main-agent participation in the existing claim registry (no second scheduler): the
+    // orchestrator that must run a task itself claims it first; the guard honours `main:<session>`.
+    const owner = typeof flags.owner === 'string' && flags.owner ? flags.owner : null;
+    if (!owner) {
+      // A random owner token would never match the guard's `main:<session>` check and could
+      // not be released — refuse instead of minting an unusable claim.
+      process.stderr.write('claim|release requires --owner <main:session>\n');
+      process.exitCode = 2;
+      return;
+    }
+    const result = command === 'claim'
+      ? await acquireTaskClaim(projectRoot, taskId.toUpperCase(), {
+        owner,
+        sessionId: owner.includes(':') ? owner.slice(owner.indexOf(':') + 1) : null,
+        ttlMs: DELEGATED_CLAIM_TTL_MS,
+      })
+      : await releaseTaskClaim(projectRoot, taskId.toUpperCase(), { owner });
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    if (result.ok === false) process.exitCode = 3;
+    return;
+  }
   process.stderr.write(
     'usage: resumable-run.mjs read <projectRoot> <taskId> [--boundary <id>]\n'
+    + '       resumable-run.mjs archive-cycle <projectRoot> <NN>\n'
+    + '       resumable-run.mjs claim|release <projectRoot> <taskId> --owner <main:session>\n'
     + '       resumable-run.mjs suspend <projectRoot> <taskId> [--boundary <id>] '
     + '[--phase <phase>] [--next <action>] [--completed <a,b,...>]\n',
   );