@ngockhoale/ukit 3.4.29 → 3.4.30

package/template_project/.claude/ukit/runtime/handoff-intent.mjs

@@ -28,7 +28,9 @@
 //        could not complete (missing/unreadable path, budget overrun) — callers keep
 //        their fail-closed posture on `known=false`.
 //
-// Intent values stay the historical pair 'create' | 'fullstack': an exact
+// Intent values: 'create' | 'fullstack' | 'review' | 'neutral' (status/clear); every
+// consumer compares by equality with 'create' / 'fullstack', so the added values are
+// non-matching by construction. An exact
 // `handoff-implement` invocation CLAIMS the run (the fullstack command says so
 // itself), so it maps onto the existing 'fullstack' intent instead of adding a
 // new enum every consumer would have to learn (TASK-C97-004).
@@ -48,7 +50,7 @@ export const HANDOFF_RESUME_BANNER = 'UKIT HANDOFF RESUME — an unfinished hand
 
 // Sweeper for "which command tag came LAST in this entry": finds every exact
 // command-name tag occurrence with its position so the newest one wins.
-const COMMAND_TAG_SWEEP = /<command-name>\/?(?:ukit:)?handoff-(create|fullstack|implement)(?![\w-])/g;
+const COMMAND_TAG_SWEEP = /<command-name>\/?(?:ukit:)?handoff-(create|fullstack|implement|review|status|clear)(?![\w-])/g;
 
 // omp and Codex do NOT wrap a slash command in `<command-name>` tags the way
 // Claude Code's user turn does. Their native evidence is the command *expansion*:
@@ -58,7 +60,7 @@ const COMMAND_TAG_SWEEP = /<command-name>\/?(?:ukit:)?handoff-(create|fullstack|
 // the FIRST line only (not any heading in the body) keeps prose references to the
 // command inside the document from being mistaken for an invocation. The same
 // exact token boundary applies: `-custom` suffixed headings are not commands.
-const NATIVE_COMMAND_HEADING = /^\s{0,3}#{1,3}\s+\/?(?:ukit:)?(handoff-create|handoff-fullstack|handoff-implement)(?![\w-])/;
+const NATIVE_COMMAND_HEADING = /^\s{0,3}#{1,3}\s+\/?(?:ukit:)?(handoff-create|handoff-fullstack|handoff-implement|handoff-review|handoff-status|handoff-clear)(?![\w-])/;
 
 // The unique customType the omp bridge stamps on host-injected UKit hook context
 // (`sendContext` → `hookContextMessage`). A resume banner only counts as intent
@@ -89,6 +91,10 @@ function commandTokenIntent(token) {
   const t = String(token).toLowerCase().replace(/^handoff-/, '');
   if (t === 'create') return 'create';
   if (t === 'fullstack' || t === 'implement') return 'fullstack';
+  // review is its own phase (scoped fix + re-review); status/clear are neutral. They
+  // must SUPERSEDE an older create, otherwise the create-scope guard leaks forward.
+  if (t === 'review') return 'review';
+  if (t === 'status' || t === 'clear') return 'neutral';
   return null;
 }
 
@@ -182,14 +188,14 @@ function classifyAssistantBlocks(blocks) {
     if (!b || typeof b !== 'object') continue;
     if (b.type === 'tool_use' && b.name === 'Skill') {
       const skill = String(b.input?.skill ?? '');
-      const m = /^(?:ukit:)?handoff-(create|fullstack|implement)$/.exec(skill);
+      const m = /^(?:ukit:)?handoff-(create|fullstack|implement|review|status|clear)$/.exec(skill);
       if (m) latest = commandTokenIntent(m[1]);
       continue;
     }
     if (b.type === 'toolCall') {
       const name = String(b.name ?? '');
       const skill = String(b.arguments?.skill ?? '');
-      const m = /^(?:ukit:)?handoff-(create|fullstack|implement)$/i.exec(name) || /^(?:ukit:)?handoff-(create|fullstack|implement)$/.exec(skill);
+      const m = /^(?:ukit:)?handoff-(create|fullstack|implement|review|status|clear)$/i.exec(name) || /^(?:ukit:)?handoff-(create|fullstack|implement|review|status|clear)$/.exec(skill);
       if (m) latest = commandTokenIntent(m[1]);
     }
   }
@@ -307,7 +313,7 @@ export async function transcriptHandoffIntent(transcriptPath, {
       // Cheap prefilter — skip JSON.parse for lines that cannot be evidence.
       // `handoff-implement` is included: an implement invocation after a create
       // must be seen as the NEWEST intent, not lost to the older create line.
-      if (!line.includes('handoff-create') && !line.includes('handoff-fullstack') && !line.includes('handoff-implement') && !line.includes('HANDOFF RESUME')) {
+      if (!line.includes('handoff-create') && !line.includes('handoff-fullstack') && !line.includes('handoff-implement') && !line.includes('handoff-review') && !line.includes('handoff-status') && !line.includes('handoff-clear') && !line.includes('HANDOFF RESUME')) {
         continue;
       }
       // This is the NEWEST line carrying intent evidence. A host append can be
@@ -410,3 +416,113 @@ export function runCursorPaused(text) {
   if (/^paused\b/i.test(field('Phase'))) return true;
   return /\bPAUSED\b/.test(field('Cursor')) || /\bPAUSED\b/.test(field('Next'));
 }
+
+// ─── Run-all intent (goal-level loop phrase) ──────────────────────────────
+// A run-all instruction ("run all remaining tasks", "finish everything",
+// "chạy hết các task còn lại") binds the GOAL, not one cycle: the executor
+// keeps cycling until no in-scope task remains. This is TEXT evidence for the
+// goal loop ONLY — it never feeds classifyHandoffEntry, whose structured-only
+// rule (TASK-007) keeps raw phrases from minting command ownership, so
+// "handoff-create + run-all" stays planning. Every alternative below demands a
+// totality quantifier (all/every/everything/hết/toàn bộ/…) next to the task
+// word, so a single-task prompt ("run task 3", "TASK-003") never matches.
+export const RUN_ALL_RE = new RegExp(
+  [
+    // EN verb … all/every … tasks ("run all remaining tasks", "execute every open task").
+    String.raw`\b(?:run|execute|do|process|implement|finish|complete|handle|work\s+through)\b[^.\n]{0,40}?\b(?:all|every)\b[^.\n]{0,40}?\btasks?\b`,
+    // EN bare quantifier over tasks ("all remaining tasks", "every queued task", "all of the tasks").
+    String.raw`\b(?:all|every)\s+(?:the\s+)?(?:(?:remaining|pending|open|unfinished|authorized|queued|outstanding|in-scope)\s+)?tasks?\b|\b(?:all|every)\b[^.\n]{0,20}?\bof\s+the\b[^.\n]{0,20}?\btasks?\b`,
+    // EN totality idioms ("run all", "finish everything", "complete the whole goal",
+    // "continue until no tasks remain", "until all tasks are done").
+    String.raw`\brun\s+(?:all|everything)\b(?!\s+(?:of\s+)?(?:the\s+)?(?:(?:unit|e2e|integration|smoke)\s+)?(?:tests?|specs?|checks?|lint|builds?|suites?|migrations?)\b)|\b(?:finish|complete|do)\s+(?:everything|all\s+of\s+it|the\s+(?:whole|entire)\s+(?:goal|backlog|list|plan))\b|\b(?:continue|keep\s+going|work)\s+until\s+(?:all\s+tasks?\s+(?:are\s+)?done|no\s+tasks?\s+(?:remain|are\s+left))\b|\buntil\s+(?:all\s+)?tasks?\s+(?:are\s+)?(?:done|complete[d]?|finished)\b|\bcontinue\s+until\s+nothing\s+(?:is\s+)?left\b`,
+    // VN (diacritic + ascii fallbacks): chạy hết / chạy tất cả task / làm hết các task còn lại /
+    // hoàn thành toàn bộ / cho đến khi không còn task.
+    String.raw`ch(?:ạy|ay)\s+h(?:ế|e)t|ch(?:ạy|ay)\s+t(?:ấ|a)t\s+c(?:ả|a)|l(?:à|a)m\s+h(?:ế|e)t|ho(?:à|a)n\s+th(?:à|a)nh\s+(?:to(?:à|a)n\s+b(?:ộ|o)|h(?:ế|e)t)|t(?:ấ|a)t\s+c(?:ả|a)\s+(?:c(?:á|a)c\s+)?tasks?|to(?:à|a)n\s+b(?:ộ|o)\s+(?:c(?:á|a)c\s+)?tasks?|cho\s+đ(?:ế|e)n\s+khi\s+kh(?:ô|o)ng\s+c(?:ò|o)n\s+tasks?`,
+  ].join('|'),
+  'iu',
+);
+
+/**
+ * Goal-level loop phrase detector. Pure text matching — deliberately separate
+ * from the structured intent classification above.
+ * @returns {boolean}
+ */
+export function isRunAllRequest(text) {
+  const t = String(text ?? '');
+  if (!t.trim()) return false;
+  // Read/list requests and plan-only / negated asks never authorize a backlog run.
+  if (RUN_ALL_READ_RE.test(t) || RUN_ALL_VETO_RE.test(t)) return false;
+  if (SINGLE_TASK_REF_RE.test(t)) return false;
+  return RUN_ALL_RE.test(t);
+}
+
+const RUN_ALL_READ_RE = /^\s*(?:please\s+)?(?:show|list|view|display|print|count|xem|liệt\s+kê|hiển\s+thị)\b/iu;
+const RUN_ALL_VETO_RE = new RegExp(
+  [
+    String.raw`\b(?:do\s+not|don'?t|dont|never|no\s+need\s+to|without|not)\b[^.\n]{0,30}?\b(?:run|execute|do|process|implement|finish|complete|handle)\b`,
+    String.raw`\b(?:plan|planning)[\s-]+only\b|\bonly\s+(?:create|write|make|draft)\s+(?:a\s+|the\s+)?plan`,
+    String.raw`(?:kh(?:ô|o)ng|đ(?:ừ|u)ng|dung|ch(?:ư|u)a)\s+(?:được\s+|duoc\s+|cần\s+|can\s+)?(?:ch(?:ạ|a)y|l(?:à|a)m|th(?:ự|u)c\s+hi(?:ệ|e)n|implement)`,
+    String.raw`ch(?:ỉ|i)\s+(?:t(?:ạ|a)o|vi(?:ế|e)t|l(?:ậ|a)p)\s+(?:plan|k(?:ế|e)\s+ho(?:ạ|a)ch)`,
+  ].join('|'),
+  'iu',
+);
+const SINGLE_TASK_REF_RE = /\b(?:task|việc|viec)[\s_-]*#?\d+\b|\bTASK-\d+\b/i;
+
+/**
+ * Shared phase lookup for BOTH Stop paths (Claude `execution-ledger --evaluate-stop` and the
+ * omp bridge's in-process `runSessionStop`). Returns the current intent only when the scan
+ * is conclusive and it is one of create/review/neutral — the phases that change what the
+ * completion gate may demand. fullstack/implement, unknown and unreadable all return null,
+ * which keeps the normal (strict) gate: a lost read never relaxes enforcement.
+ */
+export async function resolveStopPhase(transcriptPath, opts = {}) {
+  try {
+    const { intent, known } = await transcriptHandoffIntent(transcriptPath, opts);
+    if (!known) return null;
+    return intent === 'create' || intent === 'review' || intent === 'neutral' ? intent : null;
+  } catch {
+    return null;
+  }
+}
+
+// Subagent inheritance. A delegated omp session is its own transcript (own session id, no command
+// tag) whose first record is `{type:"session", parentSession:<parent transcript path>}`; the
+// parent's command authority must follow the delegation. Walks at most `maxDepth` parents, each
+// scan bounded by the normal budget; a missing/unreadable link is `known:false` (never relaxed).
+export async function transcriptHandoffIntentInherited(transcriptPath, { maxDepth = 3, ...opts } = {}) {
+  let current = transcriptPath;
+  for (let depth = 0; depth <= maxDepth; depth += 1) {
+    const scan = await transcriptHandoffIntent(current, opts);
+    // A parent link that cannot be read is reported (never relaxed): the caller fails closed
+    // against the parent's session marker instead of treating the child as unrestricted.
+    if (!scan.known) return depth > 0 ? { ...scan, unresolvedParent: current } : scan;
+    if (scan.intent) return scan;
+    const parent = await readParentSession(current);
+    if (!parent) return scan;
+    current = parent;
+  }
+  return { intent: null, known: false, unresolvedParent: current };
+}
+
+async function readParentSession(transcriptPath) {
+  let handle;
+  try {
+    handle = await fs.open(transcriptPath, 'r');
+    const buf = Buffer.allocUnsafe(8192);
+    const { bytesRead } = await handle.read(buf, 0, buf.length, 0);
+    for (const line of buf.toString('utf8', 0, bytesRead).split('\n').slice(0, 4)) {
+      if (!line.includes('"parentSession"')) continue;
+      try {
+        const rec = JSON.parse(line);
+        if (rec?.type === 'session' && typeof rec.parentSession === 'string' && rec.parentSession.trim()) {
+          return rec.parentSession;
+        }
+      } catch { /* header larger than the probe window: treat as no link */ }
+    }
+    return null;
+  } catch {
+    return null;
+  } finally {
+    await handle?.close().catch(() => {});
+  }
+}

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',
   );