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

package/dist/plugins/workflow/index.js

@@ -1,8 +1,8 @@
 // FILE: src/plugins/workflow/index.ts
-// VERSION: 0.6.0
+// VERSION: 0.7.0
 // START_MODULE_CONTRACT
-//   PURPOSE: Register workflow tools and enforcement while injecting only startup-profile-compatible vv-controller guidance, including delegated control tools, host-call-bound attempts, and checkpoint reviewer linkage.
-//   SCOPE: work_item_open/list/close registration, delegated-only work_item_decide and work_checkpoint registration with root-session authorization, tracked launch validation with delegated barriers and overlapping-write gates, live host-call bindings that convert supported foreground vv-implementer task launches into failed delegated attempts on confirmed host-terminal errors, result normalization and bounded same-session continuation with explicit hard-stop suppression, callID-bound delegated attempt results and checkpoint reviewer bookkeeping, round aggregation with bounded excerpts, implementation round limits, checked persistence, and profile-selected chat.message guidance.
+//   PURPOSE: Register workflow tools and enforcement while injecting only startup-profile-compatible vv-controller guidance, including delegated control tools with bounded recovery, host-call-bound attempts, terminal report-rejection settlement, and checkpoint reviewer linkage.
+//   SCOPE: work_item_open/list/close registration, delegated-only work_item_decide and work_checkpoint registration with root-session authorization and an SDK-backed read-only authorization-message lookup for user-authorized recovery, tracked launch validation with delegated barriers and overlapping-write gates, live host-call bindings that convert supported foreground vv-implementer task launches into failed delegated attempts on confirmed host-terminal errors, result normalization and bounded same-session continuation with explicit hard-stop suppression, callID-bound delegated attempt results, terminal settlement of protocol-invalid reports as report_rejected attempts through staged persistence, checkpoint reviewer bookkeeping, round aggregation with bounded excerpts, implementation round limits, durably committed recovery with synchronous persist and rollback so launch permissions appear only after a durable write, checked persistence, and profile-selected chat.message guidance.
 //   DEPENDS: [@opencode-ai/plugin, src/lib/config-layers.ts, src/lib/orchestration.ts, src/lib/plugin-toggle-config.ts, src/plugins/workflow/checkpoint-io.ts, src/plugins/workflow/checkpoints.ts, src/plugins/workflow/delegated.ts, src/plugins/workflow/persistence.ts, src/plugins/workflow/protocol.ts, src/plugins/workflow/repair.ts, src/plugins/workflow/state.ts, src/plugins/workflow/tooling.ts, src/plugins/workflow/transitions.ts]
 //   LINKS: M-PLUGIN-WORKFLOW, M-ORCHESTRATION-PROFILES, M-WORKFLOW-PROTOCOL, M-WORKFLOW-REPAIR, M-WORKFLOW-STATE, M-WORKFLOW-TRANSITIONS, M-WORKFLOW-TOOLING, M-WORKFLOW-PERSISTENCE, M-WORKFLOW-DELEGATED, M-WORKFLOW-CHECKPOINTS, V-M-PLUGIN-WORKFLOW
 //   ROLE: RUNTIME
@@ -10,17 +10,17 @@
 // END_MODULE_CONTRACT
 //
 // START_MODULE_MAP
-//   WorkflowPlugin - Registers workflow work-item tools, delegated control tools under the delegated profile, tracked task protocol enforcement with callID-bound delegated attempts, checkpoint linkage, and live host-call failure bindings, and primary-session workflow guidance injection.
+//   WorkflowPlugin - Registers workflow work-item tools, delegated control tools under the delegated profile, tracked task protocol enforcement with callID-bound delegated attempts, bounded recovery with durable persist-and-rollback commits, terminal report-rejection settlement, checkpoint linkage, live host-call failure bindings, and primary-session workflow guidance injection.
 // END_MODULE_MAP
 //
 // START_CHANGE_SUMMARY
-//   LAST_CHANGE: [direct fix bounded result continuation - Replaced format-only repair wiring with one bounded same-session continuation that sends no prompt `tools` override, preserves persistent session permissions, and suppresses continuation for explicit malformed BLOCKED/NEEDS_CONTEXT output while keeping strict reparse and the original protocol-error excerpt path.]
+//   LAST_CHANGE: [C-WORKFLOW-BOUNDED-RECOVERY-R1 - Added decision/checkpoint recover wiring with an SDK-backed authorization lookup and durable persist-then-rollback commits, settled terminal protocol-invalid delegated reports as report_rejected attempts, and calibrated the delegated instruction for bounded recovery and native plan registration.]
 // END_CHANGE_SUMMARY
 import { tool } from "@opencode-ai/plugin";
-import { attemptTrackedResultRepair, hasExplicitHardStopStatus, isTrackedResultRepairEligible, unwrapResumableTaskResult, } from "./repair.js";
+import { attemptTrackedResultRepair, detectExplicitHardStopStatus, isTrackedResultRepairEligible, unwrapResumableTaskResult, } from "./repair.js";
 import { parseResultBlock, parseWorkItemHeader, TRACKED_SUBAGENT_NAMES, } from "./protocol.js";
-import { applyTrackedResult, createRecordLookupKey, createWorkflowResultExcerpt, beginTrackedLaunch, createWorkItemStore, getReviewRound, getWorkItem, revertReviewerLaunch, } from "./state.js";
-import { applyDelegatedLaunchFailure, applyDelegatedResult, beginDelegatedLaunch, revertInFlightDelegatedLaunches, } from "./delegated.js";
+import { applyTrackedResult, createRecordLookupKey, createWorkflowResultExcerpt, beginTrackedLaunch, createWorkItemStore, createWorkItemStoreView, getReviewRound, getWorkItem, revertReviewerLaunch, } from "./state.js";
+import { applyDelegatedLaunchFailure, applyDelegatedReportRejection, applyDelegatedResult, beginDelegatedLaunch, revertInFlightDelegatedLaunches, summarizeDelegatedProgress, } from "./delegated.js";
 import { checkpointBarrierUnsatisfied, findOverlappingInFlightReview, recordCheckpointReviewerLaunch, recordCheckpointReviewerResult, } from "./checkpoints.js";
 import { getAllowedNextAgents, getAttemptedImplementationRound, getReviewerRoleForAgent, shouldBlockRound, } from "./transitions.js";
 import { createWorkItemCloseTool, createWorkItemDecideTool, createWorkItemListTool, createWorkItemOpenTool, createWorkCheckpointTool, } from "./tooling.js";
@@ -30,6 +30,8 @@ import { resolveOrchestrationPolicy, } from "../../lib/orchestration.js";
 import { isVvocPluginEnabled } from "../../lib/plugin-toggle-config.js";
 import { deleteWorkflowSessionDir, hydrateWorkflowStateChecked, snapshotWorkflowStateChecked, } from "./persistence.js";
 import { loadApprovedDelegatedPlan } from "./checkpoint-io.js";
+import { isTaskLaunchableInStore } from "./execution.js";
+import { runWorkflowTransaction, WorkflowTransactionQueue } from "./transactions.js";
 const z = tool.schema;
 const TRACKED_SUBAGENT_SET = new Set(TRACKED_SUBAGENT_NAMES);
 const WORK_ITEM_MISSING_MARKER = "__VVOC" + "_SECRET_BEARER_TOKEN_a6f582092f05__";
@@ -71,10 +73,31 @@ work_item_decide with the attempt number to accept or request changes. DONE_WITH
 an explicit concerns disposition. Controller retries are bounded to one correction attempt before
 explicit recovery; BLOCKED and NEEDS_CONTEXT remain hard stops.
 
-Register an approved plan once with work_checkpoint register, start each declared review checkpoint
-only after its prerequisite tasks are accepted, and run the due checkpoint before dependent waves.
-A checkpoint passes only when every declared reviewer passes against the pinned snapshot; a closed
-review-only FAIL report is a findings result, not approval. Do not write source files yourself:
+Bounded recovery: when a delegated task stops (BLOCKED or NEEDS_CONTEXT) or exhausts its two
+ordinary attempts without acceptance, diagnose it yourself and call work_item_decide with decision
+"recover", the terminal attempt number, a diagnosis, the changed condition or approach, the
+required verification references, and a stable recoveryId. A recovery resumes the same work item
+and its ordinary budget; when a further attempt is necessary it grants exactly one. The single
+autonomous grant per target is consumed on first use. After that, a further unit requires either a
+fresh root-user message referenced by userMessageId — validated for role, session identity, and
+timing, never wording — or a recorded advance authority referenced by runId and authorityId whose
+finite shared reserve still has a unit. Recovery never accepts a result, replaces a reviewer, or
+changes declared scope. A rejected report (a worker execution that finished with a protocol-invalid
+result) is recorded with bounded diagnostics and has the same recovery path; it never becomes DONE.
+
+Requirements may come from the supported approved native spec/plan package under .vvoc/specs/, a
+provided plan reference, or the current conversation. Register a native package once with
+work_checkpoint register (planPath); start and verify declared checkpoints only after their
+prerequisite tasks are accepted. A provided-plan or conversation-scoped run is registered once with
+work_item_open carrying an execution descriptor (executionKey, source, goal, boundary) and its
+first task batch; later tasks append with the same runId plus amendmentId and rationale, and generic
+review obligations run through work_checkpoint start/review/complete. A selected source stays
+authoritative: a failed native package is never silently reopened as weaker generic execution, and
+a provided document is never converted or executed as commands. A checkpoint passes only when
+every declared reviewer passes against the pinned snapshot; a closed review-only FAIL report is a
+findings result, not approval. A checkpoint generation that stopped or exhausted its ordinary
+generations recovers through work_checkpoint action "recover" with the same bounded fields and the
+same authority options. Do not write source files yourself:
 delegate implementation edits, including fixes requested by reviewers, through bounded task
 packets, while keeping planning artifacts, acceptance decisions, and verification commands in this
 session.
@@ -250,7 +273,6 @@ export const WorkflowPlugin = async ({ client, directory, worktree }) => {
         return {};
     const resolvedPolicy = resolveOrchestrationPolicy(vvoc.config);
     const workflowSystemInstruction = getWorkflowSystemInstruction(resolvedPolicy);
-    const delegatedProfileActive = resolvedPolicy.profile === "delegated";
     const trustedWorkspaceRoot = worktree || directory;
     // START_BLOCK_PERSISTENCE_SETUP
     // Each session (main or subagent) gets its own isolated store.
@@ -452,6 +474,76 @@ export const WorkflowPlugin = async ({ client, directory, worktree }) => {
         })
             .catch(() => undefined);
     }
+    /**
+     * Settle a confirmed terminal protocol-invalid delegated report: the domain
+     * reducer applies to a staged copy, the staged state persists, and only then
+     * the settled record commits to the live store, returning the settled
+     * attempt number. A failed write keeps the live in-flight attempt so an
+     * unpersisted settlement never frees a launch slot.
+     */
+    function commitDelegatedReportRejection(sessionId, workItemId, callId, protocolErrorCode, excerpt, explicitHardStop) {
+        const liveStore = stores.get(sessionId);
+        if (!liveStore || invalidHydrationSessions.has(sessionId))
+            return undefined;
+        const liveData = liveStore.getStoreData();
+        const stagedStore = createWorkItemStore(liveData);
+        const applied = applyDelegatedReportRejection(stagedStore, {
+            sessionId,
+            workItemId,
+            callId,
+            protocolErrorCode,
+            excerpt,
+            ...(explicitHardStop ? { explicitHardStop } : {}),
+        });
+        if (!applied.ok) {
+            // Stale, duplicate, or already-transitioned: nothing to settle.
+            return undefined;
+        }
+        const stagedData = stagedStore.getStoreData();
+        const persisted = snapshotWorkflowStateChecked(sessionId, stagedData);
+        if (!persisted.ok) {
+            void client.app
+                .log({
+                body: {
+                    service: "workflow",
+                    level: "error",
+                    message: "[workflow][reportRejection][BLOCK_REPORT_REJECTION] persistence failed",
+                    extra: {
+                        sessionID: sessionId,
+                        workItemId,
+                        attempt: applied.attempt,
+                        error: persisted.error.slice(0, 300),
+                    },
+                },
+            })
+                .catch(() => undefined);
+            return undefined;
+        }
+        const lookupKey = createRecordLookupKey(sessionId, workItemId);
+        const committed = stagedData.records.get(lookupKey);
+        if (!committed)
+            return undefined;
+        liveData.records.set(lookupKey, committed);
+        void client.app
+            .log({
+            body: {
+                service: "workflow",
+                level: "warn",
+                message: "[workflow][reportRejection][BLOCK_REPORT_REJECTION] terminal report rejected and settled",
+                extra: {
+                    sessionID: sessionId,
+                    workItemId,
+                    attempt: applied.attempt,
+                    protocolErrorCode,
+                    observedHardStop: explicitHardStop,
+                    consumedAttempts: applied.consumedAttempts,
+                    attemptBudget: applied.attemptBudget,
+                },
+            },
+        })
+            .catch(() => undefined);
+        return applied.attempt;
+    }
     function handleDelegatedPartUpdated(properties) {
         const part = properties.part;
         if (!part || typeof part !== "object")
@@ -570,6 +662,185 @@ export const WorkflowPlugin = async ({ client, directory, worktree }) => {
         }
     }
     // END_BLOCK_DELEGATED_AUTHORIZATION
+    // START_BLOCK_RECOVERY_SUPPORT
+    // Read-only SDK message lookup for user-authorized recovery. Only identity
+    // and timing metadata (role, sessionID, id, time.created) are retained;
+    // message bodies never enter validation, persistence, or logs. Transport
+    // failures throw so the domain reports AUTHORIZATION_LOOKUP_FAILED instead
+    // of conflating an unreachable lookup with a nonexistent message.
+    const lookupRecoveryUserMessage = async (sessionId, messageId) => {
+        const response = await client.session.message({
+            path: { id: sessionId, messageID: messageId },
+            query: { directory },
+        });
+        if (response.error || !response.data) {
+            const errorName = response.error?.name;
+            if (errorName && errorName !== "NotFound") {
+                throw new Error(`session message lookup failed: ${errorName}`);
+            }
+            return undefined;
+        }
+        const info = response.data.info;
+        return {
+            role: info.role,
+            sessionID: info.sessionID,
+            id: info.id,
+            timeCreatedMs: typeof info.time?.created === "number" && Number.isFinite(info.time.created)
+                ? info.time.created
+                : undefined,
+        };
+    };
+    // Advance-authority provenance uses the same pinned SDK message response.
+    // Only verified identity/timing/eligibility metadata leaves this lookup; raw
+    // user text is never persisted or logged.
+    const lookupAuthorityMessage = async (input) => {
+        const response = await client.session.message({
+            path: { id: input.sessionId, messageID: input.messageId },
+            query: { directory },
+        });
+        if (response.error || !response.data) {
+            const errorName = response.error?.name;
+            if (errorName && errorName !== "NotFound") {
+                throw new Error(`authority message lookup failed: ${errorName}`);
+            }
+            return undefined;
+        }
+        const info = response.data.info;
+        const parts = Array.isArray(response.data.parts) ? response.data.parts : [];
+        const textParts = parts
+            .map((part) => part)
+            .filter((part) => part.type === "text" && typeof part.text === "string")
+            .map((part) => part.text);
+        return {
+            messageId: info.id ?? input.messageId,
+            sessionId: info.sessionID ?? input.sessionId,
+            role: info.role === "user" ? "user" : "assistant",
+            createdMs: typeof info.time?.created === "number" && Number.isFinite(info.time.created)
+                ? info.time.created
+                : 0,
+            ignored: info.ignored === true,
+            syntheticOnly: false,
+            textParts,
+        };
+    };
+    // Per-session serialization for generic mutating tool calls. The staged
+    // snapshot persists before the committed state is published, so a failed
+    // write never exposes new obligations, authority, or launch permissions.
+    const workflowTransactions = new WorkflowTransactionQueue();
+    async function commitGenericToolResult(sessionId, run) {
+        const liveStore = stores.get(sessionId);
+        if (!liveStore) {
+            return {
+                ok: false,
+                errorCode: "SESSION_MISMATCH",
+                message: `no live workflow store for session ${sessionId}`,
+            };
+        }
+        if (invalidHydrationSessions.has(sessionId)) {
+            return {
+                ok: false,
+                errorCode: "INVALID_STATE",
+                message: `persisted workflow state for session ${sessionId} is invalid`,
+            };
+        }
+        const outcome = await runWorkflowTransaction({
+            queue: workflowTransactions,
+            sessionId,
+            getData: () => liveStore.getStoreData(),
+            operation: async (staged) => {
+                const result = await run(createWorkItemStoreView(staged));
+                if (result.ok !== true) {
+                    // Validation failed: persist nothing and publish nothing.
+                    return { result, skipPersist: true };
+                }
+                return { result };
+            },
+        });
+        if (!outcome.ok) {
+            void client.app
+                .log({
+                body: {
+                    service: "workflow",
+                    level: "error",
+                    message: "[workflow][generic][BLOCK_GENERIC_COMMIT] persistence failed",
+                    extra: { sessionID: sessionId, error: outcome.error.slice(0, 300) },
+                },
+            })
+                .catch(() => undefined);
+            return {
+                ok: false,
+                errorCode: "PERSISTENCE_FAILED",
+                message: `generic workflow mutation could not be persisted: ${outcome.error}`,
+            };
+        }
+        return outcome.result;
+    }
+    /**
+     * Execute one recovery mutation durably on the live store: the domain
+     * reducer applies to the live entry (re-prechecking after any authorization
+     * await), and the whole live store is then persisted synchronously. If the
+     * write fails, the captured prior entry is restored so no unpersisted launch
+     * permission is ever exposed — there is no await between mutation, persist,
+     * and rollback, so no concurrent actor can observe the intermediate state,
+     * and no stale whole-store snapshot can regress concurrent transitions.
+     */
+    async function executeCommittedRecovery(sessionId, runRecovery, captureRestore, wasApplied) {
+        const liveStore = stores.get(sessionId);
+        if (!liveStore || invalidHydrationSessions.has(sessionId)) {
+            throw new Error(`CONTROL_DENIED: persisted workflow state for session ${sessionId} is invalid; resolve or remove it before new control mutations.`);
+        }
+        const restore = captureRestore();
+        const result = await runRecovery(liveStore);
+        if (!wasApplied(result)) {
+            return result;
+        }
+        const persisted = snapshotWorkflowStateChecked(sessionId, liveStore.getStoreData());
+        if (!persisted.ok) {
+            restore();
+            void client.app
+                .log({
+                body: {
+                    service: "workflow",
+                    level: "error",
+                    message: "[workflow][recovery][BLOCK_RECOVERY_COMMIT] recovery persistence failed",
+                    extra: { sessionID: sessionId, error: persisted.error.slice(0, 300) },
+                },
+            })
+                .catch(() => undefined);
+            throw new Error(`PERSISTENCE_FAILED: recovery applied in memory but could not be persisted and was rolled back: ${persisted.error}`);
+        }
+        return result;
+    }
+    /** Capture and restore one work-item record entry for recovery rollback. */
+    function captureRecordRestore(sessionId, workItemId) {
+        const liveStore = stores.get(sessionId);
+        if (!liveStore)
+            return () => undefined;
+        const liveData = liveStore.getStoreData();
+        const lookupKey = createRecordLookupKey(sessionId, workItemId);
+        const prior = liveData.records.get(lookupKey);
+        return () => {
+            if (prior) {
+                liveData.records.set(lookupKey, prior);
+            }
+        };
+    }
+    /** Capture and restore one checkpoint entry for recovery rollback. */
+    function captureCheckpointRestore(sessionId, runId, checkpointId) {
+        const liveStore = stores.get(sessionId);
+        if (!liveStore)
+            return () => undefined;
+        const run = liveStore.getStoreData().planRuns.get(runId);
+        if (!run)
+            return () => undefined;
+        const priorCheckpoint = run.checkpoints.get(checkpointId);
+        return () => {
+            if (priorCheckpoint) {
+                run.checkpoints.set(checkpointId, priorCheckpoint);
+            }
+        };
+    }
+    // END_BLOCK_RECOVERY_SUPPORT
     // START_BLOCK_CHECKPOINT_LINKAGE
     /** Find the in-flight checkpoint generation whose linked review item matches. */
     function findCheckpointByReviewItem(sessionId, reviewWorkItemId) {
@@ -592,8 +863,13 @@ export const WorkflowPlugin = async ({ client, directory, worktree }) => {
     const workItemOpenTool = createWorkItemOpenTool(dummyStore);
     const workItemListTool = createWorkItemListTool(dummyStore);
     const workItemCloseTool = createWorkItemCloseTool(dummyStore);
-    const workItemDecideTool = createWorkItemDecideTool(dummyStore);
-    const workCheckpointTool = createWorkCheckpointTool(dummyStore);
+    const workItemDecideTool = createWorkItemDecideTool(dummyStore, {
+        lookupUserMessage: lookupRecoveryUserMessage,
+    });
+    const workCheckpointTool = createWorkCheckpointTool(dummyStore, {
+        lookupUserMessage: lookupRecoveryUserMessage,
+        lookupAuthorityMessage,
+    });
     return {
         tool: {
             work_item_open: tool({
@@ -607,10 +883,42 @@ export const WorkflowPlugin = async ({ client, directory, worktree }) => {
                         writeScope: z.array(z.string()).optional(),
                         planRunId: z.string().optional(),
                         planTaskId: z.string().optional(),
+                        taskId: z.string().optional(),
+                        goal: z.string().optional(),
+                        acceptanceCriteria: z.array(z.string()).optional(),
+                        verification: z.array(z.string()).optional(),
+                        dependsOn: z.array(z.string()).optional(),
+                        blockedBy: z.array(z.string()).optional(),
                     })),
+                    execution: z
+                        .object({
+                        executionKey: z.string(),
+                        source: z.record(z.string(), z.unknown()),
+                        goal: z.string(),
+                        boundary: z.object({
+                            files: z.array(z.string()),
+                            directories: z.array(z.string()),
+                        }),
+                        checkpoints: z.array(z.record(z.string(), z.unknown())).optional(),
+                    })
+                        .optional(),
+                    runId: z.string().optional(),
+                    amendmentId: z.string().optional(),
+                    rationale: z.string().optional(),
                 },
                 async execute(args, context) {
                     assertWorkflowToolAccess(context.agent, "work_item_open");
+                    const isGeneric = args.execution !== undefined || args.runId !== undefined;
+                    if (isGeneric) {
+                        // Hydrate/validate the session store before the transaction boundary
+                        // reads it, matching every other tool entry point.
+                        getOrCreateStore(context.sessionID);
+                        const result = await commitGenericToolResult(context.sessionID, (view) => workItemOpenTool.execute(args, {
+                            sessionId: context.sessionID,
+                            workspaceRoot: trustedWorkspaceRoot,
+                        }, view));
+                        return stringifyToolOutput(result);
+                    }
                     const sessionStore = getOrCreateStore(context.sessionID);
                     const opened = workItemOpenTool.execute(args, { sessionId: context.sessionID }, sessionStore);
                     snapshotSession(context.sessionID);
@@ -641,73 +949,153 @@ export const WorkflowPlugin = async ({ client, directory, worktree }) => {
                     return stringifyToolOutput(closed);
                 },
             }),
-            // The delegated control tools are registered only under the delegated
-            // startup profile; other profiles keep their current tool-schema footprint.
-            ...(delegatedProfileActive
-                ? {
-                    work_item_decide: tool({
-                        description: workItemDecideTool.description,
-                        args: {
-                            workItemId: z.string(),
-                            attempt: z.number().int().min(1),
-                            decision: z.enum(["accept", "request_changes", "rework"]),
-                            rationale: z.string(),
-                            evidence: z.array(z.string()),
-                            concernsDisposition: z.string().optional(),
-                            runId: z.string().optional(),
-                            checkpointId: z.string().optional(),
-                        },
-                        async execute(args, context) {
-                            // Resolve the store first so invalid persisted state is detected
-                            // before the authorization check reports it as a control denial.
-                            const sessionStore = getOrCreateStore(context.sessionID);
-                            await assertPrimaryControllerMutation(context.agent, context.sessionID, { directory: context.directory, worktree: context.worktree }, "work_item_decide");
-                            const decided = workItemDecideTool.execute(args, { sessionId: context.sessionID }, sessionStore);
-                            if (decided.ok) {
-                                const persisted = snapshotSession(context.sessionID);
-                                if (!persisted.ok) {
-                                    throw new Error(`PERSISTENCE_FAILED: decision applied in memory but could not be persisted: ${persisted.error}`);
-                                }
+            // Control tools are registered independent of the startup profile; they
+            // remain root-session, agent, workspace, and invalid-hydration gated at
+            // execution time.
+            ...{
+                work_item_decide: tool({
+                    description: workItemDecideTool.description,
+                    args: {
+                        workItemId: z.string(),
+                        attempt: z.number().int().min(1),
+                        decision: z.enum(["accept", "request_changes", "rework", "recover"]),
+                        rationale: z.string().optional(),
+                        evidence: z.array(z.string()).optional(),
+                        concernsDisposition: z.string().optional(),
+                        runId: z.string().optional(),
+                        checkpointId: z.string().optional(),
+                        diagnosis: z.string().optional(),
+                        changedCondition: z.string().optional(),
+                        verification: z.array(z.string()).optional(),
+                        recoveryId: z.string().optional(),
+                        userMessageId: z.string().optional(),
+                        authorityId: z.string().optional(),
+                    },
+                    async execute(args, context) {
+                        // Resolve the store first so invalid persisted state is detected
+                        // before the authorization check reports it as a control denial.
+                        const sessionStore = getOrCreateStore(context.sessionID);
+                        await assertPrimaryControllerMutation(context.agent, context.sessionID, { directory: context.directory, worktree: context.worktree }, "work_item_decide");
+                        // Recovery is the only decision family that must persist
+                        // before it exposes new launch permissions. Authority-bearing
+                        // recovery stages the work-item recovery and the reserve debit in
+                        // one serialized transaction so they commit or fail together.
+                        if (args.decision === "recover") {
+                            if (args.authorityId !== undefined) {
+                                const staged = await commitGenericToolResult(context.sessionID, (view) => workItemDecideTool.execute(args, { sessionId: context.sessionID }, view));
+                                return stringifyToolOutput(staged);
                             }
-                            return stringifyToolOutput(decided);
-                        },
-                    }),
-                    work_checkpoint: tool({
-                        description: workCheckpointTool.description,
-                        args: {
-                            action: z.enum(["register", "start", "verify"]),
-                            planPath: z.string().optional(),
-                            runId: z.string().optional(),
-                            checkpointId: z.string().optional(),
-                            complete: z.boolean().optional(),
-                        },
-                        async execute(args, context) {
-                            // Resolve the store first so invalid persisted state is detected
-                            // before the authorization check reports it as a control denial.
-                            const sessionStore = getOrCreateStore(context.sessionID);
-                            await assertPrimaryControllerMutation(context.agent, context.sessionID, { directory: context.directory, worktree: context.worktree }, "work_checkpoint");
-                            const toolContext = {
-                                sessionId: context.sessionID,
-                                workspaceRoot: trustedWorkspaceRoot,
-                                loadPlan: async (planPath, workspaceRoot) => {
-                                    const loaded = await loadApprovedDelegatedPlan({ workspaceRoot, planPath });
-                                    return loaded.ok
-                                        ? loaded.plan
-                                        : { loadError: `${loaded.code}: ${loaded.message}` };
-                                },
-                            };
-                            const result = await workCheckpointTool.execute({ ...args }, toolContext, sessionStore);
-                            if (result.ok) {
-                                const persisted = snapshotSession(context.sessionID);
-                                if (!persisted.ok) {
-                                    throw new Error(`PERSISTENCE_FAILED: checkpoint change applied in memory but could not be persisted: ${persisted.error}`);
-                                }
+                            const workItemId = String(args.workItemId ?? "");
+                            const recovered = await executeCommittedRecovery(context.sessionID, (liveStore) => workItemDecideTool.execute(args, { sessionId: context.sessionID }, liveStore), () => captureRecordRestore(context.sessionID, workItemId), (result) => result.ok === true);
+                            return stringifyToolOutput(recovered);
+                        }
+                        const decided = await workItemDecideTool.execute(args, { sessionId: context.sessionID }, sessionStore);
+                        if (decided.ok) {
+                            const persisted = snapshotSession(context.sessionID);
+                            if (!persisted.ok) {
+                                throw new Error(`PERSISTENCE_FAILED: decision applied in memory but could not be persisted: ${persisted.error}`);
                             }
+                        }
+                        return stringifyToolOutput(decided);
+                    },
+                }),
+                work_checkpoint: tool({
+                    description: workCheckpointTool.description,
+                    args: {
+                        action: z.enum([
+                            "register",
+                            "start",
+                            "verify",
+                            "recover",
+                            "review",
+                            "bind",
+                            "complete",
+                            "amend",
+                            "authorize",
+                            "record_approval",
+                            "revoke_authority",
+                        ]),
+                        planPath: z.string().optional(),
+                        runId: z.string().optional(),
+                        checkpointId: z.string().optional(),
+                        complete: z.boolean().optional(),
+                        diagnosis: z.string().optional(),
+                        changedCondition: z.string().optional(),
+                        verification: z.array(z.string()).optional(),
+                        recoveryId: z.string().optional(),
+                        userMessageId: z.string().optional(),
+                        checkpoints: z.array(z.record(z.string(), z.unknown())).optional(),
+                        tasks: z.array(z.record(z.string(), z.unknown())).optional(),
+                        amendmentId: z.string().optional(),
+                        rationale: z.string().optional(),
+                        startFingerprint: z.string().optional(),
+                        reviewer: z.string().optional(),
+                        authorityId: z.string().optional(),
+                        messageId: z.string().optional(),
+                        approvalId: z.string().optional(),
+                        stage: z.string().optional(),
+                        stages: z.array(z.string()).optional(),
+                        decisionScope: z.string().optional(),
+                        fileBoundary: z.array(z.string()).optional(),
+                        reservedStops: z.array(z.string()).optional(),
+                        artifactPath: z.string().optional(),
+                        artifactSha256: z.string().optional(),
+                        revocationId: z.string().optional(),
+                    },
+                    async execute(args, context) {
+                        // Resolve the store first so invalid persisted state is detected
+                        // before the authorization check reports it as a control denial.
+                        const sessionStore = getOrCreateStore(context.sessionID);
+                        await assertPrimaryControllerMutation(context.agent, context.sessionID, { directory: context.directory, worktree: context.worktree }, "work_checkpoint");
+                        const toolContext = {
+                            sessionId: context.sessionID,
+                            workspaceRoot: trustedWorkspaceRoot,
+                            loadPlan: async (planPath, workspaceRoot) => {
+                                const loaded = await loadApprovedDelegatedPlan({ workspaceRoot, planPath });
+                                return loaded.ok ? loaded.plan : { loadError: `${loaded.code}: ${loaded.message}` };
+                            },
+                        };
+                        // Generic (non-native) executions route through the atomic
+                        // transaction boundary: staged persist, then publish.
+                        const runIdArg = String(args.runId ?? "");
+                        const liveExecution = runIdArg
+                            ? sessionStore.getStoreData().executions.get(runIdArg)
+                            : undefined;
+                        const authorityAction = args.action === "authorize" ||
+                            args.action === "record_approval" ||
+                            args.action === "revoke_authority";
+                        const genericAction = args.action !== "register" &&
+                            liveExecution !== undefined &&
+                            (liveExecution.source.kind !== "native-package" || authorityAction);
+                        const nativeAuthorityRecover = args.action === "recover" &&
+                            args.authorityId !== undefined &&
+                            liveExecution !== undefined;
+                        const genericRegister = args.action === "register" && !args.planPath;
+                        if (genericAction || genericRegister || nativeAuthorityRecover) {
+                            const result = await commitGenericToolResult(context.sessionID, (view) => workCheckpointTool.execute(args, toolContext, view));
                             return stringifyToolOutput(result);
-                        },
-                    }),
-                }
-                : {}),
+                        }
+                        // Checkpoint recovery commits durably on the live store and
+                        // rolls the checkpoint entry back on write failure, so a
+                        // granted generation is never exposed before its state is
+                        // durably recorded.
+                        if (args.action === "recover") {
+                            const runId = String(args.runId ?? "");
+                            const checkpointId = String(args.checkpointId ?? "");
+                            const recovered = await executeCommittedRecovery(context.sessionID, (liveStore) => workCheckpointTool.execute(args, toolContext, liveStore), () => captureCheckpointRestore(context.sessionID, runId, checkpointId), (result) => result.ok === true);
+                            return stringifyToolOutput(recovered);
+                        }
+                        const result = await workCheckpointTool.execute({ ...args }, toolContext, sessionStore);
+                        if (result.ok) {
+                            const persisted = snapshotSession(context.sessionID);
+                            if (!persisted.ok) {
+                                throw new Error(`PERSISTENCE_FAILED: checkpoint change applied in memory but could not be persisted: ${persisted.error}`);
+                            }
+                        }
+                        return stringifyToolOutput(result);
+                    },
+                }),
+            },
         },
         "tool.execute.before": async (input, output) => {
             if (input.tool !== "task") {
@@ -754,6 +1142,41 @@ export const WorkflowPlugin = async ({ client, directory, worktree }) => {
                 });
                 throw new Error(`${WORK_ITEM_MISSING_MARKER} LAUNCH_REJECTED_UNKNOWN_WORK_ITEM: no open work item ${header.value} exists in this session. Use work_item_open first or check state with work_item_list.`);
             }
+            // Generic executions enforce declared task dependencies and checkpoint
+            // barriers at launch, not only at completion.
+            if (subagentType === "vv-implementer") {
+                const data = sessionStore.getStoreData();
+                for (const execution of data.executions.values()) {
+                    if (execution.sessionId !== input.sessionID)
+                        continue;
+                    const boundTask = [...execution.tasks.values()].find((binding) => binding.workItemId === workItem.workItemId);
+                    if (!boundTask)
+                        continue;
+                    const launchable = isTaskLaunchableInStore(data, {
+                        sessionId: input.sessionID,
+                        runId: execution.runId,
+                        taskId: boundTask.taskId,
+                    });
+                    if (!launchable.ok) {
+                        await client.app.log({
+                            body: {
+                                service: "workflow",
+                                level: "warn",
+                                message: "[workflow][launchValidation][BLOCK_VALIDATE_LAUNCH] dependency gate",
+                                extra: {
+                                    sessionID: input.sessionID,
+                                    workItemId: workItem.workItemId,
+                                    runId: execution.runId,
+                                    taskId: boundTask.taskId,
+                                    reason: launchable.reason,
+                                },
+                            },
+                        });
+                        throw new Error(`${INVALID_NEXT_AGENT_MARKER} LAUNCH_REJECTED_DEPENDENCY: task ${boundTask.taskId} cannot start yet: ${launchable.message}`);
+                    }
+                    break;
+                }
+            }
             const allowedNextAgents = getAllowedNextAgents(workItem);
             const reviewRound = getReviewRound(workItem);
             const attemptedRound = subagentType === "vv-implementer" ? getAttemptedImplementationRound(workItem) : reviewRound;
@@ -984,7 +1407,7 @@ export const WorkflowPlugin = async ({ client, directory, worktree }) => {
                 expectedWorkItemId: header.value,
             });
             if (!parsed.ok) {
-                const explicitHardStop = hasExplicitHardStopStatus(unwrapped.normalizedOutput);
+                const explicitHardStop = detectExplicitHardStopStatus(unwrapped.normalizedOutput);
                 if (unwrapped.envelope &&
                     isTrackedResultRepairEligible(parsed.error.code) &&
                     !explicitHardStop) {
@@ -1042,8 +1465,44 @@ export const WorkflowPlugin = async ({ client, directory, worktree }) => {
                     },
                 });
                 revertLaunch();
+                // A confirmed terminal delegated execution whose report stays
+                // protocol-invalid settles as a completed execution with a rejected
+                // report: never in flight, never DONE, with the observed substantive
+                // hard stop preserved and a supported recovery path remaining.
+                // Unknown (non-string) or mismatched outputs never reach here.
+                const currentForSettlement = getWorkItem(getOrCreateStore(input.sessionID), input.sessionID, header.value);
+                const settledAttempt = (() => {
+                    if (!protocolFailureExcerpt || !currentForSettlement)
+                        return undefined;
+                    if (currentForSettlement.state === "closed" ||
+                        currentForSettlement.mode !== "delegated" ||
+                        subagentType !== "vv-implementer") {
+                        return undefined;
+                    }
+                    if (!currentForSettlement.delegated?.attempts.some((attempt) => attempt.status === "in_flight" && attempt.callId === input.callID)) {
+                        return undefined;
+                    }
+                    const observedHardStop = detectExplicitHardStopStatus(unwrapped.normalizedOutput);
+                    return commitDelegatedReportRejection(input.sessionID, header.value, input.callID, parsed.error.code, protocolFailureExcerpt, observedHardStop);
+                })();
+                const settlementLines = settledAttempt
+                    ? [
+                        `Report rejected: attempt ${settledAttempt} of ${header.value} settled as report_rejected with bounded diagnostics retained.`,
+                        (() => {
+                            const settledRecord = getWorkItem(getOrCreateStore(input.sessionID), input.sessionID, header.value);
+                            const progress = settledRecord
+                                ? summarizeDelegatedProgress(settledRecord)
+                                : undefined;
+                            return `Next action: ${progress?.nextAction ?? "inspect work_item_list"}${progress?.nextAction === "recover" ||
+                                progress?.nextAction === "recover_with_user_authorization"
+                                ? ' through work_item_decide decision "recover"'
+                                : ""}.`;
+                        })(),
+                    ]
+                    : [];
                 throw new Error([
                     `RESULT_PROTOCOL_ERROR: ${parsed.error.message}`,
+                    ...settlementLines,
                     formatResultExcerptForError(protocolFailureExcerpt),
                 ].join("\n"));
             }