@osovv/vv-opencode 1.3.8 → 1.4.1

package/dist/plugins/workflow/delegated.js

@@ -0,0 +1,751 @@
+// FILE: src/plugins/workflow/delegated.ts
+// VERSION: 1.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]
+//   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.
+//   DelegatedImplementerStatus - Implementer result statuses recordable on an attempt.
+//   DelegatedAttempt - One host-callID-bound implementation attempt.
+//   DelegatedAttemptStatus - Attempt lifecycle statuses (in_flight, completed, failed).
+//   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.
+//   DelegatedWriteScopeValidation - Result of validating declared write-scope text inputs.
+//   BeginDelegatedLaunchInput - Delegated launch input with session, item, and host callID.
+//   BeginDelegatedLaunchResult - Launch allocation outcome.
+//   ApplyDelegatedResultInput - Call-bound delegated result payload.
+//   ApplyDelegatedResultResult - Result application outcome.
+//   DecideDelegatedWorkItemInput - Controller decision payload with attempt identity and bounded text.
+//   DecideDelegatedWorkItemResult - Controller decision outcome.
+//   ReworkDelegatedWorkItemInput - Checkpoint-authorized rework request.
+//   ReworkDelegatedWorkItemResult - Authorized rework outcome.
+//   delegatedAttemptBudget - Allowed attempt count given consumed attempts and rework history.
+//   currentDelegatedAcceptance - Currently applicable acceptance for a record.
+//   DelegatedDecisionInputValidation - Shape accepted by validateDelegatedDecisionInput.
+//   validateDelegatedWriteScope - Validates declared write-scope text into canonical normalized paths.
+//   validateDelegatedDecisionInput - Pure validation of decision text bounds.
+//   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.
+//   applyDelegatedResult - Apply one implementer result to its matching in-flight attempt.
+//   applyDelegatedResultInStore - Store-level delegated result application.
+//   ApplyDelegatedLaunchFailureInput - Call-bound host-terminal launch-failure payload.
+//   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.
+//   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.
+// 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.]
+// END_CHANGE_SUMMARY
+import { cloneRecord, createRecordLookupKey } from "./state.js";
+import { getAllowedNextAgents } from "./transitions.js";
+import { normalizeDeclaredScopePath } from "../../lib/spec-lint.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;
+// 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. */
+export function delegatedAttemptBudget(state) {
+    return DELEGATED_BASE_ATTEMPTS + state.reworkHistory.length;
+}
+/** Currently applicable acceptance for a record: the latest unrevoked acceptance. */
+export function currentDelegatedAcceptance(record) {
+    if (!record.delegated)
+        return undefined;
+    return [...record.delegated.acceptances].reverse().find((acceptance) => !acceptance.revokedAt);
+}
+/** Validate declared write-scope text inputs into canonical normalized paths. */
+export function validateDelegatedWriteScope(paths) {
+    if (!Array.isArray(paths) || paths.length === 0) {
+        return {
+            ok: false,
+            message: "writeScope must be a non-empty array of workspace-relative files",
+        };
+    }
+    const normalized = [];
+    const seen = new Set();
+    for (const declared of paths) {
+        const result = normalizeDeclaredScopePath(String(declared));
+        if (!result.ok) {
+            return {
+                ok: false,
+                message: `writeScope path ${JSON.stringify(String(declared))} is malformed (${result.reason})`,
+            };
+        }
+        if (seen.has(result.path)) {
+            return {
+                ok: false,
+                message: `writeScope path ${JSON.stringify(result.path)} is declared more than once`,
+            };
+        }
+        seen.add(result.path);
+        normalized.push(result.path);
+    }
+    return { ok: true, paths: normalized };
+}
+/** Pure validation of decision text bounds shared by the tool layer and domain layer. */
+export function validateDelegatedDecisionInput(input) {
+    const rationale = typeof input.rationale === "string" ? input.rationale.trim() : "";
+    if (rationale === "") {
+        return { ok: false, message: "rationale must be a non-empty string" };
+    }
+    if (rationale.length > DELEGATED_RATIONALE_MAX_CHARS) {
+        return { ok: false, message: `rationale exceeds ${DELEGATED_RATIONALE_MAX_CHARS} characters` };
+    }
+    if (!Array.isArray(input.evidence) || input.evidence.length === 0) {
+        return { ok: false, message: "evidence must be a non-empty array of reference strings" };
+    }
+    if (input.evidence.length > DELEGATED_EVIDENCE_MAX_REFS) {
+        return { ok: false, message: `evidence exceeds ${DELEGATED_EVIDENCE_MAX_REFS} references` };
+    }
+    for (const reference of input.evidence) {
+        const normalized = typeof reference === "string" ? reference.trim() : "";
+        if (normalized === "") {
+            return { ok: false, message: "evidence references must be non-empty strings" };
+        }
+        if (normalized.length > DELEGATED_EVIDENCE_MAX_CHARS) {
+            return {
+                ok: false,
+                message: `evidence reference exceeds ${DELEGATED_EVIDENCE_MAX_CHARS} characters`,
+            };
+        }
+    }
+    if (input.concernsDisposition !== undefined) {
+        if (typeof input.concernsDisposition !== "string" || input.concernsDisposition.trim() === "") {
+            return { ok: false, message: "concernsDisposition must be a non-empty string when provided" };
+        }
+        if (input.concernsDisposition.trim().length > DELEGATED_RATIONALE_MAX_CHARS) {
+            return {
+                ok: false,
+                message: `concernsDisposition exceeds ${DELEGATED_RATIONALE_MAX_CHARS} characters`,
+            };
+        }
+    }
+    return { ok: true };
+}
+function findRecord(store, sessionId, workItemId) {
+    return store.records.get(createRecordLookupKey(sessionId, workItemId));
+}
+/**
+ * Resolve the single delegated attempt that owns one host callID within a
+ * parent session. Ambiguous pre-existing histories fail closed instead of
+ * selecting one so an old event can never affect a newer attempt.
+ */
+function findDelegatedCallIdBinding(store, sessionId, callId) {
+    const matches = [];
+    for (const [lookupKey, record] of store.records) {
+        if (record.sessionId !== sessionId || record.mode !== "delegated" || !record.delegated)
+            continue;
+        for (const attempt of record.delegated.attempts) {
+            if (attempt.callId === callId) {
+                matches.push({ record, attempt, lookupKey });
+            }
+        }
+    }
+    if (matches.length === 0)
+        return { kind: "none" };
+    if (matches.length > 1)
+        return { kind: "ambiguous" };
+    return { kind: "unique", ...matches[0] };
+}
+// START_CONTRACT: beginDelegatedLaunch
+//   PURPOSE: Allocate one implementation attempt and bind it to the host tool-call identity.
+//   INPUTS: { store: WorkItemStore - backing store, input: BeginDelegatedLaunchInput - session, item, and host callID }
+//   OUTPUTS: { BeginDelegatedLaunchResult - allocated attempt or a coded rejection }
+//   SIDE_EFFECTS: [Mutates the delegated attempt ledger for valid launches]
+//   LINKS: [M-WORKFLOW-DELEGATED, M-WORKFLOW-STATE]
+// END_CONTRACT: beginDelegatedLaunch
+export function beginDelegatedLaunch(store, input) {
+    return beginDelegatedLaunchInStore(store.getStoreData(), input);
+}
+export function beginDelegatedLaunchInStore(store, input) {
+    const callId = input.callId?.trim() ?? "";
+    if (!callId) {
+        return { ok: false, errorCode: "INVALID_STATE", message: "callId must be a non-empty string" };
+    }
+    const existing = findRecord(store, input.sessionId, input.workItemId);
+    if (!existing) {
+        return {
+            ok: false,
+            errorCode: "WORK_ITEM_NOT_FOUND",
+            message: `WORK_ITEM_NOT_FOUND: ${input.workItemId}`,
+        };
+    }
+    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 (!getAllowedNextAgents(existing).includes("vv-implementer")) {
+        return {
+            ok: false,
+            errorCode: "INVALID_STATE",
+            message: `INVALID_STATE: ${input.workItemId} is ${existing.state} and cannot start an implementation attempt`,
+        };
+    }
+    const delegated = existing.delegated;
+    if (delegated.attempts.some((attempt) => attempt.status === "in_flight")) {
+        return {
+            ok: false,
+            errorCode: "ATTEMPT_IN_FLIGHT",
+            message: `ATTEMPT_IN_FLIGHT: ${input.workItemId} already has an in-flight implementation attempt`,
+        };
+    }
+    if (delegated.attempts.length >= delegatedAttemptBudget(delegated)) {
+        return {
+            ok: false,
+            errorCode: "ATTEMPTS_EXHAUSTED",
+            message: `ATTEMPTS_EXHAUSTED: ${input.workItemId} consumed ${delegated.attempts.length} of ${delegatedAttemptBudget(delegated)} allowed attempts; explicit recovery or checkpoint-authorized rework is required`,
+        };
+    }
+    // A host callID is a single-shot identity within a parent session. Reusing it
+    // for a new attempt — in this item or any other — would let a delayed event
+    // from the old call affect the new attempt, so fail closed instead.
+    const callIdBinding = findDelegatedCallIdBinding(store, input.sessionId, callId);
+    if (callIdBinding.kind !== "none") {
+        return {
+            ok: false,
+            errorCode: "CALL_ID_REUSED",
+            message: `CALL_ID_REUSED: callID ${callId} is already bound to a delegated attempt in session ${input.sessionId}`,
+        };
+    }
+    const attemptNumber = delegated.attempts.length + 1;
+    const now = toIsoNow();
+    const updated = {
+        ...existing,
+        state: "awaiting_implementer",
+        delegated: {
+            ...delegated,
+            attempts: [
+                ...delegated.attempts,
+                { attempt: attemptNumber, callId, launchedAt: now, status: "in_flight" },
+            ],
+        },
+        updatedAt: now,
+    };
+    store.records.set(createRecordLookupKey(input.sessionId, input.workItemId), updated);
+    return { ok: true, record: cloneRecord(updated), attempt: attemptNumber, callId };
+}
+const DELEGATED_RESULT_STATUSES = new Set([
+    "DONE",
+    "DONE_WITH_CONCERNS",
+    "NEEDS_CONTEXT",
+    "BLOCKED",
+]);
+// START_CONTRACT: applyDelegatedResult
+//   PURPOSE: Apply one implementer result to its matching in-flight attempt and move DONE or DONE_WITH_CONCERNS to awaiting_acceptance.
+//   INPUTS: { store: WorkItemStore - backing store, input: ApplyDelegatedResultInput - call-bound result payload }
+//   OUTPUTS: { ApplyDelegatedResultResult - applied transition or a coded rejection including stale callbacks }
+//   SIDE_EFFECTS: [Mutates the matching delegated attempt and the work-item state]
+//   LINKS: [M-WORKFLOW-DELEGATED, M-WORKFLOW-STATE]
+// END_CONTRACT: applyDelegatedResult
+export function applyDelegatedResult(store, input) {
+    return applyDelegatedResultInStore(store.getStoreData(), input);
+}
+export function applyDelegatedResultInStore(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 (!DELEGATED_RESULT_STATUSES.has(input.resultStatus)) {
+        return {
+            ok: false,
+            errorCode: "INVALID_RESULT_STATUS",
+            message: `INVALID_RESULT_STATUS: ${String(input.resultStatus)} is not a delegated implementer status`,
+        };
+    }
+    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 fromState = existing.state;
+    const nextState = input.resultStatus === "DONE" || input.resultStatus === "DONE_WITH_CONCERNS"
+        ? "awaiting_acceptance"
+        : input.resultStatus === "NEEDS_CONTEXT"
+            ? "needs_context"
+            : "blocked";
+    const updated = {
+        ...existing,
+        state: nextState,
+        ...(input.resultExcerpt ? { resultExcerpt: input.resultExcerpt } : {}),
+        delegated: {
+            ...existing.delegated,
+            attempts: existing.delegated.attempts.map((attempt) => attempt.attempt === inFlight.attempt
+                ? {
+                    ...attempt,
+                    status: "completed",
+                    resultStatus: input.resultStatus,
+                    completedAt: now,
+                    ...(input.resultExcerpt ? { resultExcerpt: input.resultExcerpt } : {}),
+                }
+                : attempt),
+        },
+        updatedAt: now,
+    };
+    store.records.set(createRecordLookupKey(input.sessionId, input.workItemId), updated);
+    return {
+        ok: true,
+        record: cloneRecord(updated),
+        fromState,
+        toState: nextState,
+        attempt: inFlight.attempt,
+        resultStatus: input.resultStatus,
+    };
+}
+// START_CONTRACT: applyDelegatedLaunchFailure
+//   PURPOSE: Record a confirmed host-terminal launch failure on its matching in-flight attempt without advancing the item lifecycle.
+//   INPUTS: { store: WorkItemStore - backing store, input: ApplyDelegatedLaunchFailureInput - call-bound host wrapper error evidence }
+//   OUTPUTS: { ApplyDelegatedLaunchFailureResult - failed attempt with remaining budget or a coded rejection }
+//   SIDE_EFFECTS: [Marks the matching in-flight attempt failed and consumes one attempt from the existing budget]
+//   LINKS: [M-WORKFLOW-DELEGATED, M-WORKFLOW-STATE]
+// END_CONTRACT: applyDelegatedLaunchFailure
+export function applyDelegatedLaunchFailure(store, input) {
+    return applyDelegatedLaunchFailureInStore(store.getStoreData(), input);
+}
+export function applyDelegatedLaunchFailureInStore(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`,
+        };
+    }
+    // A host-terminal launch failure is only meaningful while the item is still
+    // waiting for its implementer. Any other lifecycle state means a different
+    // transition got there first, so fail closed.
+    if (existing.state !== "awaiting_implementer") {
+        return {
+            ok: false,
+            errorCode: "INVALID_STATE",
+            message: `INVALID_STATE: ${input.workItemId} is ${existing.state}, not awaiting_implementer`,
+        };
+    }
+    const callIdBinding = findDelegatedCallIdBinding(store, input.sessionId, input.callId);
+    if (callIdBinding.kind === "ambiguous") {
+        return {
+            ok: false,
+            errorCode: "AMBIGUOUS_CALL_ID",
+            message: `AMBIGUOUS_CALL_ID: callID ${input.callId} is bound to more than one delegated attempt in session ${input.sessionId}`,
+        };
+    }
+    if (callIdBinding.kind === "unique" &&
+        (callIdBinding.record.workItemId !== input.workItemId ||
+            callIdBinding.record.sessionId !== input.sessionId)) {
+        return {
+            ok: false,
+            errorCode: "STALE_CALLBACK",
+            message: `STALE_CALLBACK: ${input.callId} is bound to ${callIdBinding.record.workItemId}, not ${input.workItemId}`,
+        };
+    }
+    const inFlight = existing.delegated.attempts.find((attempt) => attempt.status === "in_flight" && attempt.callId === input.callId);
+    if (!inFlight) {
+        return {
+            ok: false,
+            errorCode: "STALE_CALLBACK",
+            message: `STALE_CALLBACK: ${input.callId} does not match an in-flight attempt for ${input.workItemId}`,
+        };
+    }
+    const now = toIsoNow();
+    const updated = {
+        ...existing,
+        // Failed attempts never advance the lifecycle: the item stays waiting at
+        // the launch gate so an explicit controller retry can consume the
+        // remaining budget, and two failures naturally exhaust it.
+        state: "awaiting_implementer",
+        delegated: {
+            ...existing.delegated,
+            attempts: existing.delegated.attempts.map((attempt) => attempt.attempt === inFlight.attempt
+                ? {
+                    ...attempt,
+                    status: "failed",
+                    failureExcerpt: input.failureExcerpt,
+                    completedAt: now,
+                }
+                : attempt),
+        },
+        updatedAt: now,
+    };
+    store.records.set(createRecordLookupKey(input.sessionId, input.workItemId), updated);
+    const attemptBudget = delegatedAttemptBudget(updated.delegated);
+    return {
+        ok: true,
+        record: cloneRecord(updated),
+        fromState: existing.state,
+        toState: "awaiting_implementer",
+        attempt: inFlight.attempt,
+        consumedAttempts: updated.delegated?.attempts.length ?? 0,
+        attemptBudget,
+        retryAllowed: (updated.delegated?.attempts.length ?? 0) < 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 }
+//   OUTPUTS: { DecideDelegatedWorkItemResult - applied decision or a coded rejection without mutation }
+//   SIDE_EFFECTS: [Mutates decision history, acceptance state, and the work-item lifecycle state]
+//   LINKS: [M-WORKFLOW-DELEGATED, M-WORKFLOW-STATE]
+// END_CONTRACT: decideDelegatedWorkItem
+export function decideDelegatedWorkItem(store, input) {
+    return decideDelegatedWorkItemInStore(store.getStoreData(), input);
+}
+export function decideDelegatedWorkItemInStore(store, input) {
+    if (input.decision !== "accept" && input.decision !== "request_changes") {
+        return {
+            ok: false,
+            errorCode: "INVALID_INPUT",
+            message: "INVALID_INPUT: decision must be accept or request_changes",
+        };
+    }
+    const validation = validateDelegatedDecisionInput({
+        decision: input.decision,
+        rationale: input.rationale,
+        evidence: input.evidence,
+        concernsDisposition: input.concernsDisposition,
+    });
+    if (!validation.ok) {
+        return {
+            ok: false,
+            errorCode: "INVALID_INPUT",
+            message: `INVALID_INPUT: ${validation.message}`,
+        };
+    }
+    if (!Number.isInteger(input.attempt) || input.attempt < 1) {
+        return {
+            ok: false,
+            errorCode: "INVALID_INPUT",
+            message: "INVALID_INPUT: attempt must be a positive integer",
+        };
+    }
+    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}; only delegated items receive controller decisions`,
+        };
+    }
+    if (existing.state !== "awaiting_acceptance") {
+        return {
+            ok: false,
+            errorCode: "INVALID_STATE",
+            message: `INVALID_STATE: ${input.workItemId} is ${existing.state}, not awaiting_acceptance`,
+        };
+    }
+    const completed = [...existing.delegated.attempts]
+        .filter((attempt) => attempt.status === "completed")
+        .sort((left, right) => right.attempt - left.attempt)[0];
+    if (!completed) {
+        return {
+            ok: false,
+            errorCode: "INVALID_STATE",
+            message: `INVALID_STATE: ${input.workItemId} has no completed attempt to decide`,
+        };
+    }
+    if (completed.attempt !== input.attempt) {
+        return {
+            ok: false,
+            errorCode: "INVALID_ATTEMPT",
+            message: `INVALID_ATTEMPT: decision targets attempt ${input.attempt} but the current completed attempt is ${completed.attempt}`,
+        };
+    }
+    if (existing.delegated.decisions.some((decision) => decision.attempt === input.attempt)) {
+        return {
+            ok: false,
+            errorCode: "DUPLICATE_DECISION",
+            message: `DUPLICATE_DECISION: attempt ${input.attempt} already received a controller decision`,
+        };
+    }
+    const hasConcerns = completed.resultStatus === "DONE_WITH_CONCERNS";
+    if (hasConcerns && input.concernsDisposition === undefined) {
+        return {
+            ok: false,
+            errorCode: "CONCERNS_DISPOSITION_REQUIRED",
+            message: `CONCERNS_DISPOSITION_REQUIRED: attempt ${input.attempt} completed DONE_WITH_CONCERNS and requires an explicit disposition`,
+        };
+    }
+    if (!hasConcerns && input.concernsDisposition !== undefined) {
+        return {
+            ok: false,
+            errorCode: "UNEXPECTED_CONCERNS_DISPOSITION",
+            message: `UNEXPECTED_CONCERNS_DISPOSITION: attempt ${input.attempt} completed ${completed.resultStatus}, not DONE_WITH_CONCERNS`,
+        };
+    }
+    const now = toIsoNow();
+    const decisionId = `dec-${existing.workItemId}-a${input.attempt}`;
+    const decision = {
+        decisionId,
+        attempt: input.attempt,
+        decision: input.decision,
+        decidedAt: now,
+        rationale: input.rationale.trim(),
+        evidence: input.evidence.map((reference) => reference.trim()),
+        ...(input.concernsDisposition !== undefined
+            ? { concernsDisposition: input.concernsDisposition.trim() }
+            : {}),
+    };
+    const nextState = input.decision === "accept" ? "ready_to_close" : "awaiting_implementer";
+    const updated = {
+        ...existing,
+        state: nextState,
+        delegated: {
+            ...existing.delegated,
+            decisions: [...existing.delegated.decisions, decision],
+            ...(input.decision === "accept"
+                ? {
+                    acceptances: [
+                        ...existing.delegated.acceptances,
+                        {
+                            attempt: input.attempt,
+                            decisionId,
+                            acceptedAt: now,
+                            rationale: input.rationale.trim(),
+                            evidence: input.evidence.map((reference) => reference.trim()),
+                            ...(input.concernsDisposition !== undefined
+                                ? { concernsDisposition: input.concernsDisposition.trim() }
+                                : {}),
+                        },
+                    ],
+                }
+                : {}),
+        },
+        updatedAt: now,
+    };
+    store.records.set(createRecordLookupKey(input.sessionId, input.workItemId), updated);
+    return { ok: true, record: cloneRecord(updated), decision: input.decision, decisionId };
+}
+// START_CONTRACT: reworkDelegatedWorkItem
+//   PURPOSE: Reopen an accepted delegated item under validated checkpoint-failure authorization without resetting attempt history.
+//   INPUTS: { store: WorkItemStore - backing store, input: ReworkDelegatedWorkItemInput - checkpoint authorization payload }
+//   OUTPUTS: { ReworkDelegatedWorkItemResult - reopened record with one extra granted attempt or a coded rejection }
+//   SIDE_EFFECTS: [Revokes the current acceptance's applicability, records the rework event, and returns the item to awaiting_implementer]
+//   LINKS: [M-WORKFLOW-DELEGATED, M-WORKFLOW-CHECKPOINTS]
+// END_CONTRACT: reworkDelegatedWorkItem
+export function reworkDelegatedWorkItem(store, input) {
+    return reworkDelegatedWorkItemInStore(store.getStoreData(), input);
+}
+export function reworkDelegatedWorkItemInStore(store, input) {
+    const reason = typeof input.reason === "string" ? input.reason.trim() : "";
+    const planRunId = typeof input.planRunId === "string" ? input.planRunId.trim() : "";
+    const failedCheckpointId = typeof input.failedCheckpointId === "string" ? input.failedCheckpointId.trim() : "";
+    if (!reason || reason.length > DELEGATED_RATIONALE_MAX_CHARS) {
+        return {
+            ok: false,
+            errorCode: "INVALID_INPUT",
+            message: `INVALID_INPUT: reason must be non-empty and at most ${DELEGATED_RATIONALE_MAX_CHARS} characters`,
+        };
+    }
+    if (!planRunId || !failedCheckpointId) {
+        return {
+            ok: false,
+            errorCode: "INVALID_INPUT",
+            message: "INVALID_INPUT: planRunId and failedCheckpointId must be non-empty",
+        };
+    }
+    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.mode !== "delegated" || !existing.delegated) {
+        return {
+            ok: false,
+            errorCode: "WRONG_MODE",
+            message: `WRONG_MODE: ${input.workItemId} is ${existing.mode}, not delegated`,
+        };
+    }
+    if (existing.state === "needs_context" || existing.state === "blocked") {
+        return {
+            ok: false,
+            errorCode: "HARD_STOP_STATE",
+            message: `HARD_STOP_STATE: ${input.workItemId} is ${existing.state} and cannot be reopened by rework`,
+        };
+    }
+    if (existing.state !== "ready_to_close" && existing.state !== "closed") {
+        return {
+            ok: false,
+            errorCode: "INVALID_STATE",
+            message: `INVALID_STATE: ${input.workItemId} is ${existing.state}; rework targets accepted items`,
+        };
+    }
+    const delegated = existing.delegated;
+    const current = currentDelegatedAcceptance(existing);
+    if (!current || current.revokedAt) {
+        return {
+            ok: false,
+            errorCode: "NOT_ACCEPTED",
+            message: `NOT_ACCEPTED: ${input.workItemId} has no currently applicable acceptance to revoke`,
+        };
+    }
+    if (delegated.reworkHistory.some((rework) => rework.authorizedByCheckpoint === failedCheckpointId)) {
+        return {
+            ok: false,
+            errorCode: "ALREADY_REWORKED",
+            message: `ALREADY_REWORKED: checkpoint ${failedCheckpointId} already authorized one rework of ${input.workItemId}`,
+        };
+    }
+    if (delegated.planRunId && delegated.planRunId !== planRunId) {
+        return {
+            ok: false,
+            errorCode: "INVALID_INPUT",
+            message: `INVALID_INPUT: ${input.workItemId} belongs to plan run ${delegated.planRunId}, not ${planRunId}`,
+        };
+    }
+    const now = toIsoNow();
+    const reworkId = `rw-${existing.workItemId}-${failedCheckpointId}`;
+    const rework = {
+        reworkId,
+        planRunId,
+        authorizedByCheckpoint: failedCheckpointId,
+        reason,
+        reworkedAt: now,
+        revokedAcceptanceAttempt: current.attempt,
+    };
+    const updated = {
+        ...existing,
+        state: "awaiting_implementer",
+        closedAt: undefined,
+        delegated: {
+            ...delegated,
+            reworkHistory: [...delegated.reworkHistory, rework],
+            acceptances: delegated.acceptances.map((acceptance) => acceptance === current
+                ? { ...acceptance, revokedAt: now, revokedByReworkId: reworkId }
+                : acceptance),
+        },
+        updatedAt: now,
+    };
+    store.records.set(createRecordLookupKey(input.sessionId, input.workItemId), updated);
+    return {
+        ok: true,
+        record: cloneRecord(updated),
+        reworkId,
+        grantedAttempts: delegatedAttemptBudget(updated.delegated),
+    };
+}
+// 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 }
+//   OUTPUTS: { { reverted: number; workItemIds: string[] } - reclaimed attempts and affected items }
+//   SIDE_EFFECTS: [Removes never-completed in-flight attempts from the ledger and returns items to awaiting_implementer]
+//   LINKS: [M-WORKFLOW-DELEGATED, M-WORKFLOW-PERSISTENCE, M-PLUGIN-WORKFLOW]
+// END_CONTRACT: revertInFlightDelegatedLaunches
+export function revertInFlightDelegatedLaunches(store, sessionId) {
+    const reverted = [];
+    for (const [lookupKey, record] of store.records) {
+        if (record.sessionId !== sessionId || record.mode !== "delegated" || !record.delegated)
+            continue;
+        const inFlight = record.delegated.attempts.filter((attempt) => attempt.status === "in_flight");
+        if (inFlight.length === 0)
+            continue;
+        // Only the plugin's first store creation for a freshly hydrated session
+        // calls this reclamation. A persisted in-flight attempt can never receive
+        // its host callback after a restart, so reverting it (without consuming
+        // budget — it never completed) is the only non-dead-end recovery. Items
+        // stay hard-stopped when they are already blocked or needs_context.
+        if (record.state === "needs_context" ||
+            record.state === "blocked" ||
+            record.state === "closed") {
+            continue;
+        }
+        const attempts = record.delegated.attempts.filter((attempt) => attempt.status !== "in_flight");
+        store.records.set(lookupKey, {
+            ...record,
+            state: attempts.length > 0 || record.delegated.decisions.length > 0
+                ? "awaiting_implementer"
+                : "open",
+            delegated: {
+                ...record.delegated,
+                attempts,
+            },
+            updatedAt: toIsoNow(),
+        });
+        reverted.push(record.workItemId);
+    }
+    return { reverted: reverted.length, workItemIds: reverted };
+}
+//# sourceMappingURL=delegated.js.map