@osovv/vv-opencode 1.4.2 → 1.4.3-rc.1

package/dist/plugins/workflow/delegated.js

@@ -1,27 +1,37 @@
 // FILE: src/plugins/workflow/delegated.ts
-// VERSION: 1.0.0
+// VERSION: 2.0.0
 // START_MODULE_CONTRACT
-//   PURPOSE: Delegated work-item attempt ledger and explicit controller acceptance decisions with a checkpoint-authorized rework path.
-//   SCOPE: Delegated attempt allocation bound to host callIDs with per-session callID uniqueness, call-bound result application, call-bound host-terminal launch failure recorded as a distinct failed attempt (bounded evidence, no budget refund, no state advance), bounded controller decisions (accept / request_changes with rationale, evidence, and concerns disposition), acceptance history with rework revocation, and the two-attempt budget extended only by authorized rework. Pure domain transitions over WorkItemStoreData; no tool, session, or filesystem authorization here.
-//   DEPENDS: [src/plugins/workflow/protocol.ts (types), src/plugins/workflow/state.ts (types and shared helpers), src/plugins/workflow/transitions.ts]
-//   LINKS: [M-WORKFLOW-DELEGATED, M-WORKFLOW-STATE, M-WORKFLOW-TRANSITIONS, M-WORKFLOW-CHECKPOINTS, V-M-WORKFLOW-DELEGATED]
+//   PURPOSE: Delegated work-item attempt ledger with bounded recovery, terminal report-rejection settlement, and explicit controller acceptance decisions with a checkpoint-authorized rework path.
+//   SCOPE: Delegated attempt allocation bound to host callIDs with per-session callID uniqueness, call-bound result application, call-bound host-terminal launch failure recorded as a distinct failed attempt (bounded evidence, no budget refund, no state advance), bounded controller decisions (accept / request_changes with rationale, evidence, and concerns disposition), acceptance history with rework revocation, the two-attempt budget extended only by authorized rework or one-unit recovery grants, bounded recovery of stopped or exhausted unaccepted items (diagnosis, changed condition, verification references, stable recoveryId, optional root-user message authorization validated through a read-only lookup with replay protection), call-bound settlement of confirmed terminal protocol-invalid reports as report_rejected attempts with bounded diagnostics preserved substantive hard stops, and progress summaries exposing remaining budget and supported next actions. Pure domain transitions over WorkItemStoreData; no tool, session, or filesystem authorization here.
+//   DEPENDS: [src/plugins/workflow/protocol.ts (types), src/plugins/workflow/state.ts (types and shared helpers), src/plugins/workflow/transitions.ts, src/lib/workflow-contract.ts]
+//   LINKS: [M-WORKFLOW-DELEGATED, M-WORKFLOW-STATE, M-WORKFLOW-TRANSITIONS, M-WORKFLOW-CHECKPOINTS, M-WORKFLOW-CONTRACT, V-M-WORKFLOW-DELEGATED]
 //   ROLE: RUNTIME
 //   MAP_MODE: EXPORTS
 // END_MODULE_CONTRACT
 //
 // START_MODULE_MAP
 //   DELEGATED_BASE_ATTEMPTS - Initial controller-directed implementation attempt budget (initial plus one correction).
-//   DELEGATED_RATIONALE_MAX_CHARS - Maximum accepted rationale length.
-//   DELEGATED_EVIDENCE_MAX_CHARS - Maximum accepted single evidence-reference length.
-//   DELEGATED_EVIDENCE_MAX_REFS - Maximum accepted evidence-reference count.
+//   DELEGATED_RATIONALE_MAX_CHARS - Maximum accepted rationale, diagnosis, and changed-condition length.
+//   DELEGATED_EVIDENCE_MAX_CHARS - Maximum accepted single evidence/verification reference length.
+//   DELEGATED_EVIDENCE_MAX_REFS - Maximum accepted evidence/verification reference count.
+//   DELEGATED_RECOVERY_CODE_MAX_CHARS - Maximum accepted protocol error code stored in report rejections.
 //   DelegatedImplementerStatus - Implementer result statuses recordable on an attempt.
 //   DelegatedAttempt - One host-callID-bound implementation attempt.
-//   DelegatedAttemptStatus - Attempt lifecycle statuses (in_flight, completed, failed).
+//   DelegatedAttemptStatus - Attempt lifecycle statuses (in_flight, completed, failed, report_rejected).
+//   DelegatedAttemptReportRejection - Bounded rejected-report record for a terminal protocol-invalid result.
 //   DelegatedDecisionRecord - One recorded controller decision bound to an attempt.
 //   DelegatedAcceptanceRecord - One acceptance with optional later revocation.
 //   DelegatedReworkRecord - One checkpoint-authorized rework event.
-//   DelegatedWorkItemState - Full delegated-mode record extension.
+//   DelegatedRecoveryKind - One recovery unit kind (resume, autonomous grant, user grant).
+//   DelegatedRecoveryRecord - One bounded recovery event bound to its terminal target attempt.
+//   DelegatedWorkItemState - Full delegated-mode record extension including recovery history.
 //   DelegatedWriteScopeValidation - Result of validating declared write-scope text inputs.
+//   DelegatedRecoveryInputValidation - Shape accepted by validateDelegatedRecoveryInput.
+//   RecoveryUserMessageSnapshot - Identity and timing metadata of one candidate authorization message.
+//   LookupRecoveryUserMessage - Read-only authorization message lookup bound to the plugin SDK.
+//   RecoveryAuthorizationResult - Outcome of validating one root-user authorization reference.
+//   DelegatedProgressSummary - Inspectable budget, stop, and rejected-report snapshot with next action.
+//   DelegatedNextAction - Supported next action suggested by progress summaries.
 //   BeginDelegatedLaunchInput - Delegated launch input with session, item, and host callID.
 //   BeginDelegatedLaunchResult - Launch allocation outcome.
 //   ApplyDelegatedResultInput - Call-bound delegated result payload.
@@ -30,11 +40,20 @@
 //   DecideDelegatedWorkItemResult - Controller decision outcome.
 //   ReworkDelegatedWorkItemInput - Checkpoint-authorized rework request.
 //   ReworkDelegatedWorkItemResult - Authorized rework outcome.
-//   delegatedAttemptBudget - Allowed attempt count given consumed attempts and rework history.
+//   RecoverDelegatedWorkItemInput - Bounded recovery request with optional user authorization.
+//   RecoverDelegatedWorkItemResult - Recovery outcome with budget and kind, or a coded rejection.
+//   ApplyDelegatedReportRejectionInput - Call-bound terminal report-rejection payload.
+//   ApplyDelegatedReportRejectionResult - Report-rejection settlement outcome.
+//   delegatedAttemptBudget - Allowed attempt count given consumed attempts, rework, and recovery grants.
+//   delegatedRecoveryGrantCount - Number of budget-granting recovery entries in a history.
+//   delegatedAutonomousGrantConsumed - Whether the single autonomous grant is already recorded.
 //   currentDelegatedAcceptance - Currently applicable acceptance for a record.
+//   summarizeDelegatedProgress - Budget, terminal-state, and next-action summary for inspection.
 //   DelegatedDecisionInputValidation - Shape accepted by validateDelegatedDecisionInput.
 //   validateDelegatedWriteScope - Validates declared write-scope text into canonical normalized paths.
 //   validateDelegatedDecisionInput - Pure validation of decision text bounds.
+//   validateDelegatedRecoveryInput - Pure validation of recovery text bounds shared by tool and domain layers.
+//   validateRecoveryUserAuthorization - Validates one authorization reference against its root-session message snapshot.
 //   beginDelegatedLaunch - Allocate and bind one implementation attempt to a host callID.
 //   beginDelegatedLaunchInStore - Store-level delegated launch allocation.
 //   revertInFlightDelegatedLaunches - Reclaim attempts orphaned by a process restart boundary.
@@ -44,31 +63,48 @@
 //   ApplyDelegatedLaunchFailureResult - Host-terminal launch-failure outcome.
 //   applyDelegatedLaunchFailure - Record a confirmed host-terminal launch failure on its matching in-flight attempt.
 //   applyDelegatedLaunchFailureInStore - Store-level failed-attempt transition.
+//   applyDelegatedReportRejection - Settle one confirmed terminal protocol-invalid report on its call-bound attempt.
+//   applyDelegatedReportRejectionInStore - Store-level report-rejection settlement.
 //   decideDelegatedWorkItem - Record an explicit controller accept/request_changes decision.
 //   decideDelegatedWorkItemInStore - Store-level controller decision.
 //   reworkDelegatedWorkItem - Reopen an accepted item under validated checkpoint-failure authorization.
 //   reworkDelegatedWorkItemInStore - Store-level guarded rework reducer.
+//   recoverDelegatedWorkItem - Resume or grant exactly one additional attempt for a stopped or exhausted unaccepted item.
+//   recoverDelegatedWorkItemInStore - Store-level guarded recovery reducer.
 // END_MODULE_MAP
 //
 // START_CHANGE_SUMMARY
-//   LAST_CHANGE: [direct fix inFlightAttempt after failed worker launch - Record confirmed host-terminal launch failures as distinct failed attempts, enforce per-session callID uniqueness across items, and keep failed attempts out of acceptance decisions.]
+//   LAST_CHANGE: [C-WORKFLOW-BOUNDED-RECOVERY-R1 - Added bounded recovery with a single autonomous grant, replay-protected root-user message authorization, terminal report-rejection settlement preserving substantive hard stops, and recovery-aware budgets and progress summaries.]
 // END_CHANGE_SUMMARY
 import { cloneRecord, createRecordLookupKey } from "./state.js";
 import { getAllowedNextAgents } from "./transitions.js";
-import { normalizeDeclaredScopePath } from "../../lib/spec-lint.js";
+import { normalizeDeclaredScopePath } from "../../lib/workflow-contract.js";
 // START_BLOCK_DELEGATED_TYPES
 export const DELEGATED_BASE_ATTEMPTS = 2;
 export const DELEGATED_RATIONALE_MAX_CHARS = 2000;
 export const DELEGATED_EVIDENCE_MAX_CHARS = 512;
 export const DELEGATED_EVIDENCE_MAX_REFS = 8;
+export const DELEGATED_RECOVERY_CODE_MAX_CHARS = 128;
 // END_BLOCK_DELEGATED_TYPES
 // START_BLOCK_DELEGATED_HELPERS
 function toIsoNow() {
     return new Date().toISOString();
 }
-/** Allowed attempt count: the base budget plus one per authorized rework event. */
+/** Count of budget-granting recovery entries in a recovery history. */
+export function delegatedRecoveryGrantCount(history) {
+    return history.filter((entry) => entry.kind === "autonomous_grant" ||
+        entry.kind === "user_grant" ||
+        entry.kind === "advance_grant").length;
+}
+/** Allowed attempt count: base budget plus one per authorized rework or recovery grant. */
 export function delegatedAttemptBudget(state) {
-    return DELEGATED_BASE_ATTEMPTS + state.reworkHistory.length;
+    return (DELEGATED_BASE_ATTEMPTS +
+        state.reworkHistory.length +
+        delegatedRecoveryGrantCount(state.recoveryHistory));
+}
+/** Whether the single autonomous recovery grant is already recorded for this item. */
+export function delegatedAutonomousGrantConsumed(history) {
+    return history.some((entry) => entry.kind === "autonomous_grant");
 }
 /** Currently applicable acceptance for a record: the latest unrevoked acceptance. */
 export function currentDelegatedAcceptance(record) {
@@ -145,6 +181,184 @@ export function validateDelegatedDecisionInput(input) {
     }
     return { ok: true };
 }
+/** Pure validation of bounded recovery text shared by the tool layer and domain layer. */
+export function validateDelegatedRecoveryInput(input) {
+    const recoveryId = typeof input.recoveryId === "string" ? input.recoveryId.trim() : "";
+    if (recoveryId === "") {
+        return { ok: false, message: "recoveryId must be a non-empty string" };
+    }
+    if (recoveryId.length > DELEGATED_EVIDENCE_MAX_CHARS) {
+        return { ok: false, message: `recoveryId exceeds ${DELEGATED_EVIDENCE_MAX_CHARS} characters` };
+    }
+    const diagnosis = typeof input.diagnosis === "string" ? input.diagnosis.trim() : "";
+    if (diagnosis === "") {
+        return { ok: false, message: "diagnosis must be a non-empty string" };
+    }
+    if (diagnosis.length > DELEGATED_RATIONALE_MAX_CHARS) {
+        return { ok: false, message: `diagnosis exceeds ${DELEGATED_RATIONALE_MAX_CHARS} characters` };
+    }
+    const changedCondition = typeof input.changedCondition === "string" ? input.changedCondition.trim() : "";
+    if (changedCondition === "") {
+        return { ok: false, message: "changedCondition must be a non-empty string" };
+    }
+    if (changedCondition.length > DELEGATED_RATIONALE_MAX_CHARS) {
+        return {
+            ok: false,
+            message: `changedCondition exceeds ${DELEGATED_RATIONALE_MAX_CHARS} characters`,
+        };
+    }
+    if (!Array.isArray(input.verification) || input.verification.length === 0) {
+        return { ok: false, message: "verification must be a non-empty array of reference strings" };
+    }
+    if (input.verification.length > DELEGATED_EVIDENCE_MAX_REFS) {
+        return { ok: false, message: `verification exceeds ${DELEGATED_EVIDENCE_MAX_REFS} references` };
+    }
+    for (const reference of input.verification) {
+        const normalized = typeof reference === "string" ? reference.trim() : "";
+        if (normalized === "") {
+            return { ok: false, message: "verification references must be non-empty strings" };
+        }
+        if (normalized.length > DELEGATED_EVIDENCE_MAX_CHARS) {
+            return {
+                ok: false,
+                message: `verification reference exceeds ${DELEGATED_EVIDENCE_MAX_CHARS} characters`,
+            };
+        }
+    }
+    return { ok: true };
+}
+/**
+ * Validate one authorization reference against its root-session message
+ * snapshot. Provenance only: role, session identity, message identity, and a
+ * creation timestamp at or after the relevant stop. This check never
+ * interprets natural-language intent.
+ */
+export async function validateRecoveryUserAuthorization(input) {
+    let snapshot;
+    try {
+        snapshot = await input.lookup(input.owningSessionId, input.userMessageId);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            errorCode: "AUTHORIZATION_LOOKUP_FAILED",
+            message: `AUTHORIZATION_LOOKUP_FAILED: authorization message lookup failed: ${error.message}`,
+        };
+    }
+    if (!snapshot) {
+        return {
+            ok: false,
+            errorCode: "AUTHORIZATION_NOT_FOUND",
+            message: `AUTHORIZATION_NOT_FOUND: no message ${input.userMessageId} is observable in session ${input.owningSessionId}`,
+        };
+    }
+    if (snapshot.id !== undefined && snapshot.id !== input.userMessageId) {
+        return {
+            ok: false,
+            errorCode: "AUTHORIZATION_ID_MISMATCH",
+            message: `AUTHORIZATION_ID_MISMATCH: looked-up message ${snapshot.id} is not the referenced ${input.userMessageId}`,
+        };
+    }
+    if (snapshot.role !== "user") {
+        return {
+            ok: false,
+            errorCode: "AUTHORIZATION_NOT_USER_MESSAGE",
+            message: `AUTHORIZATION_NOT_USER_MESSAGE: message ${input.userMessageId} has role ${snapshot.role ?? "(unknown)"} instead of user`,
+        };
+    }
+    if (snapshot.sessionID !== input.owningSessionId) {
+        return {
+            ok: false,
+            errorCode: "AUTHORIZATION_SESSION_MISMATCH",
+            message: `AUTHORIZATION_SESSION_MISMATCH: message ${input.userMessageId} belongs to session ${snapshot.sessionID ?? "(unknown)"}, not ${input.owningSessionId}`,
+        };
+    }
+    if (typeof snapshot.timeCreatedMs !== "number" || !Number.isFinite(snapshot.timeCreatedMs)) {
+        return {
+            ok: false,
+            errorCode: "AUTHORIZATION_NOT_FOUND",
+            message: "AUTHORIZATION_NOT_FOUND: authorization message is missing verifiable timing metadata",
+        };
+    }
+    if (input.requireAfterMs !== undefined && snapshot.timeCreatedMs < input.requireAfterMs) {
+        return {
+            ok: false,
+            errorCode: "AUTHORIZATION_STALE",
+            message: `AUTHORIZATION_STALE: message ${input.userMessageId} predates the stop it must authorize`,
+        };
+    }
+    return { ok: true, timeCreatedMs: snapshot.timeCreatedMs };
+}
+/** Terminal timestamp (epoch ms) of one attempt, or undefined when unknown. */
+function terminalAttemptTimeMs(attempt) {
+    if (!attempt.completedAt)
+        return undefined;
+    const parsed = Date.parse(attempt.completedAt);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+/**
+ * Budget, terminal-state, and next-action summary for work-item inspection.
+ * The next action never suggests an ordinary launch the same state rejects.
+ */
+export function summarizeDelegatedProgress(record) {
+    const delegated = record.delegated;
+    if (!delegated) {
+        return {
+            attemptsConsumed: 0,
+            attemptBudget: 0,
+            remainingAttempts: 0,
+            hasInFlightAttempt: false,
+            recoveryGrants: 0,
+            autonomousGrantConsumed: false,
+            reportRejectedAttempts: 0,
+            nextAction: record.state === "closed" ? "closed" : "launch_implementer",
+        };
+    }
+    const attemptsConsumed = delegated.attempts.length;
+    const attemptBudget = delegatedAttemptBudget(delegated);
+    const remainingAttempts = Math.max(0, attemptBudget - attemptsConsumed);
+    const hasInFlightAttempt = delegated.attempts.some((attempt) => attempt.status === "in_flight");
+    const recoveryGrants = delegatedRecoveryGrantCount(delegated.recoveryHistory);
+    const autonomousGrantConsumed = delegatedAutonomousGrantConsumed(delegated.recoveryHistory);
+    const reportRejectedAttempts = delegated.attempts.filter((attempt) => attempt.status === "report_rejected").length;
+    let nextAction;
+    if (record.state === "closed") {
+        nextAction = "closed";
+    }
+    else if (record.state === "ready_to_close") {
+        nextAction = "close";
+    }
+    else if (record.state === "awaiting_acceptance") {
+        nextAction = "decide";
+    }
+    else if (record.state === "blocked" || record.state === "needs_context") {
+        nextAction =
+            remainingAttempts > 0 || !autonomousGrantConsumed
+                ? "recover"
+                : "recover_with_user_authorization";
+    }
+    else if (hasInFlightAttempt) {
+        // A live attempt rejects an ordinary launch with ATTEMPT_IN_FLIGHT; the
+        // supported action is collecting its result, not launching again.
+        nextAction = "await_result";
+    }
+    else if (remainingAttempts > 0) {
+        nextAction = "launch_implementer";
+    }
+    else {
+        nextAction = autonomousGrantConsumed ? "recover_with_user_authorization" : "recover";
+    }
+    return {
+        attemptsConsumed,
+        attemptBudget,
+        remainingAttempts,
+        hasInFlightAttempt,
+        recoveryGrants,
+        autonomousGrantConsumed,
+        reportRejectedAttempts,
+        nextAction,
+    };
+}
 function findRecord(store, sessionId, workItemId) {
     return store.records.get(createRecordLookupKey(sessionId, workItemId));
 }
@@ -447,6 +661,106 @@ export function applyDelegatedLaunchFailureInStore(store, input) {
         retryAllowed: (updated.delegated?.attempts.length ?? 0) < attemptBudget,
     };
 }
+// START_CONTRACT: applyDelegatedReportRejection
+//   PURPOSE: Settle one confirmed terminal protocol-invalid report on its exact call-bound attempt as a completed execution with a rejected report.
+//   INPUTS: { store: WorkItemStore - backing store, input: ApplyDelegatedReportRejectionInput - call-bound report rejection with bounded diagnostics }
+//   OUTPUTS: { ApplyDelegatedReportRejectionResult - settled attempt and preserved hard-stop state, or a coded rejection without mutation }
+//   SIDE_EFFECTS: [Marks the matching in-flight attempt report_rejected and consumes one attempt without fabricating DONE]
+//   LINKS: [M-WORKFLOW-DELEGATED, M-WORKFLOW-STATE, M-WORKFLOW-REPAIR]
+// END_CONTRACT: applyDelegatedReportRejection
+export function applyDelegatedReportRejection(store, input) {
+    return applyDelegatedReportRejectionInStore(store.getStoreData(), input);
+}
+export function applyDelegatedReportRejectionInStore(store, input) {
+    const protocolErrorCode = typeof input.protocolErrorCode === "string" ? input.protocolErrorCode.trim() : "";
+    if (!protocolErrorCode || protocolErrorCode.length > DELEGATED_RECOVERY_CODE_MAX_CHARS) {
+        return {
+            ok: false,
+            errorCode: "INVALID_INPUT",
+            message: `INVALID_INPUT: protocolErrorCode must be 1 to ${DELEGATED_RECOVERY_CODE_MAX_CHARS} characters`,
+        };
+    }
+    if (input.explicitHardStop !== undefined &&
+        input.explicitHardStop !== "BLOCKED" &&
+        input.explicitHardStop !== "NEEDS_CONTEXT") {
+        return {
+            ok: false,
+            errorCode: "INVALID_INPUT",
+            message: "INVALID_INPUT: explicitHardStop must be BLOCKED, NEEDS_CONTEXT, or omitted",
+        };
+    }
+    const existing = findRecord(store, input.sessionId, input.workItemId);
+    if (!existing) {
+        return {
+            ok: false,
+            errorCode: "WORK_ITEM_NOT_FOUND",
+            message: `WORK_ITEM_NOT_FOUND: no work item ${input.workItemId} for session ${input.sessionId}`,
+        };
+    }
+    if (existing.state === "closed") {
+        return {
+            ok: false,
+            errorCode: "WORK_ITEM_ALREADY_CLOSED",
+            message: `WORK_ITEM_ALREADY_CLOSED: ${input.workItemId} is already closed`,
+        };
+    }
+    if (existing.mode !== "delegated" || !existing.delegated) {
+        return {
+            ok: false,
+            errorCode: "WRONG_MODE",
+            message: `WRONG_MODE: ${input.workItemId} is ${existing.mode}, not delegated`,
+        };
+    }
+    const inFlight = existing.delegated.attempts.find((attempt) => attempt.status === "in_flight");
+    if (!inFlight || inFlight.callId !== input.callId) {
+        return {
+            ok: false,
+            errorCode: "STALE_CALLBACK",
+            message: `STALE_CALLBACK: ${input.callId} does not match the in-flight attempt ${inFlight ? inFlight.callId : "(none)"} for ${input.workItemId}`,
+        };
+    }
+    const now = toIsoNow();
+    const nextState = input.explicitHardStop === "BLOCKED"
+        ? "blocked"
+        : input.explicitHardStop === "NEEDS_CONTEXT"
+            ? "needs_context"
+            : "awaiting_implementer";
+    const updated = {
+        ...existing,
+        // A confirmed terminal execution settles its attempt; a rejected report
+        // never synthesizes DONE, so the item returns to the launch gate (or the
+        // observed substantive hard-stop state) with the attempt consumed.
+        state: nextState,
+        ...(input.explicitHardStop ? { resultExcerpt: input.excerpt } : {}),
+        delegated: {
+            ...existing.delegated,
+            attempts: existing.delegated.attempts.map((attempt) => attempt.attempt === inFlight.attempt
+                ? {
+                    ...attempt,
+                    status: "report_rejected",
+                    reportRejection: {
+                        protocolErrorCode,
+                        excerpt: input.excerpt,
+                        rejectedAt: now,
+                    },
+                    completedAt: now,
+                }
+                : attempt),
+        },
+        updatedAt: now,
+    };
+    store.records.set(createRecordLookupKey(input.sessionId, input.workItemId), updated);
+    const delegated = updated.delegated;
+    const attemptBudget = delegatedAttemptBudget(delegated);
+    return {
+        ok: true,
+        record: cloneRecord(updated),
+        attempt: inFlight.attempt,
+        ...(input.explicitHardStop ? { observedHardStop: input.explicitHardStop } : {}),
+        consumedAttempts: delegated.attempts.length,
+        attemptBudget,
+    };
+}
 // START_CONTRACT: decideDelegatedWorkItem
 //   PURPOSE: Record an explicit controller accept or request_changes decision bound to the current completed attempt.
 //   INPUTS: { store: WorkItemStore - backing store, input: DecideDelegatedWorkItemInput - decision payload with attempt identity and bounded text }
@@ -707,6 +1021,228 @@ export function reworkDelegatedWorkItemInStore(store, input) {
         grantedAttempts: delegatedAttemptBudget(updated.delegated),
     };
 }
+/**
+ * Synchronous eligibility check for delegated recovery. Re-run after any
+ * asynchronous authorization validation so a changed target state can never
+ * be committed on stale evidence.
+ */
+function precheckDelegatedRecovery(store, input) {
+    const existing = findRecord(store, input.sessionId, input.workItemId);
+    if (!existing) {
+        return {
+            ok: false,
+            errorCode: "WORK_ITEM_NOT_FOUND",
+            message: `WORK_ITEM_NOT_FOUND: no work item ${input.workItemId} for session ${input.sessionId}`,
+        };
+    }
+    if (existing.state === "closed") {
+        return {
+            ok: false,
+            errorCode: "WORK_ITEM_ALREADY_CLOSED",
+            message: `WORK_ITEM_ALREADY_CLOSED: ${input.workItemId} is already closed`,
+        };
+    }
+    if (existing.mode !== "delegated" || !existing.delegated) {
+        return {
+            ok: false,
+            errorCode: "WRONG_MODE",
+            message: `WRONG_MODE: ${input.workItemId} is ${existing.mode}, not delegated`,
+        };
+    }
+    if (currentDelegatedAcceptance(existing)) {
+        return {
+            ok: false,
+            errorCode: "INVALID_TARGET_STATE",
+            message: `INVALID_TARGET_STATE: ${input.workItemId} is currently accepted; checkpoint-authorized rework is the path for accepted items, not recovery`,
+        };
+    }
+    if (existing.delegated.attempts.some((attempt) => attempt.status === "in_flight")) {
+        return {
+            ok: false,
+            errorCode: "INVALID_TARGET_STATE",
+            message: `INVALID_TARGET_STATE: ${input.workItemId} has a live in-flight attempt; recovery never interrupts live work`,
+        };
+    }
+    const isStop = existing.state === "blocked" || existing.state === "needs_context";
+    const isExhausted = existing.state === "awaiting_implementer" &&
+        existing.delegated.attempts.length >= delegatedAttemptBudget(existing.delegated);
+    if (!isStop && !isExhausted) {
+        return {
+            ok: false,
+            errorCode: "INVALID_TARGET_STATE",
+            message: `INVALID_TARGET_STATE: ${input.workItemId} is ${existing.state} and is neither stopped nor out of implementation budget`,
+        };
+    }
+    const target = existing.delegated.attempts[existing.delegated.attempts.length - 1];
+    if (!target) {
+        return {
+            ok: false,
+            errorCode: "INVALID_TARGET_STATE",
+            message: `INVALID_TARGET_STATE: ${input.workItemId} has no terminal attempt to recover`,
+        };
+    }
+    if (target.status === "in_flight") {
+        return {
+            ok: false,
+            errorCode: "ATTEMPT_NOT_TERMINAL",
+            message: `ATTEMPT_NOT_TERMINAL: attempt ${target.attempt} of ${input.workItemId} is still in flight`,
+        };
+    }
+    if (target.attempt !== input.attempt) {
+        return {
+            ok: false,
+            errorCode: "ATTEMPT_MISMATCH",
+            message: `ATTEMPT_MISMATCH: recovery targets attempt ${input.attempt} but the latest terminal attempt is ${target.attempt}`,
+        };
+    }
+    if (existing.delegated.recoveryHistory.some((entry) => entry.recoveryId === input.recoveryId)) {
+        return {
+            ok: false,
+            errorCode: "DUPLICATE_RECOVERY_ID",
+            message: `DUPLICATE_RECOVERY_ID: recoveryId ${input.recoveryId} is already recorded for ${input.workItemId}`,
+        };
+    }
+    const remaining = delegatedAttemptBudget(existing.delegated) - existing.delegated.attempts.length;
+    return {
+        ok: true,
+        record: existing,
+        target,
+        needsGrant: remaining <= 0,
+        autonomousAvailable: !delegatedAutonomousGrantConsumed(existing.delegated.recoveryHistory),
+    };
+}
+// START_CONTRACT: recoverDelegatedWorkItem
+//   PURPOSE: Resume a stopped unaccepted item or grant exactly one additional attempt after exhaustion, preserving every prior outcome and decision.
+//   INPUTS: { store: WorkItemStore - backing store, input: RecoverDelegatedWorkItemInput - bounded recovery payload with optional root-user authorization }
+//   OUTPUTS: { RecoverDelegatedWorkItemResult - recorded recovery with updated budget or a coded rejection without mutation }
+//   SIDE_EFFECTS: [Appends a recovery record, moves a stopped item back to awaiting_implementer, and may extend the attempt budget by exactly one]
+//   LINKS: [M-WORKFLOW-DELEGATED, M-WORKFLOW-CHECKPOINTS, validateRecoveryUserAuthorization]
+// END_CONTRACT: recoverDelegatedWorkItem
+export async function recoverDelegatedWorkItem(store, input) {
+    return recoverDelegatedWorkItemInStore(store.getStoreData(), input);
+}
+export async function recoverDelegatedWorkItemInStore(store, input) {
+    const validation = validateDelegatedRecoveryInput({
+        diagnosis: input.diagnosis,
+        changedCondition: input.changedCondition,
+        verification: input.verification,
+        recoveryId: input.recoveryId,
+    });
+    if (!validation.ok) {
+        return {
+            ok: false,
+            errorCode: "INVALID_INPUT",
+            message: `INVALID_INPUT: ${validation.message}`,
+        };
+    }
+    const precheck = precheckDelegatedRecovery(store, input);
+    if (!precheck.ok) {
+        return { ok: false, errorCode: precheck.errorCode, message: precheck.message };
+    }
+    const commitRecovery = (kind) => {
+        // Re-run the synchronous eligibility check immediately before committing
+        // so an authorization await can never commit against a changed target.
+        const fresh = precheckDelegatedRecovery(store, input);
+        if (!fresh.ok) {
+            return { ok: false, errorCode: fresh.errorCode, message: fresh.message };
+        }
+        const now = toIsoNow();
+        const recovery = {
+            recoveryId: input.recoveryId,
+            targetAttempt: input.attempt,
+            kind,
+            diagnosis: input.diagnosis.trim(),
+            changedCondition: input.changedCondition.trim(),
+            verification: input.verification.map((reference) => reference.trim()),
+            recoveredAt: now,
+            ...(kind === "user_grant" && input.userMessageId
+                ? { userMessageId: input.userMessageId }
+                : {}),
+        };
+        const updated = {
+            ...fresh.record,
+            // Recovery returns a stopped item to the launch gate; an exhausted item
+            // is already there. Either way recovery never accepts or closes work.
+            state: "awaiting_implementer",
+            delegated: {
+                ...fresh.record.delegated,
+                recoveryHistory: [...fresh.record.delegated.recoveryHistory, recovery],
+            },
+            updatedAt: now,
+        };
+        store.records.set(createRecordLookupKey(input.sessionId, input.workItemId), updated);
+        const delegated = updated.delegated;
+        const attemptBudget = delegatedAttemptBudget(delegated);
+        return {
+            ok: true,
+            record: cloneRecord(updated),
+            recoveryId: input.recoveryId,
+            kind,
+            attemptBudget,
+            remainingAttempts: Math.max(0, attemptBudget - delegated.attempts.length),
+        };
+    };
+    if (!precheck.needsGrant) {
+        return commitRecovery("resume");
+    }
+    if (input.userMessageId !== undefined) {
+        const userMessageId = input.userMessageId.trim();
+        if (!userMessageId) {
+            return {
+                ok: false,
+                errorCode: "INVALID_INPUT",
+                message: "INVALID_INPUT: userMessageId must be a non-empty string when provided",
+            };
+        }
+        if (precheck.record.delegated?.recoveryHistory.some((entry) => entry.userMessageId === userMessageId)) {
+            return {
+                ok: false,
+                errorCode: "AUTHORIZATION_REUSED",
+                message: `AUTHORIZATION_REUSED: message ${userMessageId} already authorized recovery of ${input.workItemId}; each message grants at most one unit per target`,
+            };
+        }
+        if (typeof input.lookupUserMessage !== "function") {
+            return {
+                ok: false,
+                errorCode: "AUTHORIZATION_LOOKUP_FAILED",
+                message: "AUTHORIZATION_LOOKUP_FAILED: user-authorized recovery requires a read-only message lookup bound to the plugin context",
+            };
+        }
+        const authorization = await validateRecoveryUserAuthorization({
+            owningSessionId: input.sessionId,
+            userMessageId,
+            requireAfterMs: terminalAttemptTimeMs(precheck.target),
+            lookup: input.lookupUserMessage,
+        });
+        if (!authorization.ok) {
+            return { ok: false, errorCode: authorization.errorCode, message: authorization.message };
+        }
+        // The await above is an async boundary: re-verify non-reuse before commit
+        // (the precheck inside commitRecovery covers the rest of the state).
+        const fresh = findRecord(store, input.sessionId, input.workItemId);
+        if (fresh?.delegated?.recoveryHistory.some((entry) => entry.userMessageId === userMessageId)) {
+            return {
+                ok: false,
+                errorCode: "AUTHORIZATION_REUSED",
+                message: `AUTHORIZATION_REUSED: message ${userMessageId} already authorized recovery of ${input.workItemId}`,
+            };
+        }
+        return commitRecovery("user_grant");
+    }
+    if (precheck.autonomousAvailable) {
+        return commitRecovery("autonomous_grant");
+    }
+    if (input.advanceGrantApproved === true) {
+        // The transaction layer already validated the execution authority and
+        // reserved exactly one unit for this recoveryId; record the grant kind.
+        return commitRecovery("advance_grant");
+    }
+    return {
+        ok: false,
+        errorCode: "AUTONOMOUS_GRANT_EXHAUSTED",
+        message: `AUTONOMOUS_GRANT_EXHAUSTED: the single autonomous recovery grant for ${input.workItemId} is consumed; one further unit requires a recorded advance authority or a fresh root-user message referenced by userMessageId`,
+    };
+}
 // START_CONTRACT: revertInFlightDelegatedLaunches
 //   PURPOSE: Reclaim delegated attempts that a process-restart boundary orphaned, restoring their items to a launchable state without consuming budget.
 //   INPUTS: { store: WorkItemStoreData - hydrated store data, sessionId: string - owning session }