@ngockhoale/ukit 3.4.67 → 3.4.69

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

@@ -742,6 +742,128 @@ function claimActive(claim, now) {
     : false;
 }
 
+// Cycle identity (stale-claim across cycles hardening): task ids restart per
+// cycle, so a bare task id names BOTH the archived cycle's task and the live
+// cycle's task. A run pins its cycle with the additive `Cycle:` field in
+// RUN.md (the same identity stop-coordinator's parseRunCycle defines); claims
+// stamped with it let acquire/renew tell a PREVIOUS cycle's ghost from the
+// CURRENT cycle's live worker. Normalized `cycle-NN`; anything unparseable →
+// null (no stamp → the legacy, cycle-blind behavior).
+export function normalizeClaimCycle(value) {
+  const raw = String(value ?? '').trim();
+  const m = raw.match(/^(?:cycle-)?(\d+)$/i);
+  return m ? `cycle-${m[1].padStart(2, '0')}` : null;
+}
+
+// True only when BOTH sides carry a cycle stamp and they differ — the only
+// provably-stale shape. Unstamped (legacy) claims always take the legacy path,
+// so an upgraded install never preempts a worker it cannot reason about.
+function claimCycleDiffers(existing, incoming) {
+  return Boolean(existing?.cycle) && Boolean(incoming) && existing.cycle !== incoming;
+}
+
+// True when the live claim's cycle is strictly newer than the incoming (stale) one.
+function claimCycleOlder(existing, incoming) {
+  if (!existing?.cycle || !incoming) return false;
+  const a = Number(String(existing.cycle).replace(/\D/g, ''));
+  const b = Number(String(incoming).replace(/\D/g, ''));
+  return Number.isFinite(a) && Number.isFinite(b) && b < a;
+}
+
+// A claim stamped with an OLDER cycle is a ghost (may be superseded) only when that cycle is PROVEN
+// archived for THIS task. Proof is not a path: every component of docs/AI_HANDOFF/<ARCHIVE|archive>/
+// cycle-NN must be a real non-symlink directory, and the archive's INDEX.md snapshot (written at
+// archive time, before INDEX is reset) must be a readable, well-formed, non-symlink file with a
+// terminal row for the claimed task — `done`, or `cancelled_superseded` resolved by a terminal
+// `<root>-R<n>` successor in the same snapshot. Empty dir, regular file, symlink, malformed,
+// unreadable, missing row or nonterminal row all deny (false). Unknown never supersedes.
+const SAFE_DIR_ERRNO = new Set(['ENOENT']);
+
+async function realDirectoryOrAbsent(target) {
+  try {
+    const st = await fs.lstat(target);
+    return st.isDirectory() && !st.isSymbolicLink() ? 'dir' : 'unsafe';
+  } catch (error) {
+    return SAFE_DIR_ERRNO.has(error?.code) ? 'absent' : 'unsafe';
+  }
+}
+
+function parseArchiveSnapshotStatuses(text) {
+  const map = 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());
+    if (!row.startsWith('|') || !row.endsWith('|') || cells.length !== 8) return null;
+    const key = cells[0].toLowerCase();
+    if (map.has(key)) return null;
+    map.set(key, cells[4].toLowerCase());
+  }
+  return map;
+}
+
+// Terminal-success under the snapshot: done, or grounded cancellation resolved by a terminal successor.
+function snapshotTaskTerminal(key, statuses, seen = new Set()) {
+  if (seen.has(key)) return false;
+  seen.add(key);
+  const st = statuses.get(key);
+  if (st === 'done') return true;
+  if (st !== 'cancelled_superseded') return false;
+  const root = key.replace(/-r\d+$/, '');
+  const currentRepair = BigInt(key.match(/-r(\d+)$/)?.[1] ?? '0');
+  for (const [other, ost] of statuses) {
+    if (!other.startsWith(`${root}-r`) || !/^\d+$/.test(other.slice(root.length + 2))) continue;
+    if (BigInt(other.slice(root.length + 2)) <= currentRepair) continue;
+    if (ost === 'done' || (ost === 'cancelled_superseded' && snapshotTaskTerminal(other, statuses, seen))) return true;
+  }
+  return false;
+}
+
+async function claimCycleFinalized(projectRoot, cycle, taskId) {
+  if (!cycle || !/^cycle-\d+$/.test(cycle) || !taskId) return false;
+  const ai = path.join(projectRoot, 'docs', 'AI_HANDOFF');
+  for (const parent of [path.join(projectRoot, 'docs'), ai]) {
+    if ((await realDirectoryOrAbsent(parent)) !== 'dir') return false;
+  }
+  let proven = false;
+  for (const name of ['ARCHIVE', 'archive']) {
+    const base = path.join(ai, name);
+    const baseState = await realDirectoryOrAbsent(base);
+    if (baseState === 'unsafe') return false;
+    if (baseState === 'absent') continue;
+    const cycleDir = path.join(base, cycle);
+    const cycleState = await realDirectoryOrAbsent(cycleDir);
+    if (cycleState === 'unsafe') return false;
+    if (cycleState === 'absent') continue;
+    // Snapshot must be a regular, non-symlink file that is readable and well-formed.
+    let raw;
+    try {
+      const st = await fs.lstat(path.join(cycleDir, 'INDEX.md'));
+      if (!st.isFile() || st.isSymbolicLink()) return false;
+      raw = await fs.readFile(path.join(cycleDir, 'INDEX.md'), 'utf8');
+    } catch {
+      return false;
+    }
+    const statuses = parseArchiveSnapshotStatuses(raw);
+    if (statuses === null) return false;
+    if (snapshotTaskTerminal(goalKey(taskId), statuses)) proven = true;
+    else return false;
+  }
+  return proven;
+}
+
+function goalKey(taskId) {
+  return String(taskId ?? '').trim().toLowerCase();
+}
+
+// True when the incoming cycle is strictly newer than the live claim's stamped cycle.
+function claimCycleNewer(incoming, existing) {
+  if (!existing?.cycle || !incoming) return false;
+  const a = Number(String(existing.cycle).replace(/\D/g, ''));
+  const b = Number(String(incoming).replace(/\D/g, ''));
+  return Number.isFinite(a) && Number.isFinite(b) && b > a;
+}
+
 // 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) {
@@ -758,13 +880,44 @@ async function readClaimsMap(projectRoot) {
 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 });
+  let delegations = {};
+  try {
+    const stored = JSON.parse(await fs.readFile(target, 'utf8'));
+    if (stored.delegations !== undefined && !isPlainObject(stored.delegations)) throw new Error('invalid delegations');
+    delegations = stored.delegations || {};
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
+  let delegationCount = Object.keys(delegations).length;
+  for (const [taskId, claim] of Object.entries(claims)) {
+    if (!claim.grantId || !String(claim.owner).startsWith('deleg:')) continue;
+    const key = `${claim.owner}/${taskId}`;
+    // Immutable launch tuple: a reused owner must never retarget an old completion.
+    // Never evict an original identity: a delayed completion could otherwise retarget a
+    // reused tool id. Real dispatch refuses saturation; low-level callers retain lease-only metadata.
+    if (!delegations[key] && delegationCount < 4096) {
+      delegations[key] = { taskId, owner: claim.owner, cycle: claim.cycle ?? null,
+        generation: claim.generation, grantId: claim.grantId, sessionId: claim.sessionId ?? null };
+      delegationCount++;
+    }
+  }
+  await writeJsonAtomic(target, { schemaVersion: TASK_CLAIMS_SCHEMA_VERSION, claims, delegations });
+  return delegations;
 }
 
 /**
  * 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.
+ * `cycle` (the run's `Cycle:` from RUN.md, normalized `cycle-NN`) stamps the
+ * claim. A different owner can retire an ACTIVE older-cycle claim only with
+ * valid archived delivery proof for that task; a cycle change alone is not proof.
+ * Same-owner newer-cycle grants bump generation; stale older-cycle acquires deny.
+ * Same-cycle and unstamped different-owner claims remain protected until expiry.
+ * `requireTermination` is mandatory for real dispatch: a delegated grant is never
+ * replaced using expiry or archived delivery status. Its immutable launch identity
+ * must have registry capacity and must not have been used by a previous grant.
+ * Low-level callers leaving this false must enforce their own write/landing fence.
  *
  * @returns {Promise<{ok:true, claim:{owner,heartbeat,ttlMs}, refreshed?:boolean, tookOver?:boolean}
  *   | {ok:false, reason:string, claim?:object}>}
@@ -772,12 +925,15 @@ async function writeClaimsMap(projectRoot, claims) {
 export async function acquireTaskClaim(projectRoot, taskId, {
   owner = null,
   sessionId = null,
+  cycle = null,
   ttlMs = DEFAULT_TASK_CLAIM_TTL_MS,
   now = Date.now(),
   deadlineMs = RUN_JOURNAL_LOCK_BUDGET_MS,
+  requireTermination = false,
 } = {}) {
   const key = safeTaskId(taskId);
   const ownerToken = normalizeClaimOwner(owner);
+  const claimCycle = normalizeClaimCycle(cycle);
   const ttl = Number.isFinite(ttlMs) && ttlMs >= 0 ? ttlMs : DEFAULT_TASK_CLAIM_TTL_MS;
   try {
     const outcome = await withAsyncLock(taskClaimsPath(projectRoot), { deadlineMs }, async () => {
@@ -785,13 +941,64 @@ export async function acquireTaskClaim(projectRoot, taskId, {
       if (!read.ok) return { ok: false, reason: read.reason };
       const claims = read.claims;
       const existing = claims[key];
+      // Expiry revokes lease authority, not the worker's filesystem access. Real dispatch
+      // must not start a competing writer until a terminal handback removed this grant.
+      // Keep the low-level lease API compatible for callers that enforce their own fence.
+      if (requireTermination && isPlainObject(existing)
+        && String(existing.owner).startsWith('deleg:')
+        && (!claimActive(existing, now)
+          || (existing.owner === ownerToken && claimCycleNewer(claimCycle, existing)))) {
+        return { ok: false, reason: 'termination-unconfirmed', claim: { ...existing } };
+      }
       if (isPlainObject(existing) && claimActive(existing, now)) {
-        if (existing.owner === ownerToken) {
-          claims[key] = { ...existing, heartbeat: now, ttlMs: existing.ttlMs ?? ttl };
+        if (existing.owner !== ownerToken) {
+          // A different owner's ACTIVE claim is never displaced by a different cycle alone: a
+          // freshly acquired live worker has not renewed yet, so "not renewed" does not prove it
+          // dead. Its lease expires by TTL. Sole exception: the claim is stamped with an OLDER
+          // cycle that has since been archived (completed-only), so that worker is finished and a
+          // reused task id must not wait out the TTL. Unknown/unreadable → keep the deny.
+          const ghost = !(requireTermination && String(existing.owner).startsWith('deleg:'))
+            && claimCycleNewer(claimCycle, existing)
+            && await claimCycleFinalized(projectRoot, existing.cycle, taskId);
+          if (!ghost) return { ok: false, reason: 'active-claim', claim: { ...existing } };
+          // ghost: fall through to the takeover below (generation bump fences the old owner)
+        } else if (claimCycleOlder(existing, claimCycle)) {
+          // Same owner, but the incoming acquire is from an OLDER cycle than the live grant:
+          // a late/stale acquire must not regress the newer cycle's claim.
+          return { ok: false, reason: 'stale-cycle', claim: { ...existing } };
+        } else if (!claimCycleDiffers(existing, claimCycle)) {
+          // Same owner, same cycle (or unstamped legacy): refresh the heartbeat in place.
+          claims[key] = {
+            ...existing,
+            heartbeat: now,
+            ttlMs: existing.ttlMs ?? ttl,
+            ...(claimCycle ? { cycle: claimCycle } : {}),
+          };
           await writeClaimsMap(projectRoot, claims);
           return { ok: true, claim: { ...claims[key] }, refreshed: true };
         }
-        return { ok: false, reason: 'active-claim', claim: { ...existing } };
+        // Same owner, NEWER cycle: a new grant for the new cycle. Falls through to the takeover
+        // below, so the generation bumps and the old cycle's token is fenced.
+      }
+      if (requireTermination && ownerToken.startsWith('deleg:')) {
+        // Never launch a worker whose immutable handback tuple cannot be persisted.
+        // Do not evict old identities: a delayed notification must not target a new grant.
+        let delegations = {};
+        try {
+          const stored = JSON.parse(await fs.readFile(taskClaimsPath(projectRoot), 'utf8'));
+          if (stored.delegations !== undefined && !isPlainObject(stored.delegations)) {
+            return { ok: false, reason: 'claims-unreadable' };
+          }
+          delegations = stored.delegations || {};
+        } catch (error) {
+          if (error?.code !== 'ENOENT') return { ok: false, reason: 'claims-unreadable' };
+        }
+        if (delegations[`${ownerToken}/${key}`]) {
+          return { ok: false, reason: 'delegation-identity-reused' };
+        }
+        if (Object.keys(delegations).length >= 4096) {
+          return { ok: false, reason: 'delegation-registry-full' };
+        }
       }
       // `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.
@@ -799,15 +1006,20 @@ export async function acquireTaskClaim(projectRoot, taskId, {
       const claim = {
         owner: ownerToken,
         heartbeat: now,
+        claimedAt: now,
+        grantId: crypto.randomUUID(),
         ttlMs: ttl,
         generation,
+        ...(claimCycle ? { cycle: claimCycle } : {}),
         ...(sessionId ? { sessionId: String(sessionId) } : {}),
       };
       claims[key] = claim;
-      await writeClaimsMap(projectRoot, claims);
+      const delegations = await writeClaimsMap(projectRoot, claims);
       return {
         ok: true,
         claim: { ...claim },
+        ...(ownerToken.startsWith('deleg:') && !delegations[`${ownerToken}/${key}`]
+          ? { completionRecovery: 'lease-only' } : {}),
         ...(isPlainObject(existing) ? { tookOver: true } : {}),
       };
     });
@@ -823,11 +1035,14 @@ export async function acquireTaskClaim(projectRoot, taskId, {
 /** Refresh the heartbeat of a claim this owner still holds. Never creates one. */
 export async function heartbeatTaskClaim(projectRoot, taskId, {
   owner = null,
+  cycle = null,
+  generation = null,
   now = Date.now(),
   deadlineMs = RUN_JOURNAL_LOCK_BUDGET_MS,
 } = {}) {
   const key = safeTaskId(taskId);
   const ownerToken = normalizeClaimOwner(owner);
+  const beatCycle = normalizeClaimCycle(cycle);
   try {
     const outcome = await withAsyncLock(taskClaimsPath(projectRoot), { deadlineMs }, async () => {
       const read = await readClaimsMap(projectRoot);
@@ -835,6 +1050,12 @@ export async function heartbeatTaskClaim(projectRoot, taskId, {
       const existing = read.claims[key];
       if (!isPlainObject(existing)) return { ok: false, reason: 'no-claim' };
       if (existing.owner !== ownerToken) return { ok: false, reason: 'owner-mismatch' };
+      // Same fences as release: an old-cycle / superseded-generation holder must not keep a
+      // newer grant alive.
+      if (claimCycleDiffers(existing, beatCycle)) return { ok: false, reason: 'cycle-mismatch' };
+      if (generation !== null && Number(existing.generation) !== Number(generation)) {
+        return { ok: false, reason: 'generation-mismatch' };
+      }
       read.claims[key] = { ...existing, heartbeat: now };
       await writeClaimsMap(projectRoot, read.claims);
       return { ok: true, claim: { ...read.claims[key] } };
@@ -846,13 +1067,47 @@ export async function heartbeatTaskClaim(projectRoot, taskId, {
   }
 }
 
+// Notifications name the original tool-use-id, not the worker's task-id.
+export async function releaseCompletedDelegation(projectRoot, toolUseId, sessionId) {
+  if (!toolUseId || !sessionId) return;
+  let grants;
+  let legacy = {};
+  try {
+    const store = JSON.parse(await fs.readFile(taskClaimsPath(projectRoot), 'utf8'));
+    grants = store.delegations || {};
+    if (isPlainObject(store.claims)) legacy = store.claims;
+  } catch { return; }
+  if (!isPlainObject(grants)) return;
+  // Pre-grant claims (written before grant ids existed) have no registry entry. The same
+  // authenticated handback (original tool-use id + session) still ends them; a claim that
+  // carries a grantId is only ever released through its registered grant above.
+  for (const [taskId, claim] of Object.entries(legacy)) {
+    if (!isPlainObject(claim) || (claim.grantId !== undefined && claim.grantId !== null) || claim.owner !== `deleg:${toolUseId}`
+      || claim.sessionId !== sessionId || !Number.isInteger(claim.generation)) continue;
+    await releaseTaskClaim(projectRoot, taskId, { owner: claim.owner, cycle: claim.cycle, generation: claim.generation });
+  }
+  for (const grant of Object.values(grants)) {
+    if (!isPlainObject(grant) || typeof grant.owner !== 'string' || !grant.owner.startsWith('deleg:')
+      || typeof grant.taskId !== 'string' || !grant.taskId.trim()
+      || !Number.isInteger(grant.generation) || grant.generation < 1
+      || typeof grant.grantId !== 'string' || !grant.grantId
+      || grant.owner !== `deleg:${toolUseId}` || grant.sessionId !== sessionId) continue;
+    await releaseTaskClaim(projectRoot, grant.taskId, { owner: grant.owner, cycle: grant.cycle,
+      generation: grant.generation, grantId: grant.grantId });
+  }
+}
+
 /** Release a claim. Only the owner can remove it; absent claims release clean. */
 export async function releaseTaskClaim(projectRoot, taskId, {
   owner = null,
+  cycle = null,
+  generation = null,
+  grantId = null,
   deadlineMs = RUN_JOURNAL_LOCK_BUDGET_MS,
 } = {}) {
   const key = safeTaskId(taskId);
   const ownerToken = normalizeClaimOwner(owner);
+  const releaseCycle = normalizeClaimCycle(cycle);
   try {
     const outcome = await withAsyncLock(taskClaimsPath(projectRoot), { deadlineMs }, async () => {
       const read = await readClaimsMap(projectRoot);
@@ -860,6 +1115,13 @@ export async function releaseTaskClaim(projectRoot, taskId, {
       const existing = read.claims[key];
       if (!isPlainObject(existing)) return { ok: true, released: false };
       if (existing.owner !== ownerToken) return { ok: false, reason: 'owner-mismatch' };
+      // Cycle + generation fences: a late release from an older cycle, or by a holder whose
+      // generation was superseded, must not delete the current claim.
+      if (claimCycleDiffers(existing, releaseCycle)) return { ok: false, reason: 'cycle-mismatch' };
+      if (generation !== null && Number(existing.generation) !== Number(generation)) {
+        return { ok: false, reason: 'generation-mismatch' };
+      }
+      if (grantId !== null && existing.grantId !== grantId) return { ok: false, reason: 'grant-mismatch' };
       delete read.claims[key];
       await writeClaimsMap(projectRoot, read.claims);
       return { ok: true, released: true };
@@ -891,6 +1153,8 @@ export async function readTaskClaim(projectRoot, taskId, { now = Date.now() } =
 // 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;
+// Parent activity is not proof that a delegated worker is still alive.
+export const DELEGATED_CLAIM_MAX_RENEWAL_MS = 8 * DELEGATED_CLAIM_TTL_MS;
 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").
@@ -945,9 +1209,9 @@ export function delegatedClaimTargets(toolInput, { isKnownTask = null } = {}) {
   return targets;
 }
 
-/** Stable owner token for one delegation: the tool-call id, else the session id. */
+/** Stable owner token for one delegation; a session id cannot identify siblings. */
 export function delegatedClaimOwner(payload) {
-  const id = payload?.tool_use_id || payload?.session_id;
+  const id = payload?.tool_use_id;
   return typeof id === 'string' && id ? `deleg:${id}` : null;
 }
 
@@ -956,16 +1220,26 @@ export function delegatedClaimOwner(payload) {
  * 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.
+ * loses its claim. `cycle` (the run's current `Cycle:`) scopes the renewal to this run: a
+ * claim stamped with a DIFFERENT cycle is a previous cycle's ghost on a reused task id, and
+ * the session's continued activity must not keep it alive — it expires by its TTL instead.
+ * Unstamped claims renew as before. Lock-free pre-check keeps the common call (nothing due)
+ * free of I/O writes.
  */
 export async function renewSessionClaims(projectRoot, sessionId, {
+  cycle = null,
   now = Date.now(),
   deadlineMs = RUN_JOURNAL_LOCK_BUDGET_MS,
 } = {}) {
   const sid = typeof sessionId === 'string' ? sessionId : '';
   if (!sid) return { renewed: 0 };
+  const currentCycle = normalizeClaimCycle(cycle);
   const due = (claim) => isPlainObject(claim) && claim.sessionId === sid && claimActive(claim, now)
-    && now - Number(claim.heartbeat) > Number(claim.ttlMs) / 10;
+    && (!String(claim.owner || '').startsWith('deleg:')
+      || now - Number(claim.claimedAt ?? claim.heartbeat) < DELEGATED_CLAIM_MAX_RENEWAL_MS)
+    && now - Number(claim.heartbeat) > Number(claim.ttlMs) / 10
+    // A provably foreign-cycle claim is never renewed: the ghost ages out.
+    && !(currentCycle && claim.cycle && claim.cycle !== currentCycle);
   const peek = await readClaimsMap(projectRoot);
   if (!peek.ok || !Object.values(peek.claims).some(due)) return { renewed: 0 };
   try {
@@ -975,7 +1249,7 @@ export async function renewSessionClaims(projectRoot, sessionId, {
       let renewed = 0;
       for (const [key, claim] of Object.entries(read.claims)) {
         if (due(claim)) {
-          read.claims[key] = { ...claim, heartbeat: now };
+          read.claims[key] = { ...claim, heartbeat: now, claimedAt: claim.claimedAt ?? claim.heartbeat };
           renewed += 1;
         }
       }
@@ -993,10 +1267,11 @@ export async function renewSessionClaims(projectRoot, sessionId, {
  * 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() } = {}) {
+export async function verifyTaskClaimFence(projectRoot, taskId, { owner, generation = null, grantId = 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;
+  if (grantId !== null && read.claim.grantId !== grantId) return false;
   return generation === null || read.claim.generation === generation;
 }
 
@@ -1081,11 +1356,15 @@ export async function archiveCycleSnapshot(projectRoot, cycle) {
   // 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();
+  const taskFiles = new Map();
   try {
     for (const f of await fs.readdir(dir)) {
       if (!/^TASK-[\w.-]+\.md$/i.test(f)) continue;
       if ((await fs.lstat(path.join(dir, f))).isSymbolicLink()) return { ok: false, reason: 'archive-symlink' };
-      ids.add(f.replace(/\.md$/i, '').toUpperCase());
+      const id = f.replace(/\.md$/i, '').toUpperCase();
+      ids.add(id);
+      if (!taskFiles.has(id)) taskFiles.set(id, []);
+      taskFiles.get(id).push(f);
     }
   } catch (error) {
     return { ok: false, reason: error?.code === 'ENOENT' ? 'no-task-files' : 'archive-unreadable' };
@@ -1114,13 +1393,15 @@ export async function archiveCycleSnapshot(projectRoot, cycle) {
   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;
+    for (const filename of taskFiles.get(id)) {
+      const file = path.join(dir, filename);
+      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 };
 }
@@ -1212,8 +1493,16 @@ async function main() {
         owner,
         sessionId: owner.includes(':') ? owner.slice(owner.indexOf(':') + 1) : null,
         ttlMs: DELEGATED_CLAIM_TTL_MS,
+        requireTermination: true,
+        // Optional cycle stamp (`--cycle 2`) so a main-agent claim participates
+        // in the same cross-cycle reconcile the delegation path uses.
+        cycle: typeof flags.cycle === 'string' ? flags.cycle : null,
       })
-      : await releaseTaskClaim(projectRoot, taskId.toUpperCase(), { owner });
+      : await releaseTaskClaim(projectRoot, taskId.toUpperCase(), {
+        owner,
+        cycle: typeof flags.cycle === 'string' ? flags.cycle : null,
+        generation: typeof flags.generation === 'string' ? flags.generation : null,
+      });
     process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
     if (result.ok === false) process.exitCode = 3;
     return;
@@ -1221,7 +1510,7 @@ async function main() {
   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 claim|release <projectRoot> <taskId> --owner <main:session> [--cycle <NN>] [--generation <N>]\n'
     + '       resumable-run.mjs suspend <projectRoot> <taskId> [--boundary <id>] '
     + '[--phase <phase>] [--next <action>] [--completed <a,b,...>]\n',
   );