@paperclipai/server 2026.824.0 → 2026.825.0-beta.1

package/dist/routes/issues.js

@@ -4,13 +4,15 @@ import multer from "multer";
 import { z } from "zod";
 import { and, asc, desc, eq, inArray, isNull, notInArray } from "drizzle-orm";
 import { activityLog, agents, approvals, companyMemberships, documents, executionWorkspaces, heartbeatRuns, issueApprovals, issueComments, issueDocuments, issueExecutionDecisions, issueRelations, issueThreadInteractions, issues as issueRows, issueWorkProducts, pipelineCaseIssueLinks, pipelineCases, pipelineStages, pipelines, projectWorkspaces, } from "@paperclipai/db";
-import { addIssueCommentSchema, acceptIssueThreadInteractionSchema, attachmentArtifactWorkProductMetadataSchema, cancelIssueThreadInteractionSchema, withdrawIssueThreadInteractionSchema, companySearchExtractQuerySchema, companySearchQuerySchema, createIssueAttachmentMetadataSchema, createIssueThreadInteractionSchema, createIssueWorkProductSchema, createIssueLabelSchema, createAcceptedPlanDecompositionSchema, checkoutIssueSchema, createDocumentAnnotationCommentSchema, createDocumentAnnotationThreadSchema, createChildIssueSchema, createIssueSchema, resolveCreateIssueStatusDefault, resolveIssueRecoveryActionSchema, feedbackTargetTypeSchema, feedbackTraceStatusSchema, feedbackVoteValueSchema, upsertIssueFeedbackVoteSchema, upsertIssueWatchdogSchema, linkIssueApprovalSchema, issueDocumentKeySchema, ISSUE_CONTINUATION_SUMMARY_DOCUMENT_KEY, ISSUE_WATCHDOG_DISCOVERY_KINDS, TASK_WATCHDOG_PRODUCT_BUG_ORIGIN_KIND, ONBOARDING_FIRST_TASK_ORIGIN_KIND, rejectIssueThreadInteractionSchema, restoreIssueDocumentRevisionSchema, respondIssueThreadInteractionSchema, stalledReviewDecisionSchema, submitIssueThreadInteractionVerdictsSchema, updateIssueWorkProductSchema, updateDocumentAnnotationThreadSchema, upsertIssueDocumentSchema, updateIssueSchema, isClosedIsolatedExecutionWorkspace, isUuidLike, normalizeIssueIdentifier as normalizeIssueReferenceIdentifier, issueWriteDenialCodeForResponsibleUserDenial, issueWriteDenialResponse, } from "@paperclipai/shared";
+import { addIssueCommentSchema, acceptIssueThreadInteractionSchema, attachmentArtifactWorkProductMetadataSchema, cancelIssueThreadInteractionSchema, withdrawIssueThreadInteractionSchema, companySearchExtractQuerySchema, companySearchQuerySchema, createIssueAttachmentMetadataSchema, createIssueThreadInteractionSchema, createIssueWorkProductSchema, createIssueLabelSchema, createAcceptedPlanDecompositionSchema, checkoutIssueSchema, createDocumentAnnotationCommentSchema, createDocumentAnnotationThreadSchema, createChildIssueSchema, createIssueSchema, resolveCreateIssueStatusDefault, resolveIssueRecoveryActionSchema, feedbackTargetTypeSchema, feedbackTraceStatusSchema, feedbackVoteValueSchema, upsertIssueFeedbackVoteSchema, upsertIssueWatchdogSchema, linkIssueApprovalSchema, issueDocumentKeySchema, ISSUE_CONTINUATION_SUMMARY_DOCUMENT_KEY, ISSUE_WATCHDOG_DISCOVERY_KINDS, TASK_WATCHDOG_PRODUCT_BUG_ORIGIN_KIND, ONBOARDING_FIRST_TASK_ORIGIN_KIND, rejectIssueThreadInteractionSchema, restoreIssueDocumentRevisionSchema, respondIssueThreadInteractionSchema, stalledReviewDecisionSchema, submitIssueThreadInteractionVerdictsSchema, updateIssueWorkProductSchema, updateDocumentAnnotationThreadSchema, upsertIssueDocumentSchema, updateIssueSchema, isClosedIsolatedExecutionWorkspace, isMarkdownArtifactWorkProduct, isMarkdownAttachmentContent, isUuidLike, normalizeIssueIdentifier as normalizeIssueReferenceIdentifier, issueWriteDenialCodeForResponsibleUserDenial, issueWriteDenialResponse, } from "@paperclipai/shared";
 import { trackAgentTaskCompleted } from "@paperclipai/shared/telemetry";
 import { getTelemetryClient } from "../telemetry.js";
 import { isUniqueViolation } from "../db-errors.js";
-import { validate } from "../middleware/validate.js";
+import { validate, validateIssueMutationBody } from "../middleware/validate.js";
 import * as serviceIndex from "../services/index.js";
-import { accessService, agentService, companySkillService, companyService, companySearchService, goalService, heartbeatService, issueApprovalService, issueRecoveryActionService, issueThreadInteractionService, ISSUE_LIST_DEFAULT_LIMIT, ISSUE_LIST_MAX_LIMIT, issueReferenceService, issueService, clampIssueListLimit, documentService, documentAnnotationService, logActivity, publishActivity, projectService, routineService, workProductService, } from "../services/index.js";
+import { accessService, agentService, budgetService, companySkillService, companyService, companySearchService, goalService, heartbeatService, issueApprovalService, issueRecoveryActionService, issueThreadInteractionService, ISSUE_LIST_DEFAULT_LIMIT, ISSUE_LIST_MAX_LIMIT, issueReferenceService, issueService, clampIssueListLimit, documentService, documentAnnotationService, logActivity, publishActivity, projectService, routineService, workProductService, } from "../services/index.js";
+import { artifactReviewDocumentService } from "../services/artifact-review-documents.js";
+import { assertCanResolveProposal } from "../services/secret-proposal-authorization.js";
 import { buildDocumentReviewContext, buildPlanReviewContext } from "../services/plan-review-context.js";
 import { decideIssueReviewPathRecovery, ISSUE_REVIEW_PATH_LOST_WAKE_REASON, isReviewPathRecoveryIdempotencyConflict, REVIEW_PATH_RECOVERY_INSTRUCTION, } from "../services/recovery/review-path-recovery.js";
 import { hydrateSuccessfulRunHandoffLiveness } from "../services/successful-run-handoff-state.js";
@@ -24,8 +26,10 @@ import { assertNoAgentHostWorkspaceCommandMutation, collectIssueWorkspaceCommand
 import { shouldWakeAssigneeOnCheckout } from "./issues-checkout-wakeup.js";
 import { GENERIC_ATTACHMENT_CONTENT_TYPES, isInlineAttachmentContentType, normalizeIssueAttachmentMaxBytes, normalizeContentType, normalizeUploadAttachmentContentType, SVG_CONTENT_TYPE, } from "../attachment-types.js";
 import { queueIssueAssignmentWakeup } from "../services/issue-assignment-wakeup.js";
+import { createSecretProposalsService } from "../services/secret-proposals.js";
+import { notifySecretProposalResolution } from "../services/secret-proposal-notifications.js";
 import { buildOnboardingGreeting, ONBOARDING_GREETING_AUTHORIZATION_REASON, } from "../services/onboarding-greeting.js";
-import { ISSUE_BLOCKERS_RESOLVED_WAKE_REASON, buildIssueBlockersResolvedWakeIdempotencyKey, findExistingIssueBlockersResolvedWake, } from "../services/issue-dependency-wakeups.js";
+import { ISSUE_BLOCKERS_RESOLVED_WAKE_REASON, buildIssueBlockersResolvedWakeStateKey, findExistingIssueBlockersResolvedWakeForReadyState, } from "../services/issue-dependency-wakeups.js";
 import { assertEnvironmentSelectionForCompany } from "./environment-selection.js";
 import { executionWorkspaceService as executionWorkspaceServiceDirect, STALE_REOPEN_PENDING_CONSUMPTION_GRACE_MS, } from "../services/execution-workspaces.js";
 import { decisionTrainingService } from "../services/decision-training.js";
@@ -59,17 +63,17 @@ function prefersMinimalIssueUpdateResponse(req) {
         .some((preference) => preference.trim().toLowerCase() === "return=minimal");
 }
 const refreshExternalObjectsSchema = z.object({
-    objectIds: z.array(z.string().uuid()).max(50).optional(),
+    objectIds: z.array(z.string().guid()).max(50).optional(),
 }).strict();
 const inboxArchiveBodySchema = z.object({
     userId: z.string().trim().min(1).optional(),
 }).strict().default({});
 const externalObjectSummariesSchema = z.object({
-    issueIds: z.array(z.string().uuid()).max(1000),
+    issueIds: z.array(z.string().guid()).max(1000),
 }).strict();
 const promoteLowTrustOutputSchema = z.object({
     sourceArtifactKind: z.enum(["comment", "document", "work_product", "issue"]),
-    sourceArtifactId: z.string().uuid(),
+    sourceArtifactId: z.string().guid(),
     title: z.string().trim().min(1).max(200),
     summary: z.string().trim().min(1).max(8_000),
 });
@@ -189,7 +193,7 @@ function requiresPaperclipAttachmentMetadata(input, fallback) {
     return type === "artifact" && provider === "paperclip";
 }
 const attachmentArtifactMetadataInputSchema = z.object({
-    attachmentId: z.string().uuid(),
+    attachmentId: z.string().guid(),
 }).passthrough();
 function buildCreateIssueActivityStatusDetails(issue, res) {
     const statusDefault = res.locals.createIssueStatusDefault;
@@ -1211,6 +1215,13 @@ function readToolActionExecutionStatus(value) {
         ? value
         : null;
 }
+function secretProposalExecutionErrorCode(error) {
+    if (error instanceof HttpError) {
+        const details = readObject(error.details);
+        return readNonEmptyString(details.code) ?? `http_${error.status}`;
+    }
+    return "secret_proposal_execution_failed";
+}
 function readToolActionContinuationContext(interaction) {
     const payload = readObject(interaction.payload);
     const toolActionPayload = readObject(payload.toolAction);
@@ -1269,6 +1280,49 @@ function readToolActionContinuationContext(interaction) {
         instructions: `the approved ${toolName} action is ${executionStatus}; do not call the tool again while this approval is being processed.`,
     };
 }
+function readSecretProposalContinuationContext(interaction) {
+    const payload = readObject(interaction.payload);
+    const proposal = readObject(payload.secretProposal);
+    const proposalId = readNonEmptyString(proposal.proposalId);
+    const configPath = readNonEmptyString(proposal.configPath);
+    if (!proposalId || !configPath)
+        return null;
+    const result = readObject(interaction.result);
+    const execution = readObject(result.secretProposal);
+    const executionStatus = readNonEmptyString(execution.status);
+    const errorCode = readNonEmptyString(execution.errorCode);
+    const sourceSecretLabel = readNonEmptyString(proposal.sourceSecretLabel);
+    if (interaction.status === "rejected") {
+        return {
+            proposalId,
+            configPath,
+            decision: "rejected",
+            executionStatus: "rejected",
+            instructions: "the secret binding proposal was rejected; do not assume the alias exists.",
+        };
+    }
+    if (interaction.status !== "accepted" || (executionStatus !== "executed" && executionStatus !== "failed")) {
+        return null;
+    }
+    if (executionStatus === "executed") {
+        return {
+            proposalId,
+            configPath,
+            decision: "accepted",
+            executionStatus,
+            ...(sourceSecretLabel ? { sourceSecretLabel } : {}),
+            instructions: `the binding was created at ${configPath}; verify it with GET /api/agents/me/secrets before using it.`,
+        };
+    }
+    return {
+        proposalId,
+        configPath,
+        decision: "accepted",
+        executionStatus,
+        ...(errorCode ? { errorCode } : {}),
+        instructions: "the binding was not created; inspect the failure comment and submit a fresh proposal after fixing the cause.",
+    };
+}
 const REQUEST_ITEM_VERDICTS_WAKE_COALESCE_WINDOW_MS = 2_000;
 function buildRequestItemVerdictsWakeIdempotencyKey(args) {
     const now = args.at ?? new Date();
@@ -1306,6 +1360,7 @@ async function queueResolvedInteractionContinuationWakeup(input) {
     const interactionResult = readConfirmationResultForWake(input.interaction.result);
     const checkboxSelection = readCheckboxSelectionForWake(input.interaction);
     const toolAction = readToolActionContinuationContext(input.interaction);
+    const secretProposal = readSecretProposalContinuationContext(input.interaction);
     const newlyResolvedItemIds = input.newlyResolvedItemIds?.filter((value) => value.length > 0) ?? [];
     const itemVerdicts = newlyResolvedItemIds.length > 0
         ? {
@@ -1337,6 +1392,7 @@ async function queueResolvedInteractionContinuationWakeup(input) {
             ...(planReviewInteraction ? { planReviewInteraction } : {}),
             ...(checkboxSelection ? { checkboxSelection } : {}),
             ...(toolAction ? { toolAction } : {}),
+            ...(secretProposal ? { secretProposal } : {}),
             ...(itemVerdicts ? { itemVerdicts, newlyResolvedItemIds } : {}),
             ...(reviewPathContext ?? {}),
             mutation: "interaction",
@@ -1355,6 +1411,7 @@ async function queueResolvedInteractionContinuationWakeup(input) {
             ...(planReviewInteraction ? { planReviewInteraction } : {}),
             ...(checkboxSelection ? { checkboxSelection } : {}),
             ...(toolAction ? { toolAction } : {}),
+            ...(secretProposal ? { secretProposal } : {}),
             ...(itemVerdicts ? { itemVerdicts, newlyResolvedItemIds } : {}),
             ...(reviewPathContext ?? {}),
             wakeReason: "issue_commented",
@@ -1835,6 +1892,7 @@ export function issueRoutes(db, storage, opts = {}) {
     const svc = issueService(db);
     const runRedactions = createRunSecretRedactionRegistry(db);
     const access = accessService(db);
+    const secretProposals = createSecretProposalsService(db);
     const heartbeat = heartbeatService(db, {
         pluginWorkerManager: opts.pluginWorkerManager,
     });
@@ -1857,6 +1915,7 @@ export function issueRoutes(db, storage, opts = {}) {
     const executionWorkspacesSvc = executionWorkspaceServiceDirect(db);
     const workProductsSvc = workProductService(db);
     const documentsSvc = documentService(db);
+    const artifactReviewDocumentsSvc = artifactReviewDocumentService(db, storage);
     const companySkillsSvc = companySkillService(db);
     const documentAnnotationsSvc = documentAnnotationService(db);
     const decisionTrainingSvc = decisionTrainingService(db);
@@ -2408,8 +2467,8 @@ export function issueRoutes(db, storage, opts = {}) {
                 && !(interaction.kind === "request_confirmation"
                     && interaction.payload
                     && typeof interaction.payload === "object"
-                    && "toolAction" in interaction.payload
-                    && interaction.payload.toolAction !== undefined));
+                    && (("toolAction" in interaction.payload && interaction.payload.toolAction !== undefined)
+                        || ("secretProposal" in interaction.payload && interaction.payload.secretProposal !== undefined))));
             if (!designatedReviewConfirmation) {
                 const creatorDescription = input.actorType === "agent"
                     ? "this agent run"
@@ -3066,7 +3125,8 @@ export function issueRoutes(db, storage, opts = {}) {
                 : { type: "user", userId: actor.actorId },
             interaction,
             additionalRestriction: resolverPolicyRestriction,
-            governedAction: interaction.kind === "request_confirmation" && payload?.toolAction !== undefined,
+            governedAction: interaction.kind === "request_confirmation"
+                && (payload?.toolAction !== undefined || payload?.secretProposal !== undefined),
         });
         if (!decision.allowed) {
             return denyIssueThreadInteractionResolution(res, {
@@ -3688,15 +3748,14 @@ export function issueRoutes(db, storage, opts = {}) {
         });
         return false;
     }
-    async function assertRecoveryActionAuthority(req, res, issue, activeRecoveryAction, input) {
+    async function requireRecoveryActionAuthority(req, issue, activeRecoveryAction, input) {
         if (req.actor.type !== "agent")
             return true;
         if (!activeRecoveryAction)
             return true;
         const actorAgentId = req.actor.agentId;
         if (!actorAgentId) {
-            res.status(403).json({ error: "Agent authentication required" });
-            return false;
+            throw forbidden("Agent authentication required");
         }
         if (issue.assigneeAgentId === actorAgentId)
             return true;
@@ -3710,19 +3769,123 @@ export function issueRoutes(db, storage, opts = {}) {
             await hasActiveCheckoutManagementOverride(actorAgentId, issue.companyId, activeRecoveryAction.ownerAgentId)) {
             return true;
         }
-        res.status(403).json({
-            error: "Agent cannot resolve another owner's recovery action",
-            details: {
+        throw forbidden("Agent cannot resolve another owner's recovery action", {
+            issueId: issue.id,
+            recoveryActionId: activeRecoveryAction.id,
+            actorAgentId,
+            assigneeAgentId: issue.assigneeAgentId,
+            recoveryOwnerAgentId: activeRecoveryAction.ownerAgentId,
+            source: input.source,
+            securityPrinciples: ["Least Privilege", "Complete Mediation", "Secure Defaults"],
+        });
+    }
+    function activeExecutionParticipantAgentId(issue) {
+        const state = parseIssueExecutionState(issue.executionState);
+        return state?.status === "pending" && state.currentParticipant?.type === "agent"
+            ? state.currentParticipant.agentId
+            : null;
+    }
+    async function requireRecoverySourceMutationAuthority(req, issue) {
+        if (req.actor.type !== "agent")
+            return;
+        const actorAgentId = req.actor.agentId;
+        if (!actorAgentId)
+            throw forbidden("Agent authentication required");
+        const isSourceOwner = issue.assigneeAgentId === actorAgentId;
+        const isExecutionParticipant = activeExecutionParticipantAgentId(issue) === actorAgentId;
+        const hasPolicyGrant = Boolean(issue.assigneeAgentId &&
+            await hasActiveCheckoutManagementOverride(actorAgentId, issue.companyId, issue.assigneeAgentId));
+        if (!isSourceOwner && !isExecutionParticipant && !hasPolicyGrant) {
+            throw forbidden("Recovery ownership does not authorize this source issue mutation", {
+                code: "recovery_source_authority_required",
                 issueId: issue.id,
-                recoveryActionId: activeRecoveryAction.id,
                 actorAgentId,
                 assigneeAgentId: issue.assigneeAgentId,
-                recoveryOwnerAgentId: activeRecoveryAction.ownerAgentId,
-                source: input.source,
+                currentExecutionParticipantAgentId: activeExecutionParticipantAgentId(issue),
+                remediation: "Have the source owner, current execution participant, board, or a policy-authorized agent perform the source mutation.",
                 securityPrinciples: ["Least Privilege", "Complete Mediation", "Secure Defaults"],
-            },
-        });
-        return false;
+            });
+        }
+        const actorRunId = req.actor.runId?.trim() || null;
+        const conflictingRunId = [issue.checkoutRunId, issue.executionRunId]
+            .find((runId) => runId && runId !== actorRunId);
+        if (conflictingRunId && !hasPolicyGrant) {
+            throw conflict("Source issue mutation is locked by another active checkout or run", {
+                code: "recovery_source_run_lock",
+                issueId: issue.id,
+                actorAgentId,
+                actorRunId,
+                checkoutRunId: issue.checkoutRunId ?? null,
+                executionRunId: issue.executionRunId ?? null,
+            });
+        }
+        if (isSourceOwner && issue.status === "in_progress" && !actorRunId && !hasPolicyGrant) {
+            throw unauthorized("Agent run id required");
+        }
+    }
+    async function assertSafeRecoveryHandBackGates(input) {
+        const returnOwnerAgentId = input.recoveryAction.returnOwnerAgentId;
+        if (!returnOwnerAgentId || input.issue.assigneeAgentId !== returnOwnerAgentId) {
+            throw forbidden("Safe recovery hand-back requires the recorded original owner to remain assigned", {
+                code: "recovery_safe_hand_back_owner_mismatch",
+                issueId: input.issue.id,
+                assigneeAgentId: input.issue.assigneeAgentId,
+                returnOwnerAgentId,
+            });
+        }
+        const actorRunId = input.req.actor.type === "agent"
+            ? input.req.actor.runId?.trim() || null
+            : null;
+        const conflictingRunId = [input.issue.checkoutRunId, input.issue.executionRunId]
+            .find((runId) => runId && runId !== actorRunId);
+        if (conflictingRunId) {
+            throw conflict("Safe recovery hand-back is locked by another active checkout or run", {
+                code: "recovery_source_run_lock",
+                issueId: input.issue.id,
+                actorRunId,
+                checkoutRunId: input.issue.checkoutRunId ?? null,
+                executionRunId: input.issue.executionRunId ?? null,
+            });
+        }
+        if (parseIssueExecutionState(input.issue.executionState)?.status === "pending") {
+            throw conflict("Safe recovery hand-back cannot bypass a pending execution review or approval stage", {
+                code: "recovery_governed_stage_pending",
+                issueId: input.issue.id,
+            });
+        }
+        const activePauseHold = await treeControlSvc.getActivePauseHoldGate(input.issue.companyId, input.issue.id);
+        if (activePauseHold) {
+            throw conflict("Safe recovery hand-back blocked by active subtree pause hold", {
+                issueId: input.issue.id,
+                holdId: activePauseHold.holdId,
+                rootIssueId: activePauseHold.rootIssueId,
+                mode: activePauseHold.mode,
+            });
+        }
+        if (input.issue.projectId) {
+            const project = await projectsSvc.getById(input.issue.projectId);
+            if (project?.pausedAt) {
+                throw conflict(project.pauseReason === "budget"
+                    ? "Project is paused because its budget hard-stop was reached"
+                    : "Project is paused");
+            }
+        }
+        const approvals = await issueApprovalsSvc.listApprovalsForIssue(input.issue.id);
+        if (approvals.some((approval) => ACTIVE_REVIEW_APPROVAL_STATUSES.has(String(approval.status)))) {
+            throw conflict("Safe recovery hand-back cannot bypass a pending governed approval", {
+                code: "recovery_governed_approval_pending",
+                issueId: input.issue.id,
+            });
+        }
+        const budgetBlock = await budgetService(db).getInvocationBlock(input.issue.companyId, returnOwnerAgentId, { issueId: input.issue.id, projectId: input.issue.projectId });
+        if (budgetBlock) {
+            throw conflict("Safe recovery hand-back is blocked by the source owner's budget or pause gate", {
+                code: "recovery_safe_hand_back_budget_blocked",
+                issueId: input.issue.id,
+                returnOwnerAgentId,
+                budgetBlock,
+            });
+        }
     }
     async function resolveActiveIssueRun(issue) {
         let runToInterrupt = issue.executionRunId ? await heartbeat.getRun(issue.executionRunId) : null;
@@ -5089,39 +5252,45 @@ export function issueRoutes(db, storage, opts = {}) {
         const existing = await getAccessibleResource(req, res, svc.getById(id), "Issue not found");
         if (!existing)
             return;
-        if (!(await assertAgentIssueMutationAllowed(req, res, existing)))
+        if (!(await assertIssueReadAllowed(req, res, existing)))
             return;
-        const activeRecoveryAction = await recoveryActionsSvc.getActiveForIssue(existing.companyId, existing.id);
-        if (!(await assertRecoveryActionAuthority(req, res, existing, activeRecoveryAction, { source: "recovery_action_resolution" }))) {
+        if (await assertLowTrustControlPlaneDenied(req, res, existing.companyId, existing))
             return;
+        if (req.actor.type === "agent") {
+            const boundaryDecision = await decideIssueAccess(req, existing, "issue:mutate");
+            if (!boundaryDecision.allowed) {
+                await denyIssueWrite(req, res, existing, issueWriteDenialCodeForDecision(boundaryDecision));
+                return;
+            }
+            if (!requireAgentRunId(req, res))
+                return;
+            if (!(await assertCrossIssueInfluenceWithinRunCap(req, res, existing, "update")))
+                return;
         }
         const { actionId, outcome, sourceIssueStatus, resolutionNote } = req.body;
         if (outcome === "false_positive" || outcome === "cancelled") {
             assertBoard(req);
         }
         const actor = getActorInfo(req);
-        const handBackAgentId = outcome === "restored" && sourceIssueStatus === "todo"
-            ? activeRecoveryAction?.returnOwnerAgentId ?? null
-            : null;
-        const recordedOutcome = handBackAgentId
-            ? "handed_back"
-            : outcome === "restored" && sourceIssueStatus === "done"
-                ? "owner_completed"
-                : outcome;
-        const updateFields = sourceIssueStatus ? { status: sourceIssueStatus } : {};
-        await assertInReviewReviewPath({
-            existing,
-            updateFields,
-            actorType: actor.actorType,
-            actorId: actor.actorId,
-            actorAgentId: actor.agentId,
-            actorRunId: actor.runId,
-        });
         const actionStatus = outcome === "cancelled" ? "cancelled" : "resolved";
         const postCommitActivityPublications = [];
         const result = await db.transaction(async (tx) => {
-            let issue = existing;
-            if (outcome === "blocked") {
+            const lockedIssue = await tx
+                .select()
+                .from(issueRows)
+                .where(and(eq(issueRows.companyId, existing.companyId), eq(issueRows.id, existing.id)))
+                .for("update")
+                .then((rows) => rows[0] ?? null);
+            if (!lockedIssue)
+                throw notFound("Issue not found");
+            const activeRecoveryAction = await recoveryActionsSvc.getActiveForIssue(lockedIssue.companyId, lockedIssue.id, tx);
+            if (!activeRecoveryAction || (actionId && activeRecoveryAction.id !== actionId)) {
+                throw notFound("Active recovery action not found");
+            }
+            await requireRecoveryActionAuthority(req, lockedIssue, activeRecoveryAction, { source: "recovery_action_resolution" });
+            let issue = lockedIssue;
+            const sourceStatusChanged = sourceIssueStatus !== lockedIssue.status;
+            if (outcome === "blocked" && sourceStatusChanged) {
                 const unresolvedBlockers = await tx
                     .select({ id: issueRows.id })
                     .from(issueRelations)
@@ -5132,10 +5301,78 @@ export function issueRoutes(db, storage, opts = {}) {
                     throw unprocessable("Blocked recovery resolution requires an unresolved first-class blocker on the source issue");
                 }
             }
-            if (sourceIssueStatus) {
+            if (sourceStatusChanged) {
+                const safeHandBack = outcome === "restored" &&
+                    sourceIssueStatus === "todo" &&
+                    activeRecoveryAction.returnOwnerAgentId != null &&
+                    lockedIssue.assigneeAgentId === activeRecoveryAction.returnOwnerAgentId;
+                if (safeHandBack) {
+                    await assertSafeRecoveryHandBackGates({
+                        req,
+                        issue: lockedIssue,
+                        recoveryAction: activeRecoveryAction,
+                    });
+                }
+                else {
+                    await requireRecoverySourceMutationAuthority(req, lockedIssue);
+                }
+                if (lockedIssue.status === "in_review" &&
+                    (sourceIssueStatus === "done" || sourceIssueStatus === "cancelled") &&
+                    lockedIssue.reviewPolicy != null &&
+                    lockedIssue.reviewPolicy !== "anyone") {
+                    await assertIssueReviewVerdictActorAllowed(tx, {
+                        issue: lockedIssue,
+                        actor: { type: actor.actorType, id: actor.actorId },
+                    });
+                }
+                const updateFields = { status: sourceIssueStatus };
+                if (!safeHandBack) {
+                    await assertInReviewReviewPath({
+                        existing: lockedIssue,
+                        updateFields,
+                        actorType: actor.actorType,
+                        actorId: actor.actorId,
+                        actorAgentId: actor.agentId,
+                        actorRunId: actor.runId,
+                    });
+                    const executionPolicy = normalizeIssueExecutionPolicy(lockedIssue.executionPolicy ?? null);
+                    const transition = applyIssueExecutionPolicyTransition({
+                        issue: lockedIssue,
+                        policy: executionPolicy,
+                        previousPolicy: executionPolicy,
+                        requestedStatus: sourceIssueStatus,
+                        requestedAssigneePatch: {},
+                        actor: {
+                            agentId: actor.agentId ?? null,
+                            userId: actor.actorType === "user" ? actor.actorId : null,
+                        },
+                        allowBoardOverride: req.actor.type === "board",
+                        commentBody: resolutionNote ?? null,
+                    });
+                    Object.assign(updateFields, transition.patch);
+                    if (transition.decision) {
+                        const decisionId = randomUUID();
+                        const nextExecutionState = updateFields.executionState;
+                        if (!nextExecutionState || typeof nextExecutionState !== "object") {
+                            throw new Error("Execution policy decision patch is missing executionState");
+                        }
+                        updateFields.executionState = { ...nextExecutionState, lastDecisionId: decisionId };
+                        await tx.insert(issueExecutionDecisions).values({
+                            id: decisionId,
+                            companyId: lockedIssue.companyId,
+                            issueId: lockedIssue.id,
+                            stageId: transition.decision.stageId,
+                            stageType: transition.decision.stageType,
+                            actorAgentId: actor.agentId ?? null,
+                            actorUserId: actor.actorType === "user" ? actor.actorId : null,
+                            outcome: transition.decision.outcome,
+                            body: transition.decision.body,
+                            createdByRunId: actor.runId ?? null,
+                        });
+                    }
+                }
                 const updatedIssue = await svc.update(id, {
-                    status: sourceIssueStatus,
-                    ...(handBackAgentId ? { assigneeAgentId: handBackAgentId } : {}),
+                    ...updateFields,
                     actorAgentId: actor.agentId ?? null,
                     actorUserId: actor.actorType === "user" ? actor.actorId : null,
                 }, tx, postCommitActivityPublications);
@@ -5143,10 +5380,17 @@ export function issueRoutes(db, storage, opts = {}) {
                     throw notFound("Issue not found");
                 issue = updatedIssue;
             }
+            const recordedOutcome = outcome === "restored" && issue.status === "todo" &&
+                activeRecoveryAction.returnOwnerAgentId != null &&
+                issue.assigneeAgentId === activeRecoveryAction.returnOwnerAgentId
+                ? "handed_back"
+                : outcome === "restored" && issue.status === "done"
+                    ? "owner_completed"
+                    : outcome;
             const recoveryAction = await recoveryActionsSvc.resolveActiveForIssue({
                 companyId: existing.companyId,
                 sourceIssueId: existing.id,
-                actionId: actionId ?? null,
+                actionId: activeRecoveryAction.id,
                 status: actionStatus,
                 outcome: recordedOutcome,
                 resolutionNote: resolutionNote ?? null,
@@ -5974,8 +6218,101 @@ export function issueRoutes(db, storage, opts = {}) {
             actor,
             workProductChanged: true,
         });
+        await materializeArtifactReviewDocumentBestEffort({ issue, workProduct: product, actor });
         res.status(201).json(product);
     });
+    async function ensureArtifactReviewDocumentForWorkProduct(input) {
+        const { issue, workProduct, actor } = input;
+        const result = await artifactReviewDocumentsSvc.ensureForWorkProduct({
+            issue: { id: issue.id, companyId: issue.companyId },
+            workProduct,
+        });
+        if (!result.revisionChanged)
+            return result;
+        const doc = result.document;
+        await issueReferencesSvc.syncDocument(doc.id);
+        await externalObjectsSvc.syncDocumentSafely(doc.id);
+        await logActivity(db, {
+            companyId: issue.companyId,
+            actorType: actor.actorType,
+            actorId: actor.actorId,
+            agentId: actor.agentId,
+            runId: actor.runId,
+            agentApiKeyId: actor.agentApiKeyId,
+            action: result.created ? "issue.document_created" : "issue.document_updated",
+            entityType: "issue",
+            entityId: issue.id,
+            details: {
+                key: doc.key,
+                documentId: doc.id,
+                title: doc.title,
+                format: doc.format,
+                revisionNumber: doc.latestRevisionNumber,
+                workProductId: workProduct.id,
+                artifactReviewDocument: true,
+            },
+        });
+        for (const remap of result.remappedAnnotations) {
+            await logActivity(db, {
+                companyId: issue.companyId,
+                actorType: actor.actorType,
+                actorId: actor.actorId,
+                agentId: actor.agentId,
+                runId: actor.runId,
+                agentApiKeyId: actor.agentApiKeyId,
+                action: "issue.document_annotation_remapped",
+                entityType: "issue",
+                entityId: issue.id,
+                details: {
+                    key: doc.key,
+                    documentId: doc.id,
+                    threadId: remap.thread.id,
+                    revisionNumber: doc.latestRevisionNumber,
+                    anchorState: remap.thread.anchorState,
+                    anchorConfidence: remap.thread.anchorConfidence,
+                    snapshotId: remap.snapshot.id,
+                },
+            });
+        }
+        await revalidateActiveSourceRecoveryAfterCommittedWrite({
+            issue,
+            trigger: "document",
+            actor,
+            documentChanged: true,
+        });
+        return result;
+    }
+    async function materializeArtifactReviewDocumentBestEffort(input) {
+        if (!isMarkdownArtifactWorkProduct(input.workProduct))
+            return;
+        try {
+            await ensureArtifactReviewDocumentForWorkProduct(input);
+        }
+        catch (error) {
+            // Work-product writes stay fail-open: raw open and download remain
+            // available, and the explicit review-document endpoint is the retry path.
+            logger.warn({ err: error, issueId: input.issue.id, workProductId: input.workProduct.id }, "markdown work product review-document materialization failed");
+        }
+    }
+    router.post("/issues/:id/work-products/:workProductId/review-document", async (req, res) => {
+        const id = req.params.id;
+        const workProductId = req.params.workProductId;
+        const issue = await getAccessibleResource(req, res, svc.getById(id), "Issue not found");
+        if (!issue)
+            return;
+        if (!(await assertAgentIssueMutationAllowed(req, res, issue)))
+            return;
+        if (!(await assertDeliverableMutationAllowedByRunContext(req, res, issue)))
+            return;
+        const workProduct = await workProductsSvc.getById(workProductId);
+        if (!workProduct || workProduct.issueId !== issue.id || workProduct.companyId !== issue.companyId) {
+            res.status(404).json({ error: "Work product not found" });
+            return;
+        }
+        const actor = getActorInfo(req);
+        const result = await ensureArtifactReviewDocumentForWorkProduct({ issue, workProduct, actor });
+        res.status(result.created ? 201 : 200).json(result.document);
+    });
     router.post("/issues/:id/low-trust/promotions", validate(promoteLowTrustOutputSchema), async (req, res) => {
         const id = req.params.id;
         const issue = await getAccessibleResource(req, res, svc.getById(id), "Issue not found");
@@ -6164,6 +6501,11 @@ export function issueRoutes(db, storage, opts = {}) {
             actor,
             workProductChanged: true,
         });
+        const reviewDocumentInputChanged = ["type", "provider", "metadata", "title", "createdByRunId"]
+            .some((key) => Object.prototype.hasOwnProperty.call(patch, key));
+        if (reviewDocumentInputChanged || sourceTrust) {
+            await materializeArtifactReviewDocumentBestEffort({ issue, workProduct: product, actor });
+        }
         res.json(product);
     });
     router.delete("/work-products/:id", async (req, res) => {
@@ -6434,7 +6776,7 @@ export function issueRoutes(db, storage, opts = {}) {
         });
         res.json({ ok: true });
     });
-    router.post("/companies/:companyId/issues", applyCreateIssueStatusDefault, validate(createIssueSchema), async (req, res) => {
+    router.post("/companies/:companyId/issues", applyCreateIssueStatusDefault, validateIssueMutationBody(createIssueSchema), async (req, res) => {
         const companyId = req.params.companyId;
         assertCompanyAccess(req, companyId);
         if (isSkillTestScopedActor(req)) {
@@ -6742,7 +7084,7 @@ export function issueRoutes(db, storage, opts = {}) {
             referencedIssueIdentifiers: referenceSummary.outbound.map((item) => item.issue.identifier ?? item.issue.id),
         });
     });
-    router.post("/issues/:id/children", applyCreateIssueStatusDefault, validate(createChildIssueSchema), async (req, res) => {
+    router.post("/issues/:id/children", applyCreateIssueStatusDefault, validateIssueMutationBody(createChildIssueSchema), async (req, res) => {
         const parentId = req.params.id;
         const parent = await getAccessibleResource(req, res, svc.getById(parentId), "Parent issue not found");
         if (!parent)
@@ -6916,7 +7258,7 @@ export function issueRoutes(db, storage, opts = {}) {
         const decompositions = await svc.listAcceptedPlanDecompositions(sourceIssue.id);
         res.json(decompositions);
     });
-    router.post("/issues/:id/accepted-plan-decompositions", validate(createAcceptedPlanDecompositionSchema), async (req, res) => {
+    router.post("/issues/:id/accepted-plan-decompositions", validateIssueMutationBody(createAcceptedPlanDecompositionSchema), async (req, res) => {
         const sourceIssueId = req.params.id;
         const sourceIssue = await getAccessibleResource(req, res, svc.getById(sourceIssueId), "Issue not found");
         if (!sourceIssue)
@@ -7251,7 +7593,7 @@ export function issueRoutes(db, storage, opts = {}) {
             wakeQueued,
         });
     });
-    router.patch("/issues/:id", validate(updateIssueRouteSchema), async (req, res) => {
+    router.patch("/issues/:id", validateIssueMutationBody(updateIssueRouteSchema), async (req, res) => {
         const id = req.params.id;
         const existing = await getAccessibleResource(req, res, svc.getById(id), "Issue not found");
         if (!existing)
@@ -7335,9 +7677,19 @@ export function issueRoutes(db, storage, opts = {}) {
         const activeRecoveryActionBeforeUpdate = recoveryRelevantSourceMutationRequested
             ? await recoveryActionsSvc.getActiveForIssue(existing.companyId, existing.id)
             : null;
-        if (recoveryRelevantSourceMutationRequested &&
-            !(await assertRecoveryActionAuthority(req, res, existing, activeRecoveryActionBeforeUpdate, { source: "issue_update" }))) {
-            return;
+        if (recoveryRelevantSourceMutationRequested) {
+            await requireRecoveryActionAuthority(req, existing, activeRecoveryActionBeforeUpdate, { source: "issue_update" });
+            const recoveryRestrictedSourceMutationRequested = activeRecoveryActionBeforeUpdate != null &&
+                (updateFields.status === "done" ||
+                    updateFields.status === "cancelled" ||
+                    normalizedAssigneeAgentId !== undefined ||
+                    req.body.assigneeUserId !== undefined ||
+                    (activeExecutionParticipantAgentId(existing) != null &&
+                        typeof updateFields.status === "string" &&
+                        updateFields.status !== existing.status));
+            if (recoveryRestrictedSourceMutationRequested) {
+                await requireRecoverySourceMutationAuthority(req, existing);
+            }
         }
         if (resumeRequested !== true &&
             agentStatusTransitionRequiresResumeAuthority &&
@@ -8259,14 +8611,17 @@ export function issueRoutes(db, storage, opts = {}) {
                 wakeups.set(`${agentId}:${wakeIssueId}`, { agentId, wakeup });
             };
             const addDependencyResolvedWakeup = async (input) => {
-                const idempotencyKey = buildIssueBlockersResolvedWakeIdempotencyKey({
+                const idempotencyKey = buildIssueBlockersResolvedWakeStateKey({
                     dependentIssueId: input.dependentIssueId,
-                    resolvedBlockerIssueId: input.resolvedBlockerIssueId,
+                    blockerIssueIds: input.blockerIssueIds,
+                    blockedTransitionAt: input.blockedTransitionAt,
                 });
                 try {
-                    const existingWake = await findExistingIssueBlockersResolvedWake(db, {
+                    const existingWake = await findExistingIssueBlockersResolvedWakeForReadyState(db, {
                         companyId: issue.companyId,
-                        idempotencyKey,
+                        dependentIssueId: input.dependentIssueId,
+                        blockerIssueIds: input.blockerIssueIds,
+                        blockedTransitionAt: input.blockedTransitionAt,
                     });
                     if (existingWake)
                         return;
@@ -8442,6 +8797,7 @@ export function issueRoutes(db, storage, opts = {}) {
                         dependentIssueId: dependent.id,
                         resolvedBlockerIssueId: issue.id,
                         blockerIssueIds: dependent.blockerIssueIds,
+                        blockedTransitionAt: dependent.blockedTransitionAt,
                         source: "issue.blockers_resolved",
                         mutation: "blocker_done",
                     });
@@ -8463,6 +8819,7 @@ export function issueRoutes(db, storage, opts = {}) {
                         dependentIssueId: issue.id,
                         resolvedBlockerIssueId,
                         blockerIssueIds: readiness.blockerIssueIds,
+                        blockedTransitionAt: issue.blockedTransitionAt,
                         source: "issue.blockers_restored",
                         mutation: "blocked_dependency_restored",
                     });
@@ -8882,6 +9239,9 @@ export function issueRoutes(db, storage, opts = {}) {
         if (req.body.kind === "request_confirmation" && req.body.payload?.toolAction !== undefined) {
             throw unprocessable("payload.toolAction is server-owned metadata and cannot be supplied when creating an interaction");
         }
+        if (req.body.kind === "request_confirmation" && req.body.payload?.secretProposal !== undefined) {
+            throw unprocessable("payload.secretProposal is server-owned metadata and cannot be supplied when creating an interaction");
+        }
         // Plan-document confirmation targets are validated authoritatively inside
         // issueThreadInteractionService.create, which re-reads the plan document's
         // latest revision and rejects a stale/missing target under the same insert
@@ -8987,6 +9347,9 @@ export function issueRoutes(db, storage, opts = {}) {
         const toolAction = interaction.payload && typeof interaction.payload === "object"
             ? interaction.payload.toolAction
             : null;
+        const secretProposal = interaction.payload && typeof interaction.payload === "object"
+            ? interaction.payload.secretProposal
+            : null;
         let continuationInteraction = interaction;
         if (interaction.kind === "request_confirmation"
             && interaction.status === "accepted"
@@ -9021,6 +9384,63 @@ export function issueRoutes(db, storage, opts = {}) {
                 };
             }
         }
+        if (interaction.kind === "request_confirmation"
+            && interaction.status === "accepted"
+            && typeof secretProposal?.proposalId === "string") {
+            const resolvedByUserId = actor.actorType === "user" ? actor.actorId : "board";
+            try {
+                if (opts.approveSecretProposal) {
+                    await opts.approveSecretProposal({
+                        companyId: issue.companyId,
+                        issueId: issue.id,
+                        interactionId: interaction.id,
+                        proposalId: secretProposal.proposalId,
+                        actor: { agentId: actor.agentId, userId: actor.actorType === "user" ? actor.actorId : null },
+                    });
+                }
+                else {
+                    const proposal = await secretProposals.getById(issue.companyId, secretProposal.proposalId);
+                    if (!proposal
+                        || proposal.kind !== "binding"
+                        || proposal.originIssueId !== issue.id
+                        || proposal.interactionId !== interaction.id) {
+                        throw notFound("Secret proposal not found");
+                    }
+                    await secretProposals.approve(issue.companyId, proposal.id, {
+                        resolvedByUserId,
+                        assertCanResolve: (lockedProposal, txDb) => assertCanResolveProposal({
+                            db: txDb,
+                            actor: req.actor,
+                            companyId: issue.companyId,
+                            proposal: lockedProposal,
+                        }),
+                    });
+                    await notifySecretProposalResolution({
+                        proposal,
+                        status: "approved",
+                        userId: resolvedByUserId,
+                        issues: svc,
+                        heartbeat,
+                    });
+                }
+                continuationInteraction = await interactionSvc.recordSecretProposalExecutionResult(issue, interaction.id, secretProposal.proposalId, { status: "executed" });
+            }
+            catch (error) {
+                const errorCode = secretProposalExecutionErrorCode(error);
+                continuationInteraction = await interactionSvc.recordSecretProposalExecutionResult(issue, interaction.id, secretProposal.proposalId, { status: "failed", errorCode });
+                const recordedResult = readObject(continuationInteraction.result);
+                const recordedSecretProposal = readObject(recordedResult.secretProposal);
+                if (recordedSecretProposal.status !== "executed") {
+                    const configPath = typeof secretProposal.configPath === "string" ? secretProposal.configPath : "unknown";
+                    try {
+                        await svc.addComment(issue.id, `Secret binding execution failed\n\n- Config path: \`${configPath}\`\n- Error code: \`${errorCode}\`\n- Binding created: **no**`, { userId: resolvedByUserId });
+                    }
+                    catch (commentError) {
+                        logger.warn({ err: commentError, issueId: issue.id, interactionId: interaction.id, errorCode }, "failed to post secret proposal execution failure comment");
+                    }
+                }
+            }
+        }
         const continuationWakeIssue = continuationIssue ?? issue;
         await logActivity(db, {
             companyId: issue.companyId,
@@ -10022,14 +10442,17 @@ export function issueRoutes(db, storage, opts = {}) {
                 wakeups.set(key, { agentId, wakeup });
             };
             const addDependencyResolvedWakeup = async (input) => {
-                const idempotencyKey = buildIssueBlockersResolvedWakeIdempotencyKey({
+                const idempotencyKey = buildIssueBlockersResolvedWakeStateKey({
                     dependentIssueId: input.dependentIssueId,
-                    resolvedBlockerIssueId: input.resolvedBlockerIssueId,
+                    blockerIssueIds: input.blockerIssueIds,
+                    blockedTransitionAt: input.blockedTransitionAt,
                 });
                 try {
-                    const existingWake = await findExistingIssueBlockersResolvedWake(db, {
+                    const existingWake = await findExistingIssueBlockersResolvedWakeForReadyState(db, {
                         companyId: currentIssue.companyId,
-                        idempotencyKey,
+                        dependentIssueId: input.dependentIssueId,
+                        blockerIssueIds: input.blockerIssueIds,
+                        blockedTransitionAt: input.blockedTransitionAt,
                     });
                     if (existingWake)
                         return;
@@ -10187,6 +10610,7 @@ export function issueRoutes(db, storage, opts = {}) {
                         dependentIssueId: dependent.id,
                         resolvedBlockerIssueId: currentIssue.id,
                         blockerIssueIds: dependent.blockerIssueIds,
+                        blockedTransitionAt: dependent.blockedTransitionAt,
                     });
                 }
             }
@@ -10484,7 +10908,13 @@ export function issueRoutes(db, storage, opts = {}) {
             objectContentType: object.contentType,
             originalFilename: attachment.originalFilename,
         });
-        res.setHeader("Content-Type", responseContentType);
+        // Markdown bodies are stored as UTF-8; declare the charset so inline
+        // (raw) views do not mojibake. SVG/inline checks below stay on the bare type.
+        const isMarkdownResponse = isMarkdownAttachmentContent({
+            contentType: responseContentType,
+            originalFilename: attachment.originalFilename,
+        });
+        res.setHeader("Content-Type", isMarkdownResponse ? `${responseContentType}; charset=utf-8` : responseContentType);
         res.setHeader("Cache-Control", "private, max-age=60");
         res.setHeader("X-Content-Type-Options", "nosniff");
         if (responseContentType === SVG_CONTENT_TYPE) {