@tea-agent/loop-agent 0.31.1 → 0.32.0

package/dist/worker/observability/read-model.js

@@ -5,6 +5,7 @@ import { truncateUtf8Preview } from "../../shared/preview.js";
 import { parseWorkerEventLine } from "./events.js";
 import { readBoundedJsonlTail } from "./event-history.js";
 import { getTaskPoolRoot, listLegacyStateFiles, listTaskPoolStates, } from "../pool/run-store.js";
+import { listRunOwners } from "../pool/run-owner-store.js";
 import { assessDagRunLiveness, assessDagRunRecoveryEligibility, deriveDagRunEffectiveStatus, } from "../../workflows/dag/lifecycle.js";
 import { parseDagSpec, resolveModelForTask, } from "../../workflows/dag/types.js";
 import { loadFeatureDecisionModels } from "../feature/decision-loader.js";
@@ -51,13 +52,14 @@ export async function buildGlobalSnapshot(options) {
         const staleThresholdMs = options.staleThresholdMs ?? 90_000;
         const quietThresholdMs = options.quietThresholdMs ?? 60_000;
         const taskPoolPresent = existsSync(getTaskPoolRoot(repoRoot));
-        const [eventsLoad, ledgerLoad, ledgerBatches, statesLoad, handoffs, dagRuns,] = await Promise.all([
+        const [eventsLoad, ledgerLoad, ledgerBatches, statesLoad, handoffs, dagRuns, owners,] = await Promise.all([
             loadObservabilityEvents(repoRoot),
             loadLedgerRuns(repoRoot),
             loadLedgerBatches(repoRoot),
             loadStateRecords(repoRoot),
             loadFailureHandoffs(repoRoot),
             loadDagRuns(repoRoot, now()),
+            listRunOwners(repoRoot).catch(() => []),
         ]);
         const events = eventsLoad.events;
         const ledgerRuns = ledgerLoad.runs;
@@ -74,7 +76,7 @@ export async function buildGlobalSnapshot(options) {
         for (const state of statesLoad.legacyCandidates) {
             mergeLegacyStateRecord(taskMap, state, identityWarnings);
         }
-        const workerRunFeatureIndex = buildWorkerRunFeatureIndex(ledgerRuns, taskMap);
+        const workerRunFeatureIndex = buildWorkerRunFeatureIndex(ledgerRuns, taskMap, owners);
         mergeEvents(taskMap, events, workerRunFeatureIndex, identityWarnings);
         mergeHandoffs(taskMap, handoffs);
         applyStaleDetection(taskMap, now(), staleThresholdMs, quietThresholdMs);
@@ -274,6 +276,15 @@ function toPublicTaskSummary(task) {
     const { timeoutMs: _to, commandStartedAt: _cs, ...rest } = task;
     return rest;
 }
+function isLivePoolStatus(status) {
+    return (status === "Running" ||
+        status === "Queued" ||
+        status === "AgentCompleted" ||
+        status === "VerificationRunning" ||
+        status === "HumanReview" ||
+        status === "Ready" ||
+        status === "Draft");
+}
 function mergeStateRecord(taskMap, state, warnings) {
     const featureId = state.featureId?.trim();
     if (!featureId) {
@@ -286,13 +297,19 @@ function mergeStateRecord(taskMap, state, warnings) {
         featureId,
         status: "unknown",
     };
+    const live = isLivePoolStatus(state.status);
+    const mapped = mapStateStatus(state.status);
     taskMap.set(key, {
         ...existing,
         featureId,
-        status: existing.status !== "unknown"
-            ? existing.status
-            : mapStateStatus(state.status),
-        workerRunId: existing.workerRunId ?? state.workerRunId,
+        // Live Task Pool state is the current attempt truth; do not keep a stale
+        // terminal ledger workerRunId/status over an active Running attempt.
+        status: live
+            ? mapped
+            : existing.status !== "unknown"
+                ? existing.status
+                : mapped,
+        workerRunId: state.workerRunId ?? existing.workerRunId,
         updatedAt: state.updatedAt ?? existing.updatedAt,
         artifactRefs: mergeArtifactRefs(existing.artifactRefs, {
             runRecordPath: state.lastRunRecordPath,
@@ -362,10 +379,10 @@ function mergeLedgerRun(taskMap, run, warnings) {
     });
 }
 /**
- * Build workerRunId → featureId unique index from ledger + already-owned task rows.
+ * Build workerRunId → featureId unique index from ledger + already-owned task rows + run owners.
  * Ambiguous (0 or N) mappings are omitted so callers treat them as unowned.
  */
-function buildWorkerRunFeatureIndex(ledgerRuns, taskMap) {
+function buildWorkerRunFeatureIndex(ledgerRuns, taskMap, owners) {
     const candidates = new Map();
     const add = (workerRunId, featureId) => {
         const wr = workerRunId?.trim();
@@ -387,6 +404,11 @@ function buildWorkerRunFeatureIndex(ledgerRuns, taskMap) {
             add(task.workerRunId, task.featureId);
         }
     }
+    if (owners) {
+        for (const owner of owners) {
+            add(owner.workerRunId, owner.featureId);
+        }
+    }
     const unique = new Map();
     for (const [workerRunId, features] of candidates) {
         if (features.size === 1) {
@@ -397,15 +419,16 @@ function buildWorkerRunFeatureIndex(ledgerRuns, taskMap) {
 }
 function mergeEvents(taskMap, events, workerRunFeatureIndex, warnings) {
     const sorted = [...events].sort((a, b) => a.at.localeCompare(b.at));
+    const unownedKeys = new Set();
     for (const event of sorted) {
         if (event.taskId) {
-            applyTaskEvent(taskMap, event, workerRunFeatureIndex, warnings);
+            applyTaskEvent(taskMap, event, workerRunFeatureIndex, warnings, unownedKeys);
         }
     }
 }
-function applyTaskEvent(taskMap, event, workerRunFeatureIndex, warnings) {
+function applyTaskEvent(taskMap, event, workerRunFeatureIndex, warnings, unownedKeys) {
     const taskId = event.taskId;
-    const featureId = resolveEventFeatureId(event, taskMap, workerRunFeatureIndex, warnings);
+    const featureId = resolveEventFeatureId(event, taskMap, workerRunFeatureIndex, warnings, unownedKeys);
     if (!featureId)
         return;
     const key = taskIdentityKey(featureId, taskId);
@@ -416,28 +439,46 @@ function applyTaskEvent(taskMap, event, workerRunFeatureIndex, warnings) {
     };
     taskMap.set(key, applyEventToSummary(existing, event));
 }
-function resolveEventFeatureId(event, taskMap, workerRunFeatureIndex, warnings) {
+function resolveEventFeatureId(event, taskMap, workerRunFeatureIndex, warnings, unownedKeys) {
     const taskId = event.taskId;
     if (!taskId)
         return undefined;
+    const eventFeatureId = event.featureId?.trim();
     if (event.workerRunId) {
         const fromIndex = workerRunFeatureIndex.get(event.workerRunId);
+        if (eventFeatureId && fromIndex && eventFeatureId !== fromIndex) {
+            pushOwnershipWarning(warnings, unownedKeys, `ownership conflict for workerRunId ${event.workerRunId}: event featureId ${eventFeatureId} vs index ${fromIndex}`, event.workerRunId);
+            return undefined;
+        }
+        if (eventFeatureId)
+            return eventFeatureId;
         if (fromIndex)
             return fromIndex;
-        // Fall through: maybe a single existing composite row already owns this workerRunId.
         const byWorkerRun = [...taskMap.values()].filter((task) => task.workerRunId === event.workerRunId && Boolean(task.featureId));
         if (byWorkerRun.length === 1)
             return byWorkerRun[0].featureId;
     }
-    // Unique taskId ownership in current map (single Feature).
+    else if (eventFeatureId) {
+        return eventFeatureId;
+    }
     const byTaskId = [...taskMap.values()].filter((task) => task.taskId === taskId && Boolean(task.featureId));
     if (byTaskId.length === 1)
         return byTaskId[0].featureId;
-    warnings?.push(`unowned event ${event.type} for task ${taskId}` +
+    pushOwnershipWarning(warnings, unownedKeys, `unowned event ${event.type} for task ${taskId}` +
         (event.workerRunId ? ` workerRunId ${event.workerRunId}` : "") +
-        ` cannot uniquely resolve featureId; excluded from task projection`);
+        ` cannot uniquely resolve featureId; excluded from task projection`, event.workerRunId ?? `${taskId}:${event.type}`);
     return undefined;
 }
+function pushOwnershipWarning(warnings, unownedKeys, message, key) {
+    if (!warnings)
+        return;
+    if (unownedKeys) {
+        if (unownedKeys.has(key))
+            return;
+        unownedKeys.add(key);
+    }
+    warnings.push(message);
+}
 function applyEventToSummary(existing, event) {
     const updated = {
         ...existing,
@@ -489,6 +530,7 @@ function applyEventToSummary(existing, event) {
 }
 function buildHistoricalRunMap(ledgerRuns, events, workerRunFeatureIndex = new Map(), warnings) {
     const runMap = new Map();
+    const unownedKeys = new Set();
     for (const run of ledgerRuns) {
         // History map is keyed by workerRunId (run-scoped); featureId still required when present.
         runMap.set(run.workerRunId, {
@@ -515,13 +557,18 @@ function buildHistoricalRunMap(ledgerRuns, events, workerRunFeatureIndex = new M
             continue;
         const existing = runMap.get(event.workerRunId);
         if (existing) {
+            if (event.featureId?.trim() &&
+                existing.featureId &&
+                event.featureId.trim() !== existing.featureId) {
+                pushOwnershipWarning(warnings, unownedKeys, `ownership conflict for workerRunId ${event.workerRunId}: event featureId ${event.featureId} vs historical ${existing.featureId}`, event.workerRunId);
+                continue;
+            }
             runMap.set(event.workerRunId, applyEventToSummary(existing, event));
             continue;
         }
-        // Only invent a historical row when workerRunId uniquely maps to a feature.
-        const featureId = workerRunFeatureIndex.get(event.workerRunId);
+        const featureId = event.featureId?.trim() || workerRunFeatureIndex.get(event.workerRunId);
         if (!featureId) {
-            warnings?.push(`unowned historical event ${event.type} for task ${event.taskId} workerRunId ${event.workerRunId} cannot uniquely resolve featureId; excluded from historical run map`);
+            pushOwnershipWarning(warnings, unownedKeys, `unowned historical event ${event.type} for task ${event.taskId} workerRunId ${event.workerRunId} cannot uniquely resolve featureId; excluded from historical run map`, event.workerRunId);
             continue;
         }
         runMap.set(event.workerRunId, applyEventToSummary({

package/dist/worker/pool/attempt-identity.js

@@ -0,0 +1,41 @@
+/**
+ * Canonical Worker Attempt identity (Phase 1).
+ * All Task-scoped ownership / events / begin transactions must carry this shape.
+ */
+export function assertWorkerAttemptIdentity(value, label = "WorkerAttemptIdentity") {
+    if (!value || typeof value !== "object") {
+        throw new Error(`${label} is required`);
+    }
+    for (const key of ["featureId", "taskId", "workerRunId", "batchRunId"]) {
+        const field = value[key];
+        if (typeof field !== "string" || field.trim().length === 0) {
+            throw new Error(`${label}.${key} is required`);
+        }
+    }
+    if (value.schemaVersion !== 1 && value.schemaVersion !== undefined) {
+        throw new Error(`${label}.schemaVersion must be 1`);
+    }
+}
+export function createWorkerAttemptIdentity(input) {
+    const identity = {
+        schemaVersion: 1,
+        featureId: input.featureId.trim(),
+        taskId: input.taskId.trim(),
+        workerRunId: input.workerRunId.trim(),
+        batchRunId: input.batchRunId.trim(),
+    };
+    assertWorkerAttemptIdentity(identity);
+    return identity;
+}
+export function identitiesEqual(a, b) {
+    return (a.featureId === b.featureId &&
+        a.taskId === b.taskId &&
+        a.workerRunId === b.workerRunId &&
+        a.batchRunId === b.batchRunId);
+}
+export function ownerMatchesIdentity(owner, identity) {
+    return (owner.featureId === identity.featureId &&
+        owner.taskId === identity.taskId &&
+        owner.workerRunId === identity.workerRunId &&
+        owner.batchRunId === identity.batchRunId);
+}

package/dist/worker/pool/attempt-lease.js

@@ -0,0 +1,184 @@
+import { randomBytes } from "node:crypto";
+import { mkdir, readFile, readdir, unlink } from "node:fs/promises";
+import path from "node:path";
+import { writeJsonAtomic } from "../../infrastructure/harness/atomic-write.js";
+import { assertSafeTaskPoolId, getTaskPoolRoot, } from "./run-store.js";
+import { TASK_POOL_STATE_ERROR_CODES, TaskPoolStateError } from "./types.js";
+export function getAttemptLeasesRoot(repoRoot) {
+    return path.join(getTaskPoolRoot(repoRoot), "leases");
+}
+export function getAttemptLeasePath(repoRoot, featureId, taskId) {
+    assertSafeTaskPoolId(featureId, "featureId");
+    assertSafeTaskPoolId(taskId, "taskId");
+    const leasePath = path.join(getAttemptLeasesRoot(repoRoot), featureId, `${taskId}.json`);
+    const root = path.resolve(getAttemptLeasesRoot(repoRoot));
+    const resolved = path.resolve(leasePath);
+    const relative = path.relative(root, resolved);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new TaskPoolStateError(TASK_POOL_STATE_ERROR_CODES.PATH_MISMATCH, `attempt lease path escapes leases root: ${leasePath}`);
+    }
+    return leasePath;
+}
+function isLeaseRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const record = value;
+    return (record.schemaVersion === 1 &&
+        typeof record.featureId === "string" &&
+        typeof record.taskId === "string" &&
+        typeof record.workerRunId === "string" &&
+        typeof record.batchRunId === "string" &&
+        typeof record.token === "string" &&
+        typeof record.acquiredAt === "string" &&
+        typeof record.renewedAt === "string");
+}
+export async function readAttemptLease(repoRoot, featureId, taskId) {
+    const leasePath = getAttemptLeasePath(repoRoot, featureId, taskId);
+    try {
+        const raw = await readFile(leasePath, "utf-8");
+        const parsed = JSON.parse(raw);
+        return isLeaseRecord(parsed) ? parsed : undefined;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+/**
+ * Acquire Task-scoped attempt lease before beginWorkerAttempt.
+ * Same identity+token reuse is idempotent; different active identity → conflict.
+ */
+export async function acquireAttemptLease(input) {
+    const now = input.now ?? new Date();
+    const existing = await readAttemptLease(input.repoRoot, input.featureId, input.taskId);
+    if (existing) {
+        if (existing.workerRunId === input.workerRunId &&
+            existing.batchRunId === input.batchRunId &&
+            existing.featureId === input.featureId &&
+            existing.taskId === input.taskId) {
+            return { status: "idempotent-reuse", lease: existing };
+        }
+        throw new TaskPoolStateError(TASK_POOL_STATE_ERROR_CODES.CONFLICT, `attempt-lease-conflict for ${input.featureId}/${input.taskId}: held by ${existing.workerRunId}`);
+    }
+    const lease = {
+        schemaVersion: 1,
+        featureId: input.featureId,
+        taskId: input.taskId,
+        workerRunId: input.workerRunId,
+        batchRunId: input.batchRunId,
+        acquiredAt: now.toISOString(),
+        renewedAt: now.toISOString(),
+        token: `atk-${randomBytes(8).toString("hex")}`,
+        ownerProcess: { pid: process.pid },
+        ...(input.revisionId ? { revisionId: input.revisionId } : {}),
+        ...(input.controllerAnchor
+            ? { controllerAnchor: input.controllerAnchor }
+            : {}),
+    };
+    await mkdir(path.dirname(getAttemptLeasePath(input.repoRoot, input.featureId, input.taskId)), {
+        recursive: true,
+    });
+    await writeJsonAtomic(getAttemptLeasePath(input.repoRoot, input.featureId, input.taskId), lease, { repoRoot: input.repoRoot });
+    const confirmed = await readAttemptLease(input.repoRoot, input.featureId, input.taskId);
+    if (!confirmed) {
+        throw new Error(`failed to persist attempt lease for ${input.featureId}/${input.taskId}`);
+    }
+    if (confirmed.workerRunId !== input.workerRunId) {
+        throw new TaskPoolStateError(TASK_POOL_STATE_ERROR_CODES.CONFLICT, `attempt-lease-conflict race for ${input.featureId}/${input.taskId}`);
+    }
+    return { status: "acquired", lease: confirmed };
+}
+export async function renewAttemptLease(input) {
+    const existing = await readAttemptLease(input.repoRoot, input.featureId, input.taskId);
+    if (!existing) {
+        throw new TaskPoolStateError(TASK_POOL_STATE_ERROR_CODES.CONFLICT, `cannot renew missing lease for ${input.featureId}/${input.taskId}`);
+    }
+    if (existing.token !== input.token || existing.workerRunId !== input.workerRunId) {
+        throw new TaskPoolStateError(TASK_POOL_STATE_ERROR_CODES.CONFLICT, `cannot renew lease: CAS token/identity mismatch for ${input.featureId}/${input.taskId}`);
+    }
+    const renewed = {
+        ...existing,
+        renewedAt: (input.now ?? new Date()).toISOString(),
+    };
+    await writeJsonAtomic(getAttemptLeasePath(input.repoRoot, input.featureId, input.taskId), renewed, { repoRoot: input.repoRoot });
+    return renewed;
+}
+/**
+ * Release active lease after terminal/recovery evidence. Moves to lease-history then deletes active locator.
+ */
+export async function releaseAttemptLease(input) {
+    const existing = await readAttemptLease(input.repoRoot, input.featureId, input.taskId);
+    if (!existing)
+        return;
+    if (existing.token !== input.token || existing.workerRunId !== input.workerRunId) {
+        throw new TaskPoolStateError(TASK_POOL_STATE_ERROR_CODES.CONFLICT, `cannot release lease: CAS token/identity mismatch for ${input.featureId}/${input.taskId}`);
+    }
+    const historyRoot = path.join(getAttemptLeasesRoot(input.repoRoot), "_history");
+    await mkdir(historyRoot, { recursive: true });
+    const historyPath = path.join(historyRoot, `${input.featureId}__${input.taskId}__${existing.workerRunId}.json`);
+    const activePath = getAttemptLeasePath(input.repoRoot, input.featureId, input.taskId);
+    await writeJsonAtomic(historyPath, {
+        ...existing,
+        releasedAt: (input.now ?? new Date()).toISOString(),
+    }, { repoRoot: input.repoRoot });
+    await unlink(activePath).catch(() => { });
+}
+export function decideAttemptLeaseReclaim(input) {
+    if (input.hasTerminalEvidence) {
+        return {
+            status: "reclaim-allowed",
+            reason: "terminal evidence present; active lease should have been released",
+        };
+    }
+    if (input.liveness === "healthy" || input.liveness === "recoverable") {
+        return {
+            status: "keep",
+            reason: `lease held by ${input.liveness} attempt; do not steal`,
+        };
+    }
+    if (input.liveness === "conflict") {
+        return {
+            status: "keep",
+            reason: "identity conflict requires human-review before reclaim",
+        };
+    }
+    return {
+        status: "reclaim-allowed",
+        reason: `lease reclaim allowed after ${input.liveness} reconcile audit`,
+    };
+}
+export async function listAttemptLeases(repoRoot) {
+    const root = getAttemptLeasesRoot(repoRoot);
+    let featureDirs;
+    try {
+        featureDirs = await readdir(root);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    const leases = [];
+    for (const featureId of featureDirs) {
+        if (featureId.startsWith("_"))
+            continue;
+        const featureRoot = path.join(root, featureId);
+        let entries;
+        try {
+            entries = await readdir(featureRoot);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.endsWith(".json"))
+                continue;
+            const taskId = entry.slice(0, -".json".length);
+            const lease = await readAttemptLease(repoRoot, featureId, taskId);
+            if (lease)
+                leases.push(lease);
+        }
+    }
+    return leases;
+}

package/dist/worker/pool/attempt-transition.js

@@ -0,0 +1,210 @@
+import { isSafeRetryDecision, resolveWorkerRecoveryDecision, } from "./recovery-decision.js";
+/**
+ * Central Attempt transition reducer. Callers must not invent parallel state writers.
+ */
+export function reduceAttemptTransition(input) {
+    const { identity, from, event } = input;
+    const nowIso = new Date().toISOString();
+    switch (event.type) {
+        case "attempt-registered": {
+            return {
+                nextState: {
+                    schemaVersion: 2,
+                    featureId: identity.featureId,
+                    taskId: identity.taskId,
+                    status: "Running",
+                    updatedAt: nowIso,
+                    workerRunId: identity.workerRunId,
+                },
+                recovery: { recommendedAction: "none", reason: "attempt registered" },
+            };
+        }
+        case "heartbeat": {
+            if (!from) {
+                throw new Error("heartbeat requires existing attempt state");
+            }
+            return {
+                nextState: { ...from, updatedAt: nowIso },
+                recovery: resolveWorkerRecoveryDecision(input.facts ?? { state: from }),
+            };
+        }
+        case "finalize-success": {
+            return {
+                nextState: {
+                    schemaVersion: 2,
+                    featureId: identity.featureId,
+                    taskId: identity.taskId,
+                    status: "Done",
+                    updatedAt: event.terminalRun.recordedAt,
+                    workerRunId: identity.workerRunId,
+                    ...(event.terminalRun.runRecordPath
+                        ? { lastRunRecordPath: event.terminalRun.runRecordPath }
+                        : {}),
+                },
+                terminalRun: event.terminalRun,
+                recovery: { recommendedAction: "none", reason: "terminal success" },
+                auditEvent: {
+                    schemaVersion: 1,
+                    at: event.terminalRun.recordedAt,
+                    type: "task-run-recorded",
+                    batchRunId: event.terminalRun.batchRunId,
+                    workerRunId: identity.workerRunId,
+                    taskId: identity.taskId,
+                    featureId: identity.featureId,
+                    status: "succeeded",
+                },
+            };
+        }
+        case "finalize-failure": {
+            const failureV2 = event.failureV2 ??
+                event.terminalRun.failureV2 ??
+                undefined;
+            const recovery = resolveWorkerRecoveryDecision({
+                state: {
+                    status: "Failed",
+                    workerRunId: identity.workerRunId,
+                    failure: event.terminalRun.failure,
+                    failureV2,
+                },
+                terminalRun: event.terminalRun,
+                ...(input.facts ?? {}),
+            });
+            const nextStatus = failureV2?.recommendedAction === "revise-contract" ||
+                failureV2?.retryability === "requires-contract-revision" ||
+                failureV2?.retryability === "requires-human"
+                ? failureV2.retryability === "requires-contract-revision"
+                    ? "Blocked"
+                    : "Failed"
+                : "Failed";
+            // Safe terminal run-error / failed → Failed so retry does not need mark-failed.
+            const status = event.terminalRun.status === "run-error" &&
+                failureV2?.retryability === "safe"
+                ? "Failed"
+                : event.terminalRun.status === "run-error" &&
+                    !failureV2 &&
+                    event.terminalRun.failure?.category === "EnvFailure"
+                    ? "Failed"
+                    : event.terminalRun.status === "run-error" && !failureV2
+                        ? "Blocked"
+                        : nextStatus === "Blocked"
+                            ? "Blocked"
+                            : "Failed";
+            return {
+                nextState: {
+                    schemaVersion: 2,
+                    featureId: identity.featureId,
+                    taskId: identity.taskId,
+                    status,
+                    updatedAt: event.terminalRun.recordedAt,
+                    workerRunId: identity.workerRunId,
+                    ...(event.terminalRun.runRecordPath
+                        ? { lastRunRecordPath: event.terminalRun.runRecordPath }
+                        : {}),
+                    ...(event.terminalRun.failure
+                        ? { failure: event.terminalRun.failure }
+                        : {}),
+                    ...(failureV2 ? { failureV2 } : {}),
+                },
+                terminalRun: event.terminalRun,
+                recovery,
+                auditEvent: {
+                    schemaVersion: 1,
+                    at: event.terminalRun.recordedAt,
+                    type: "task-run-recorded",
+                    batchRunId: event.terminalRun.batchRunId,
+                    workerRunId: identity.workerRunId,
+                    taskId: identity.taskId,
+                    featureId: identity.featureId,
+                    status: event.terminalRun.status,
+                },
+            };
+        }
+        case "retry-requested": {
+            if (!from) {
+                throw new Error("retry requires existing attempt state");
+            }
+            if (from.status === "Done") {
+                throw new Error(`cannot retry ${identity.taskId}: Done attempts are immutable`);
+            }
+            const decision = resolveWorkerRecoveryDecision({
+                state: from,
+                ...(input.facts ?? {}),
+            });
+            if (!isSafeRetryDecision(decision) && from.status !== "Failed") {
+                throw new Error(`cannot retry ${identity.taskId}: recovery action is ${decision.recommendedAction} (${decision.reason})`);
+            }
+            if (from.status !== "Failed") {
+                throw new Error(`cannot retry ${identity.taskId}: expected Failed state, found ${from.status}`);
+            }
+            if (!from.workerRunId) {
+                throw new Error(`cannot retry ${identity.taskId}: failed state is missing workerRunId`);
+            }
+            const retryRequestedAt = event.now.toISOString();
+            return {
+                nextState: {
+                    schemaVersion: 2,
+                    featureId: identity.featureId,
+                    taskId: identity.taskId,
+                    status: "Ready",
+                    updatedAt: retryRequestedAt,
+                    workerRunId: from.workerRunId,
+                    retryOfWorkerRunId: from.workerRunId,
+                    retryRequestedAt,
+                    ...(event.reason ? { retryReason: event.reason } : {}),
+                    ...(from.lastRunRecordPath
+                        ? { lastRunRecordPath: from.lastRunRecordPath }
+                        : {}),
+                    ...(from.failure ? { failure: from.failure } : {}),
+                    ...(from.failureV2 ? { failureV2: from.failureV2 } : {}),
+                },
+                recovery: {
+                    recommendedAction: "retry",
+                    reason: event.reason ?? "operator requested retry",
+                    retryability: "safe",
+                },
+                auditEvent: {
+                    schemaVersion: 1,
+                    at: retryRequestedAt,
+                    type: "task-retry-requested",
+                    taskId: identity.taskId,
+                    featureId: identity.featureId,
+                    previousWorkerRunId: from.workerRunId,
+                    ...(event.reason ? { reason: event.reason } : {}),
+                },
+            };
+        }
+        case "mark-failed": {
+            if (!from) {
+                throw new Error("mark-failed requires existing attempt state");
+            }
+            if (from.status === "Done") {
+                throw new Error(`cannot mark-failed ${identity.taskId}: Done is immutable`);
+            }
+            const at = event.now.toISOString();
+            return {
+                nextState: {
+                    ...from,
+                    schemaVersion: 2,
+                    featureId: identity.featureId,
+                    status: "Failed",
+                    updatedAt: at,
+                    operatorRecovery: {
+                        action: "mark-failed",
+                        reason: event.reason,
+                        workerRunId: from.workerRunId,
+                        at,
+                    },
+                },
+                recovery: {
+                    recommendedAction: "retry",
+                    reason: "emergency mark-failed projection",
+                    retryability: "safe",
+                },
+            };
+        }
+        default: {
+            const _exhaustive = event;
+            throw new Error(`unsupported attempt lifecycle event: ${JSON.stringify(_exhaustive)}`);
+        }
+    }
+}

package/dist/worker/pool/begin-attempt-with-lease.js

@@ -0,0 +1,26 @@
+import { assertCompatibleBeforeWrite, evaluateControllerCompatibility, } from "../loop-agent/controller-protocol.js";
+import { acquireAttemptLease, } from "./attempt-lease.js";
+import { beginWorkerAttempt, } from "./begin-attempt.js";
+/**
+ * Phase 4/5 begin path: optional protocol preflight → acquire Task lease →
+ * register owner → Running state.
+ */
+export async function beginWorkerAttemptWithLease(input) {
+    if (!input.skipProtocolPreflight && input.protocolEnvelope !== undefined) {
+        assertCompatibleBeforeWrite(evaluateControllerCompatibility({ envelope: input.protocolEnvelope }));
+    }
+    const leaseRegistration = await acquireAttemptLease({
+        repoRoot: input.repoRoot,
+        featureId: input.featureId,
+        taskId: input.taskId,
+        workerRunId: input.workerRunId,
+        batchRunId: input.batchRunId,
+        ...(input.revisionId ? { revisionId: input.revisionId } : {}),
+        ...(input.controllerAnchor
+            ? { controllerAnchor: input.controllerAnchor }
+            : {}),
+        ...(input.now ? { now: input.now } : {}),
+    });
+    const begun = await beginWorkerAttempt(input);
+    return { ...begun, leaseRegistration };
+}