@humwick/server 0.0.0-stage → 0.130.0

package/src/services/task-delivery.ts

@@ -0,0 +1,762 @@
+import {
+  getTaskDetail,
+  getWorkspace,
+  insertTaskEvent,
+  markTaskDeliverableEffectsCompleteAsync,
+  ownedIsolatedWorkspace,
+  recordGateAsync,
+  recordTaskDeliverableAsync,
+  recordTaskDeliverableWithLandingIngressAsync,
+  setTaskStage,
+  setTaskStatus,
+  setTaskStatusAsync,
+  transitionWorkspaceLandStateAsync,
+  workspaceLandAuthorization, workspaceLandAuthorizationWithdrawn,
+  ValidationError,
+  type CompleteDeliveryArmOutcome,
+} from "../db";
+import { refreshWorkspaceGitState } from "../workspace-probe";
+import { pinWorkspaceDeliveryTip } from "../workspace-delivery-tip";
+import { recoverIsolatedWorkspace, type WorkspaceRecoveryHint } from "./workspace-recovery";
+import { emitRelayEvent } from "../events";
+import { routeNotification } from "../notification-router";
+import { workflowStepForTask, workflowTaskDelivered } from "./workflow-runs";
+import { emitTaskChanged, emitNewMessages } from "../sse";
+import { agentBoundTaskIds, hasTaskReadAdminScope } from "../task-authz";
+import { applyWorkspaceAction } from "../workspace-actions";
+import { LAND_IN_FLIGHT_STATUSES, LAND_REQUEST_STALE_ON_HEAD_ADVANCE_STATUSES } from "../workspace-phase";
+import { findLatestCommandByCorrelation } from "../commands-db";
+import { mergeCommandNeedsRetry } from "../workspace-merge-progress";
+import { workspaceLandNeedsRearm } from "../workspace-land-retry";
+import { emitTaskSemanticNotification } from "./task-semantic-events";
+import { ServiceAuthError } from "./errors";
+import { resolveCoordinatorAgentId } from "../steward-identity";
+import { markAgentWorkFinal } from "./work-finality";
+import type { DiffGateDecision } from "./diff-gate";
+import { resolveDeliveryDiffDecision } from "../workspace-changed-paths-client";
+import { advanceHandedOffTask, completeVerdictOnlyTask } from "./task-delivery-close";
+import { completeTaskWithNothingToLand, zeroCommitProof } from "./task-nothing-to-land";
+import { dispatchReviewPublish, type ReviewPublishDispatch } from "./review-publish";
+import { reviewPublishEnabled } from "../config";
+import { completeGateProblem, requireWorkflowVerdict, gateWrites } from "./delivery-gate-policy";
+import { deliveryInlineSummary } from "./task-delivery-summary";
+import { deliveryEvent } from "./task-delivery-event";
+import { isDeliveredDoneWhen } from "./task-done-when";
+import { completeDeliveryLandDecision, RECORD_CLOSE_DISPATCH_TYPES } from "./task-delivery-land-policy";
+import { capturedDeliveryGateRefusal } from "./captured-delivery-gate";
+import { discoverWorkspaceLandingIdentityOnHost } from "./legacy-landing-host";
+import type { LandingLaneIdentity } from "../landing-lane-key";
+import type { AuthContext } from "./auth-context";
+import type { Command, TaskBlocker, TaskDeliverableEventMetadata, TaskDeliveryGateReports, TaskDeliveryResult, TaskDetail, WorkspaceRecord } from "../types";
+import { taskOwnerTarget } from "../task-owner";
+import { LAND_BLOCK_REJECT_MESSAGE, workspaceLandBlocked } from "../land-block";
+import { emitCommandEvent } from "../command-events";
+
+// The universal-minimum delivery gate (#1388, source of truth: `delivery-gate-policy.ts`). A
+// `complete` code delivery must self-report `REQUIRED_GATE` PASSING — nothing more. `typecheck` is
+// deliberately NOT required here: it binds the delivery contract to TS-only toolchains. A
+// project's `delivery` command (`.agent-relay/land-gates.json`) is what a worker RUNS to produce
+// this truthful `test: pass` (humwick's own dogfoods typecheck + affected tests + guards
+// behind it); the command is surfaced language-agnostically in onboarding (see
+// `composeDeliveryInstruction`), never read here. The authoritative full re-run still happens at
+// land via the `ci-land-full` gate, which catches a false self-report — so delivery stays cheap
+// and language-agnostic while land stays honest. Fallback is identical: with or without a
+// declared `delivery`, `test` is the minimum.
+
+export interface DeliverTaskInput extends TaskDeliveryResult {
+  taskId?: number;
+  workspaceId?: string;
+  idempotencyKey?: string;
+  // #1502 — the delivering worker's own workspace descriptor (from AGENT_RELAY_WORKSPACE_JSON), an
+  // UNTRUSTED hint used to self-heal a dropped/never-written registration so a `complete` land isn't
+  // rejected when the row simply hasn't been written yet. Every routing/land-policy field is
+  // reconstructed server-side (see recoverIsolatedWorkspace); only worktree/branch/base is read from
+  // here, and only after validation.
+  workspace?: WorkspaceRecoveryHint;
+  /** Explicitly proceed after reviewing a definitive stranded-cycle warning (#1697). */
+  allowStrandedBranches?: boolean;
+}
+
+function strandedDeliveryWarning(workspace: WorkspaceRecord): { branches: string[]; commits: number } | undefined {
+  const metadata = workspace.metadata as Record<string, unknown>;
+  if (metadata.gitAhead !== 0 || !Array.isArray(metadata.gitStrandedBranches)) return undefined;
+  const branches = metadata.gitStrandedBranches
+    .map((item) => item && typeof item === "object" && typeof (item as { branch?: unknown }).branch === "string"
+      ? (item as { branch: string }).branch
+      : undefined)
+    .filter((branch): branch is string => Boolean(branch));
+  const commits = typeof metadata.gitStrandedUnmergedCommits === "number" ? metadata.gitStrandedUnmergedCommits : 0;
+  return branches.length > 0 && commits > 0 ? { branches, commits } : undefined;
+}
+
+function taskIdFrom(value: unknown): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  const n = typeof value === "string" ? Number(value) : value;
+  if (typeof n !== "number" || !Number.isSafeInteger(n) || n < 1) throw new ValidationError("taskId must be a positive integer");
+  return n;
+}
+
+function resolveTaskId(ctx: AuthContext, explicit: unknown): number {
+  const taskId = taskIdFrom(explicit);
+  const caller = ctx.callerAgentId;
+  const bound = caller ? agentBoundTaskIds(caller) : new Set<number>();
+  const admin = hasTaskReadAdminScope(ctx.scopes);
+  if (taskId !== undefined) {
+    if (admin || bound.has(taskId)) return taskId;
+    throw new ServiceAuthError("taskId is not bound to the caller");
+  }
+  if (bound.size === 1) return [...bound][0]!;
+  if (bound.size === 0) throw new ServiceAuthError("caller is not bound to a Task");
+  throw new ValidationError("caller is bound to multiple Tasks; pass taskId explicitly");
+}
+
+function canRebindToWorkspace(ctx: AuthContext, task: TaskDetail, ws: WorkspaceRecord): boolean {
+  const caller = ctx.callerAgentId;
+  if (!caller || ws.ownerAgentId !== caller) return false;
+  return task.ownerAgentId === caller || agentBoundTaskIds(caller).has(task.id);
+}
+
+function shouldRebindToWorkspace(task: TaskDetail, ws: WorkspaceRecord | undefined): ws is WorkspaceRecord {
+  return Boolean(task.branch && ws?.branch && task.branch !== ws.branch);
+}
+
+function resolveWorkspace(ctx: AuthContext, input: Pick<DeliverTaskInput, "workspaceId" | "workspace" | "idempotencyKey">, taskId: number, opts: { allowRebind?: boolean } = {}): WorkspaceRecord | undefined {
+  const caller = ctx.callerAgentId;
+  const explicit = input.workspaceId?.trim();
+  let ws = explicit ? getWorkspace(explicit) : caller ? ownedIsolatedWorkspace(caller) : undefined;
+  if (!ws && input.idempotencyKey) {
+    const priorWorkspaceId = deliveryEvent(taskId, input.idempotencyKey)?.metadata.workspaceId;
+    if (priorWorkspaceId) ws = getWorkspace(priorWorkspaceId) ?? undefined;
+  }
+  // #1502 — the row can be missing for a live worker whose registration was dropped/never written
+  // under concurrent-spawn load. Recover it from the worker's own descriptor, but ONLY through the
+  // server-authoritative recovery (signed spawn-request association + immutable agent.spawn params +
+  // orchestrator baseDir containment); the descriptor is an untrusted hint, never trusted verbatim.
+  if (!ws && input.workspace) {
+    const recovery = recoverIsolatedWorkspace(ctx, input.workspace, explicit);
+    if (recovery.ok) ws = recovery.workspace;
+  }
+  if (!ws) return undefined;
+  if (!hasTaskReadAdminScope(ctx.scopes) && (!caller || ws.ownerAgentId !== caller)) {
+    throw new ServiceAuthError(`workspace ${ws.id} is not owned by the caller`);
+  }
+  const task = getTaskDetail(taskId);
+  if (!task) throw new ValidationError("task not found");
+  if (task.branch && ws.branch && task.branch !== ws.branch) {
+    if (opts.allowRebind && canRebindToWorkspace(ctx, task, ws)) return ws;
+    throw new ValidationError(`task ${taskId} is bound to branch ${task.branch}, not workspace branch ${ws.branch}`);
+  }
+  return ws;
+}
+
+function rebindTaskToWorkspaceIfNeeded(task: TaskDetail, ws: WorkspaceRecord | undefined, actor: string): TaskDetail {
+  if (!shouldRebindToWorkspace(task, ws)) return task;
+  setTaskStatus(task.id, {
+    status: "in_progress",
+    note: `fix-forward rebind to workspace ${ws.id} (${ws.branch})`,
+    actor,
+  });
+  return setTaskStage(task.id, {
+    deliverableStage: "committed-on-branch",
+    branch: ws.branch,
+    actor,
+  });
+}
+
+function cleanReason(value: unknown, disposition: "blocked" | "failed"): string {
+  if (typeof value !== "string" || !value.trim()) throw new ValidationError(`${disposition} delivery requires reason`);
+  const cleaned = value.trim();
+  if (cleaned.length > 64_000) throw new ValidationError("reason must be 64000 characters or fewer");
+  return cleaned;
+}
+
+function cleanBlockedBy(value: unknown): TaskBlocker[] {
+  if (!Array.isArray(value) || value.length === 0) throw new ValidationError("blocked delivery requires blockedBy");
+  return value as TaskBlocker[];
+}
+
+function skippedRequiredGateReports(reason: string): Required<Pick<TaskDeliveryGateReports, "typecheck" | "test">> {
+  return {
+    typecheck: { status: "skipped", detail: reason },
+    test: { status: "skipped", detail: reason },
+  };
+}
+
+// #1713 — a `complete` delivery that triggers a LAND has NOT landed yet; the merge is async and may
+// stall. So the coordinator-facing wording must say "submitted for landing — awaiting merge" and must
+// NOT contain "complete"/"landed" — the actual land is announced separately, only once a git ancestry
+// check confirms the sha reached the target ref (see landed-ancestry.ts / notifyBranchLanded).
+// Non-landing dispositions (blocked/failed/needs-review, and a verdict-only complete that closes on
+// delivery with no land) keep their honest existing wording. #2518 adds the third shape: a complete
+// delivery ACCEPTED but HELD for coordinator review — it says exactly that and never claims landing.
+function notifyDelivery(taskId: number, eventId: number, metadata: TaskDeliverableEventMetadata, landing: boolean): void {
+  const task = getTaskDetail(taskId);
+  if (!task) return;
+  const linkedIssues = task.issues.map((issue) => ({ provider: issue.provider, repo: issue.repo, externalKey: issue.externalKey, title: issue.title, status: issue.status }));
+  const coordinator = resolveCoordinatorAgentId(task.ownerAgentId ?? metadata.actor);
+  // #2518 — the held-review wording block. `land.requested=false, reason:"review-hold"` is the
+  // durable shape the arm seam stamps; surface the pinned HEAD so the reviewer/coordinator clears
+  // against exactly what was reviewed.
+  const heldHead = metadata.land?.requested === false && metadata.land.reason === "review-hold" && typeof metadata.land.sourceHeadSha === "string"
+    ? metadata.land.sourceHeadSha
+    : undefined;
+  const blockedArm = metadata.land?.requested === false && metadata.land.reason === "workspace-land-blocked";
+  // fromAgentId/toAgentId (#1544 T1387) — the worker↔coordinator identity pair, so
+  // Cosmos can route a distinct "final report" arc from the deliverer back to its
+  // coordinator sun without a round-trip lookup. The SSE fanout (sse.ts) forwards
+  // only `data`, never the RelayEvent's own `source`, so this must ride in `data`.
+  emitRelayEvent({
+    type: "task.deliverable",
+    source: metadata.actor,
+    subject: String(taskId),
+    data: {
+      taskId,
+      eventId,
+      disposition: metadata.disposition,
+      summary: metadata.summary,
+      workspaceId: metadata.workspaceId,
+      linkedIssues,
+      fromAgentId: metadata.actor,
+      ...(coordinator ? { toAgentId: coordinator } : {}),
+    },
+  });
+  const recipients = [...new Set([coordinator, taskOwnerTarget(task)].filter((item): item is string => Boolean(item && item.trim())))];
+  // #2258 — a record-close that left commits on the branch says so in the body too. The coordinator
+  // reading "delivery: complete" is the one who otherwise assumes the work reached main.
+  const unmergedAhead = metadata.land?.requested === false ? metadata.land.unmergedAhead ?? 0 : 0;
+  const notArmedWarning = metadata.landNotArmedReason && unmergedAhead > 0
+    ? `\n⚠ NOT landed: ${unmergedAhead} unmerged commit(s) remain on ${metadata.workspaceId ?? "the workspace"} (no land armed — ${metadata.landNotArmedReason}). Land it explicitly if this work belongs on main.`
+    : "";
+  const delivered = routeNotification({
+    type: "task.deliverable",
+    scope: {
+      taskId: String(taskId),
+      transition: "deliverable",
+      ...(task.ownerAgentId ? { agentId: task.ownerAgentId, author: task.ownerAgentId } : {}),
+      ...(task.createdBy ? { parent: task.createdBy } : {}),
+      ...(task.teamId ? { teamId: task.teamId } : {}),
+      ...(metadata.workspaceId ? { workspaceId: metadata.workspaceId } : {}),
+    },
+    recipients,
+    ttlMs: null,
+    message: {
+      subject: landing
+        ? `Task T${taskId} submitted for landing`
+        : heldHead
+          ? `Task T${taskId} delivery held for review at ${heldHead}`
+          : `Task T${taskId} delivery: ${metadata.disposition}`,
+      body: landing
+        ? `Task T${taskId} submitted for landing — awaiting merge: ${metadata.summary}${linkedIssues.length ? `\nLinked issues: ${linkedIssues.map((issue) => `${issue.repo}#${issue.externalKey}`).join(", ")}` : ""}\nNot yet on main — a separate on-main confirmation follows once the merge is verified against the target ref.`
+        : heldHead
+          ? `Task T${taskId} delivery accepted; held for review at ${heldHead}: ${metadata.summary}${linkedIssues.length ? `\nLinked issues: ${linkedIssues.map((issue) => `${issue.repo}#${issue.externalKey}`).join(", ")}` : ""}\nA coordinator must clear the review hold (against this exact HEAD) before this delivery lands. Nothing merged.`
+          : blockedArm
+            ? `Task T${taskId} delivery accepted: committed on branch ${metadata.land?.sourceRef ?? getWorkspace(metadata.workspaceId ?? "")?.branch ?? "unknown"}; not landed: ${LAND_BLOCK_REJECT_MESSAGE}. ${metadata.summary}`
+            : `Task T${taskId} delivery (${metadata.disposition}): ${metadata.summary}${linkedIssues.length ? `\nLinked issues: ${linkedIssues.map((issue) => `${issue.repo}#${issue.externalKey}`).join(", ")}` : ""}${notArmedWarning}`,
+      payload: {
+        kind: "task.deliverable",
+        notification: "task-deliverable",
+        taskId,
+        eventId,
+        disposition: metadata.disposition,
+        summary: metadata.summary,
+        gates: metadata.gates,
+        risks: metadata.risks,
+        workspaceId: metadata.workspaceId,
+        linkedIssues,
+        ...deliveryInlineSummary(metadata, { landing, heldHead, blockedArm }),
+      },
+      idempotencyKey: metadata.idempotencyKey ? `task:${taskId}:deliverable:${metadata.idempotencyKey}` : `task:${taskId}:deliverable:event:${eventId}`,
+      replyExpected: false,
+      // #2007 — "submitted for landing" is non-actionable noise: the coordinator does nothing
+      // with it, and both terminal land outcomes ("Merged to main" / "Landing failed", emitted
+      // separately from branch-landed.ts) still wake it normally. Keep it dashboard/thread
+      // visible but don't push it into a live coordinator turn.
+      ...(landing ? { wake: false } : {}),
+    },
+  });
+  if (delivered.length > 0) emitNewMessages(delivered);
+}
+
+function emitCommand(command: Command): void {
+  emitCommandEvent(command, command.status === "pending" ? "command.requested" : `command.${command.status}`);
+}
+
+function stableLandingRequestKey(value: string | undefined): string {
+  const key = value?.trim();
+  if (!key) throw new ValidationError("complete landing delivery requires a nonempty stable idempotencyKey");
+  return key;
+}
+
+export async function deliverTask(input: DeliverTaskInput, ctx: AuthContext): Promise<Record<string, unknown>> {
+  const actor = ctx.callerAgentId ?? ctx.actor.id;
+  const taskId = resolveTaskId(ctx, input.taskId);
+  const before = getTaskDetail(taskId);
+  if (!before || before.kind !== "deliverable") throw new ValidationError("task not found");
+  const recorded = input.idempotencyKey ? deliveryEvent(taskId, input.idempotencyKey) : undefined;
+  const recordedLand = recorded?.metadata.land;
+  const replayLand = recordedLand?.sourceHeadProvenance === "host-probe" && recordedLand.sourceRef && recordedLand.sourceHeadSha && recordedLand.frozenIntent
+    ? recordedLand : undefined;
+  if (recorded) input = { ...input, ...recorded.metadata, taskId, workspaceId: recorded.metadata.workspaceId, idempotencyKey: input.idempotencyKey };
+  const workflowStep = await workflowStepForTask(taskId);
+  if (input.disposition === "complete") requireWorkflowVerdict(input.gates, workflowStep?.verdictGate);
+  // #2258 — the workspace is resolved BEFORE the land decision, because the decision is now
+  // workspace-aware (an `ops` task with a branch lands; without one it record-closes). `allowRebind`
+  // can therefore no longer key off `wantsLand` — it keys off the disposition, the owner-authorized
+  // SUPERSET of the old condition: every delivery that previously allowed a rebind still does, and
+  // the newly-included non-landing `complete` deliveries still pass through the unchanged
+  // `canRebindToWorkspace` ownership check (caller owns the workspace AND owns/is bound to the
+  // Task). The authz boundary is identical; only the branch-mismatch outcome for a non-landing
+  // `complete` changes, from a hard reject to the same owner-authorized resolve the land path had.
+  // The TASK-record rebind itself (rebindTaskToWorkspaceIfNeeded) is still gated on `wantsLand`.
+  let workspace = input.disposition === "complete" || input.workspaceId
+    ? resolveWorkspace(ctx, input, taskId, { allowRebind: input.disposition === "complete" })
+    : undefined;
+  // A workspace that could actually carry a land: isolated, live on disk, and on a branch. Mirrors
+  // the preconditions enforced below (:live isolated workspace / :exact resolved source ref), so a
+  // dispatch type that lands "when it has a branch" can never be routed into one of those throws.
+  const hasIsolatedWorkspace = Boolean(workspace && workspace.mode === "isolated" && workspace.worktreePath && workspace.branch);
+  const canRecordCloseWithoutWork = RECORD_CLOSE_DISPATCH_TYPES.has(before.dispatch?.type ?? "");
+  let landDecision = input.disposition === "complete"
+    ? completeDeliveryLandDecision(before, { hasIsolatedWorkspace })
+    : undefined;
+  let wantsLand = Boolean(replayLand) || landDecision?.lands === true;
+  // #1452 — a REVIEW-ONLY hand-off (any disposition that does NOT land: needs-review, blocked,
+  // failed, or a review-only complete) is exactly when a fresh reviewer needs the unlanded tip
+  // on origin. Resolve the delivering agent's isolated workspace and publish its tip to
+  // refs/review/*. Gated entirely by `reviewPublishEnabled()`: with the feature OFF this is
+  // undefined and NOTHING downstream fires — deliverTask is a strict no-op. `wantsLand`
+  // deliveries are skipped: they auto-merge to main, so no review ref is needed.
+  // #2535 — the delivery diff gate probes the workspace's OWNING orchestrator, never this
+  // server's filesystem: the worktree lives on the owning host, a remote workspace has no
+  // path here ("worktree unavailable" used to force gates on legitimate no-diff deliveries),
+  // and a same-path different-host collision must classify the OWNING repo, not a local
+  // impostor. Fail-closed on any unavailable probe; classification stays in the common
+  // Relay policy (decideDiffGate). The evidence records the HEAD it was computed against so
+  // the land path can pin it to admission (re-derived below when they disagree).
+  // #3045 — a workflow step's own Task lands nothing: its declared gate is the verdict, never a block.
+  // Only complete deliveries reach these closures.
+  const verdictGate = !wantsLand ? workflowStep?.verdictGate : undefined;
+  const skippedGatesReason = (decision: Pick<DiffGateDecision, "requireGates" | "reason"> | undefined) =>
+    verdictGate ? `workflow verdict step (${verdictGate}): nothing lands` : decision?.requireGates === false ? decision.reason : undefined;
+  const effectiveGatesFor = (decision: Pick<DiffGateDecision, "requireGates" | "reason"> | undefined, skipped = skippedGatesReason(decision)) =>
+    skipped ? { ...skippedRequiredGateReports(skipped), ...(input.gates ?? {}) } : input.gates;
+  const gateProblemFor = (decision: Pick<DiffGateDecision, "requireGates" | "reason"> | undefined) =>
+    input.disposition === "complete"
+      ? completeGateProblem(effectiveGatesFor(decision), { allowSkippedRequired: skippedGatesReason(decision) !== undefined, verdictGate })
+      : undefined;
+  let diffEvidence = input.disposition === "complete" && workspace && !recorded
+    ? await resolveDeliveryDiffDecision(workspace)
+    : undefined;
+  let diffDecision: Pick<DiffGateDecision, "requireGates" | "reason"> | undefined;
+  let effectiveGates = input.gates;
+  if (input.disposition === "complete") {
+    diffDecision = recorded?.metadata.diffGate ?? diffEvidence?.decision ?? { requireGates: true, reason: "workspace unavailable" };
+    // #1418: when the diff-gate classifier skips the required gate (docs-only/empty diff), fill in
+    // the "skipped" default ONLY for gate slots the caller didn't self-report. A caller-supplied
+    // `typecheck`/`test` verdict (e.g. a real `test: pass` the worker actually ran) must win over
+    // the default — spreading the skip block second used to clobber it unconditionally, silently
+    // discarding a genuine self-report the instant the classifier decided gates were optional.
+    effectiveGates = effectiveGatesFor(diffDecision);
+    // #2535 — the diff decision's reason rides along in the rejection so "unavailable host" is
+    // distinguishable from "real code diff present".
+    const gateProblem = gateProblemFor(diffDecision);
+    if (gateProblem) throw new ValidationError(`complete delivery cannot land without passing gate block (${gateProblem}); diff: ${diffDecision.reason}`);
+  }
+  const reason = input.disposition === "blocked" || input.disposition === "failed" ? cleanReason(input.reason, input.disposition) : undefined;
+  const blockedBy = input.disposition === "blocked" ? cleanBlockedBy(input.blockedBy) : input.blockedBy;
+  if (wantsLand && (!workspace || workspace.mode !== "isolated" || !workspace.worktreePath)) {
+    throw new ValidationError("complete delivery requires a live isolated workspace");
+  }
+  let sourceProbe = input.disposition === "complete" && hasIsolatedWorkspace && workspace && !replayLand
+    ? await refreshWorkspaceGitState(workspace, { requireRemoteBase: true, ensurePushed: wantsLand && !canRecordCloseWithoutWork, allowUnavailable: !wantsLand || canRecordCloseWithoutWork && workspace.metadata.gitAhead === 0 && !strandedDeliveryWarning(workspace) })
+    : undefined;
+  // Replays skip host probes and retain the committed no-op proof (#2757/#2759).
+  let noWork: ReturnType<typeof zeroCommitProof> = replayLand?.reason === "nothing-to-land" && replayLand.sourceHeadSha
+    ? { head: replayLand.sourceHeadSha, onBaseSha: replayLand.sourceHeadSha } : undefined;
+  const classifyWork = () => {
+    if (!sourceProbe || !workspace) return;
+    if (sourceProbe.probed) workspace = getWorkspace(workspace.id) ?? workspace;
+    landDecision = completeDeliveryLandDecision(before, {
+      hasIsolatedWorkspace, hasUnmergedCommits: (sourceProbe.probed ? sourceProbe.unmergedAhead : sourceProbe.unavailable ? workspace.metadata.gitAhead : undefined) === 0 && !strandedDeliveryWarning(workspace) ? false : undefined,
+    });
+    wantsLand = landDecision.lands;
+    noWork = sourceProbe.probed ? zeroCommitProof(sourceProbe) : undefined;
+  };
+  classifyWork();
+  if (sourceProbe?.probed && workspace && (wantsLand || noWork) && sourceProbe.pushed !== true) {
+    sourceProbe = await refreshWorkspaceGitState(workspace, { ensurePushed: true, requireRemoteBase: true });
+    classifyWork();
+  }
+  if (workspace && input.disposition === "complete") {
+    const stranded = strandedDeliveryWarning(workspace);
+    if (stranded && !input.allowStrandedBranches) {
+      throw new ValidationError(`delivery refused: tracked branch ${workspace.branch ?? workspace.id} is zero-ahead while ${stranded.commits} unmerged commit(s) remain on ${stranded.branches.join(", ")}. Review or intentionally supersede those refs, then retry relay_task_deliver with allowStrandedBranches: true to proceed.`);
+    }
+  }
+  if (noWork) wantsLand = true;
+  const landingRequestKey = wantsLand ? noWork && !input.idempotencyKey ? crypto.randomUUID() : stableLandingRequestKey(input.idempotencyKey) : "";
+  const isVerdictOnlyComplete = input.disposition === "complete" && !wantsLand;
+  let resolvedSourceHeadSha: string | undefined = replayLand?.sourceHeadSha;
+  let landingIdentity: LandingLaneIdentity | undefined;
+  if (wantsLand && workspace && sourceProbe) {
+    // A held delivery still freezes `sourceHeadSha` for a reviewer. Do this before the
+    // deliverable event is written so a locally-created but unpushed HEAD can never become a
+    // durable review/landing pin. The owning host either proves origin already names this exact
+    // HEAD or pushes and re-verifies it; a confirmed failure is actionable to the worker.
+    resolvedSourceHeadSha = sourceProbe.headSha;
+    if (!sourceProbe.probed || !resolvedSourceHeadSha) {
+      throw new ValidationError(`complete delivery requires the owning host to resolve the exact current source HEAD${sourceProbe.skipped ? ` (${sourceProbe.skipped})` : ""}`);
+    }
+    if (!noWork && sourceProbe.pushed !== true) {
+      throw new ValidationError(`complete delivery requires source HEAD ${resolvedSourceHeadSha} to be fetchable from origin; auto-push failed${sourceProbe.pushError ? ` (${sourceProbe.pushError})` : ""}. Push the branch to origin and retry.`);
+    }
+    if (diffEvidence && diffEvidence.headSha !== resolvedSourceHeadSha) {
+      // #2535 — the diff evidence must describe the exact source HEAD admission pins. HEAD moved
+      // between the diff probe and the admission probe (concurrent work on the branch): re-probe
+      // ONCE pinned to the admission HEAD (the client fails the decision closed when the host
+      // still disagrees), then re-run the gate check against the fresh verdict.
+      diffEvidence = await resolveDeliveryDiffDecision(workspace, { pinnedHeadSha: resolvedSourceHeadSha });
+      diffDecision = diffEvidence.decision;
+      effectiveGates = effectiveGatesFor(diffDecision);
+      const regate = gateProblemFor(diffDecision);
+      if (regate) throw new ValidationError(`complete delivery cannot land without passing gate block (${regate}); diff: ${diffDecision?.reason ?? "workspace unavailable"}`);
+    }
+    workspace = getWorkspace(workspace.id) ?? workspace;
+    // Validated new admission normalizes the legacy default before it becomes
+    // historical. Backfill paths require an already-durable base ref.
+    const discovered = await discoverWorkspaceLandingIdentityOnHost(workspace, workspace.baseRef ?? "main");
+    if (!noWork) {
+      const deliveryRefusal = await capturedDeliveryGateRefusal({ ...discovered, sourceHeadSha: resolvedSourceHeadSha });
+      if (deliveryRefusal) throw new ValidationError(deliveryRefusal);
+    }
+    landingIdentity = discovered;
+    if (!deliveryEvent(taskId, input.idempotencyKey)) await pinWorkspaceDeliveryTip(workspace, resolvedSourceHeadSha, actor);
+  }
+  // #2258 LOUD FAILURE — a `complete` delivery that does NOT arm a land while its isolated
+  // workspace still holds unmerged commits used to return an unqualified success: the Task
+  // record-closed, the row stayed `active` outside the land lane, and NOTHING said the branch was
+  // being left behind (the stall watchdogs key off `ready_at`, which such a row never reaches, so
+  // they cannot see it either). Report it explicitly instead — on the result AND stamped durably on
+  // the deliverable event. The ahead count is re-probed on the owning host so the signal reflects
+  // reality rather than possibly-stale persisted counts; the probe is best-effort and falls back to
+  // the persisted count, so this can only ever add a warning, never fail a delivery.
+  //
+  // The diagnostic probe is normally gated on the persisted ahead count being non-zero (#2259). It is
+  // NOT side-effect-free: a transient host-preview failure stamps `lifecycleError`, which
+  // `stateForStatus` (db/workspaces.ts) then reads as a STICKY `probe-error` landState — nothing
+  // clears it. Also check a blocked workspace with reported commits when the host could not prove
+  // their status; that uncertainty must not close the Task as done.
+  let landNotArmed: { reason: string; unmergedAhead: number } | undefined;
+  const persistedAhead = typeof workspace?.metadata.gitAhead === "number" ? workspace.metadata.gitAhead : 0;
+  const unverifiedBlockedCommits = workspaceLandBlocked(workspace) && !sourceProbe?.probed ? input.commits?.length ?? 0 : 0;
+  if (!recorded && landDecision?.lands === false && workspace && workspace.mode === "isolated" && workspace.worktreePath && (persistedAhead > 0 || unverifiedBlockedCommits > 0)) {
+    let ahead = persistedAhead || unverifiedBlockedCommits;
+    try {
+      const probe = sourceProbe?.probed ? sourceProbe : await refreshWorkspaceGitState(workspace);
+      if (probe.probed) ahead = probe.unmergedAhead ?? ahead;
+    } catch {
+      // Diagnostic only — a probe failure must never break the delivery it is describing.
+    }
+    if (ahead > 0) landNotArmed = { reason: workspaceLandBlocked(workspace) ? "workspace-land-blocked" : landDecision.reason, unmergedAhead: ahead };
+  }
+  const currentTask = wantsLand && !noWork ? rebindTaskToWorkspaceIfNeeded(before, workspace, actor) : before;
+  const sourceRef = wantsLand ? replayLand?.sourceRef ?? workspace?.branch?.trim() : undefined;
+  // Only the HEAD returned by THIS host probe can authorize ingress. Persisted metadata may be
+  // stale, and the caller's commit list is a self-report; neither is authority for a mutable ref.
+  const sourceHeadSha = wantsLand ? resolvedSourceHeadSha : undefined;
+  if (wantsLand && (!sourceRef || !sourceHeadSha)) {
+    throw new ValidationError("complete delivery requires an exact resolved source ref and HEAD");
+  }
+  const frozenIntent = replayLand?.frozenIntent ?? (wantsLand && workspace && sourceRef && sourceHeadSha && landingIdentity
+    ? {
+        repoRoot: landingIdentity.repoRoot,
+        remoteIdentity: landingIdentity.remoteIdentity,
+        baseRef: landingIdentity.baseRef,
+        identityProvenance: "host-git" as const,
+        strategy: typeof workspace.metadata.landStrategy === "string" ? workspace.metadata.landStrategy : "rebase-ff",
+        gateSnapshot: effectiveGates ?? {},
+        requester: { actor, ...(ctx.callerAgentId ? { agentId: ctx.callerAgentId } : {}) },
+      }
+    : undefined);
+  const landMeta: TaskDeliverableEventMetadata["land"] | undefined = wantsLand && workspace
+    ? {
+        requested: true,
+        triggered: false,
+        reason: "pending",
+        workspaceId: workspace.id,
+        workspaceStatus: workspace.status,
+        sourceRef,
+        sourceHeadSha,
+        sourceHeadProvenance: "host-probe",
+        frozenIntent,
+      }
+    // #2258 — the record-close-with-unmerged-commits shape. `requested: false` keeps it out of every
+    // land-authorization read (they all key on `land.requested === true`); it exists purely to make
+    // the unlanded branch legible where the silence used to be.
+    : landNotArmed && workspace
+      ? {
+          requested: false,
+          triggered: false,
+          reason: landNotArmed.reason,
+          workspaceId: workspace.id,
+          workspaceStatus: workspace.status,
+          sourceRef: workspace.branch,
+          unmergedAhead: landNotArmed.unmergedAhead,
+        }
+      : undefined;
+  // #1452 round-4 (H2) — dispatch the REVIEW-ONLY publish BEFORE recording the deliverable, so the
+  // durable publish command row AND its ledger entry exist first: a crash after this can never leave
+  // a "requested" deliverable pointing at a command that was never created. The deliverable then
+  // carries only that command id — NO ref — so a reviewer resolves the actual ref from the command's
+  // TERMINAL success, never from an un-settled "requested" event. Skipped for a known idempotent
+  // replay so a duplicate delivery does not re-publish. `reviewWorkspace` is already undefined unless
+  // the feature is enabled and this is a non-landing delivery.
+  const reviewWorkspace = reviewPublishEnabled() && !wantsLand
+    ? workspace ?? (ctx.callerAgentId ? ownedIsolatedWorkspace(ctx.callerAgentId) : undefined)
+    : undefined;
+  const reviewDuplicate = input.idempotencyKey ? Boolean(deliveryEvent(taskId, input.idempotencyKey)) : false;
+  let reviewPublish: ReviewPublishDispatch | undefined;
+  if (reviewWorkspace && !reviewDuplicate) {
+    // Pin the delivered tip captured at delivery; the host publishes it ONLY if reachable from the
+    // verified workspace tip, else REFUSES (H1 — fail closed), so no unrelated local commit rides in.
+    const deliveredSha = input.commits?.length ? input.commits[input.commits.length - 1]?.sha : undefined;
+    reviewPublish = dispatchReviewPublish(reviewWorkspace, { requestedBy: actor, taskId, sha: deliveredSha, emit: emitCommand });
+  }
+  const deliveryInput = {
+      ...input,
+      ...(effectiveGates ? { gates: effectiveGates } : {}),
+      actor,
+      ...(reason ? { reason } : {}),
+      ...(blockedBy ? { blockedBy } : {}),
+      ...(workspace ? { workspaceId: workspace.id } : {}),
+      ...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
+      ...(landMeta ? { land: landMeta } : {}),
+      ...(landNotArmed ? { landNotArmedReason: landNotArmed.reason } : {}),
+      // #2535 — durable, auditable record of the authoritative diff decision: what the owning
+      // host reported (requireGates/reason) and the HEAD it was computed against.
+      ...(diffDecision
+        ? { diffGate: { requireGates: diffDecision.requireGates, reason: diffDecision.reason, ...(diffEvidence?.headSha ? { headSha: diffEvidence.headSha } : {}) } }
+        : {}),
+      ...(reviewWorkspace && reviewPublish?.dispatched
+        ? { reviewPublish: { requested: true as const, workspaceId: reviewWorkspace.id, ...(reviewPublish.commandId ? { commandId: reviewPublish.commandId } : {}) } }
+        : {}),
+    };
+  const writeIdempotencyKey = input.idempotencyKey ? `task:${taskId}:deliverable-write:${input.idempotencyKey}` : undefined;
+  // Read before the new event grants authorization; a withdrawn hand-off still has stale status.
+  const hadLandAuthorization = wantsLand && workspace ? workspaceLandAuthorization(workspace.id).authorized && !workspaceLandAuthorizationWithdrawn(workspace.id) : false;
+  const delivery = wantsLand && workspace && sourceRef && sourceHeadSha && frozenIntent
+    ? await recordTaskDeliverableWithLandingIngressAsync(
+        { id: taskId, input: deliveryInput, workspaceId: workspace.id, sourceRef, sourceHeadSha, frozenIntent, nothingToLand: Boolean(noWork) },
+        { idempotencyKey: `task:${taskId}:deliverable-write:${landingRequestKey}` },
+      )
+    : await recordTaskDeliverableAsync(
+        taskId,
+        deliveryInput,
+    // This is intentionally NOT the delivery event's domain key. It is the stable gateway-ledger
+    // key for a retry of this submission. A ledger replay returns `created:false,replayed:true`,
+    // allowing the idempotent/keyed post-commit effects below to reconcile a lost acknowledgement.
+        writeIdempotencyKey ? { idempotencyKey: writeIdempotencyKey } : undefined,
+      );
+  // #2518 — the WRITER's outcome is the authority for every post-commit branch below, never the
+  // service-side `wantsLand` boolean: a coordinator hold (or the permanent block) committing
+  // inside the write transaction flips a semantic landing delivery to held/blocked AFTER all the
+  // validation above has already run. Only `armed` may say "submitted for landing" and call ready.
+  const armOutcome = (delivery as { outcome?: CompleteDeliveryArmOutcome }).outcome ?? "armed";
+  const nothingToLand = armOutcome === "nothing-to-land" ? noWork : undefined;
+  const heldForReview = armOutcome === "held";
+  // Packaged-ephemeral Proof of Life: the writer ACK proves event + ingress committed together;
+  // die before ANY post-commit effect or the independently scheduled admission pump can run.
+  const eventMeta = deliveryEvent(taskId, input.idempotencyKey)?.metadata ?? delivery.event.metadata as unknown as TaskDeliverableEventMetadata;
+  const permanentlyBlocked = armOutcome === "permanent-blocked" || eventMeta?.land?.reason === "workspace-land-blocked";
+  // Stable per-delivery key: the caller's idempotency key, else `event:<id>` (a duplicate delivery
+  // resolves the SAME existing event, so the key is stable across retries; a reopen+re-deliver mints a
+  // new event → a new key → a genuine new close — finding 5b).
+  const deliveryKey = input.idempotencyKey ?? `event:${delivery.event.id}`;
+  // Delivery disposition is an independent lifecycle fact. Keep it even when
+  // the merge controller continues to use its existing `active`/`ready` enum.
+  if (delivery.created && workspace) {
+    const landState = input.disposition === "complete"
+      ? "delivery:complete"
+      : input.disposition === "blocked"
+        ? "delivery:blocked"
+        : input.disposition === "needs-review"
+          ? "delivery:needs-review"
+          : "delivery-error";
+    await transitionWorkspaceLandStateAsync(workspace.id, landState, { lastDeliveryDisposition: input.disposition, lastDeliveryAt: Date.now() });
+  }
+  // A natural domain duplicate is a no-op. A gateway-ledger replay is different: its write may
+  // have committed before the original caller lost the acknowledgement, so converge every
+  // idempotent/keyed post-commit effect before returning the replay result.
+  const reconcileEffects = delivery.created || (delivery.replayed === true && eventMeta?.effectsCompleted !== true);
+  if (reconcileEffects) {
+    for (const gate of gateWrites(effectiveGates, deliveryKey)) {
+      await recordGateAsync(taskId, { ...gate, actor });
+    }
+    if (input.disposition === "blocked") {
+      await setTaskStatusAsync(taskId, { status: "blocked", blockedBy: blockedBy as TaskBlocker[], note: reason, actor }, {
+        idempotencyKey: `task:${taskId}:deliverable:${deliveryKey}:status:blocked`,
+      });
+    } else if (input.disposition === "failed") {
+      await setTaskStatusAsync(taskId, { status: "failed", note: reason, actor }, {
+        idempotencyKey: `task:${taskId}:deliverable:${deliveryKey}:status:failed`,
+      });
+    } else if (nothingToLand && workspace) {
+      await completeTaskWithNothingToLand({ taskId, workspaceId: workspace.id, ...nothingToLand, deliveryKey, actor });
+    } else if (permanentlyBlocked) {
+      await advanceHandedOffTask(getTaskDetail(taskId) ?? before, workspace?.branch, deliveryKey, actor);
+    } else if (isVerdictOnlyComplete) {
+      // Close before notification so it carries the final status. The keyed transition also
+      // reconciles a gateway replay without appending another status event.
+      await completeVerdictOnlyTask(getTaskDetail(taskId) ?? before, deliveryKey, actor);
+    } else {
+      // Only an armed land commits the branch; a held or needs-review hand-off stays in review.
+      await advanceHandedOffTask(getTaskDetail(taskId) ?? before, wantsLand && armOutcome === "armed" ? workspace?.branch : undefined, deliveryKey, actor);
+    }
+  }
+  if (reconcileEffects) {
+    const detail = getTaskDetail(taskId) ?? currentTask;
+    if (detail) {
+      emitTaskChanged(detail, "task.deliverable");
+      notifyDelivery(taskId, delivery.event.id, eventMeta ?? (delivery.event.metadata as unknown as TaskDeliverableEventMetadata), wantsLand && armOutcome === "armed");
+      if (input.disposition === "failed") {
+        emitTaskSemanticNotification({ task: detail, transition: "gate-failed", actor, occurrenceKey: `event:${delivery.event.id}`, outcome: { disposition: "failed" } });
+      }
+    }
+  }
+
+  let land: Record<string, unknown> | undefined;
+  if (nothingToLand && workspace) {
+    land = { requested: false, triggered: false, reason: "nothing-to-land", workspaceId: workspace.id, ...nothingToLand };
+  } else if (heldForReview && workspace) {
+    // #2518 — the held park: push/pin the branch and leave the workspace visibly
+    // `review_requested` via the EXISTING request-review action (internal park bypass of the
+    // review-hold barrier — this parks for review; it arms nothing, because a held delivery
+    // carries neither a land authorization nor ingress, so neither land engine can pick it up).
+    // A park failure is returned but never fails the delivery: the accepted event is durable
+    // and effectsCompleted below deliberately stays unset so a retry re-drives the park.
+    land = { requested: false, triggered: false, reason: "review-hold", sourceHeadSha, workspaceId: workspace.id };
+    if (reconcileEffects) {
+      // #2518 review MED 5 — NO markAgentWorkFinal here: the worker's work is NOT final while
+      // its delivery sits under review (it stays on the hook for fix-forward); only the ARMED
+      // path below marks the hand-off final.
+      const park = await applyWorkspaceAction(workspace, {
+        action: "request-review",
+        agentId: actor,
+        detail: `Task T${taskId} delivered complete — held for coordinator review`,
+        reviewHoldPark: true,
+        deliveryHeadSha: sourceHeadSha,
+        auditMetadata: { via: "task_deliver", actor, taskId, deliveryEventId: delivery.event.id },
+      });
+      if (!park.ok) land.parkError = park.error;
+    }
+  } else if (permanentlyBlocked && workspace) {
+    // #2518 — the permanent workspace block refused the arm (it outranks the temporary hold).
+    // No park, no ready: report the refusal honestly instead of "submitted for landing".
+    land = { requested: false, triggered: false, reason: "workspace-land-blocked", workspaceId: workspace.id, branch: workspace.branch, message: `committed on branch ${workspace.branch}; not landed: ${LAND_BLOCK_REJECT_MESSAGE}` };
+  } else if (wantsLand && reconcileEffects && workspace) {
+    // `ready` itself appends an audit event and schedules auto-merge, so only request it while this
+    // delivery's workspace remains active. A ledger replay after a successful request observes the
+    // ready (or later) state and does not produce a second land request.
+    const liveWorkspace = getWorkspace(workspace.id) ?? workspace;
+    // #1937 — the `already-requested` dedup below is keyed to the HEAD the prior land/conflict state
+    // was computed against. A branch that hit a land conflict, rebased/force-pushed clean onto new
+    // base, and re-delivered `complete` used to no-op here on `already-requested` and stay silently
+    // wedged at status="conflict" with a STALE conflict scan — no steward acting, nothing landing.
+    // When the workspace HEAD has ADVANCED past the head that state was computed against, it is stale:
+    // invalidate it and RE-ENTER land evaluation against the new HEAD (which may now be a clean
+    // fast-forward — moving the row out of `conflict` back to `ready` re-arms the auto-merge lane and
+    // re-scans against the fresh head). A same-HEAD re-delivery still dedups — only a genuine HEAD
+    // change re-requests, so duplicate land requests against unchanged work are never issued.
+    //
+    // The pinned head is `landRequestHeadSha` (stamped by applyWorkspaceAction/requestWorkspaceMerge on
+    // the ready/merge hand-off), falling back to `conflictScanHeadSha`. The fallback is load-bearing:
+    // the ACTUAL #1937 population is rows that were ALREADY wedged before this fix shipped — they carry
+    // a `conflictScanHeadSha` (the periodic scan stamps it on every scanned row, and CONFLICT_SCAN_
+    // STATUSES covers `conflict` AND `merge_planned`) but NO `landRequestHeadSha`. Without the fallback
+    // they would never re-enter and stay wedged forever, which is the exact bug this fixes.
+    const liveMeta = liveWorkspace.metadata as Record<string, unknown>;
+    const currentHead = typeof liveMeta.gitHeadSha === "string" ? liveMeta.gitHeadSha : undefined;
+    const landRequestHead = typeof liveMeta.landRequestHeadSha === "string" ? liveMeta.landRequestHeadSha : undefined;
+    const conflictScanHead = typeof liveMeta.conflictScanHeadSha === "string" ? liveMeta.conflictScanHeadSha : undefined;
+    const pinnedLandHead = landRequestHead ?? conflictScanHead;
+    const headAdvancedSinceLandRequest = Boolean(currentHead && pinnedLandHead && currentHead !== pinnedLandHead);
+    // #2141 — an explicit re-delivery is a fresh signal after an in-flight merge phase
+    // completed before its branch was visible on origin. It must not be folded
+    // into same-head `already-requested`; only terminal non-PR attempts qualify,
+    // so a currently running merge or a PR waiting on GitHub is never doubled.
+    const priorMerge = LAND_IN_FLIGHT_STATUSES.has(liveWorkspace.status)
+      ? findLatestCommandByCorrelation("workspace.merge", liveWorkspace.id)
+      : null;
+    const retryableMergePlan = mergeCommandNeedsRetry(priorMerge);
+    const withdrawnLand = !hadLandAuthorization
+      && LAND_REQUEST_STALE_ON_HEAD_ADVANCE_STATUSES.has(liveWorkspace.status)
+      && !LAND_IN_FLIGHT_STATUSES.has(liveWorkspace.status);
+    const reenterLand = liveWorkspace.status === "active"
+      || (headAdvancedSinceLandRequest && LAND_REQUEST_STALE_ON_HEAD_ADVANCE_STATUSES.has(liveWorkspace.status))
+      // A complete re-delivery is an explicit fresh hand-off, including after automatic retries
+      // exhausted. applyWorkspaceAction clears the old retry incident before re-arming it.
+      || retryableMergePlan || workspaceLandNeedsRearm(liveWorkspace) || withdrawnLand;
+    if (reenterLand) {
+      markAgentWorkFinal(actor, "task-deliver");
+      const result = await applyWorkspaceAction(liveWorkspace, {
+        action: "ready",
+        agentId: actor,
+        deliveryHeadSha: sourceHeadSha,
+        detail: `Task T${taskId} delivered complete`,
+        auditMetadata: { via: "task_deliver", actor, taskId, deliveryEventId: delivery.event.id },
+      });
+      if (!result.ok) {
+        land = { requested: true, triggered: false, error: result.error, workspaceId: workspace.id };
+      } else {
+        if (result.command) emitCommand(result.command);
+        land = { requested: true, triggered: true, workspace: result.workspace, command: result.command };
+      }
+    } else {
+      land = {
+        requested: true,
+        triggered: false,
+        reason: "already-requested",
+        workspaceId: workspace.id,
+      };
+    }
+  } else if (wantsLand && !reconcileEffects) {
+    land = { requested: true, triggered: false, reason: "duplicate-delivery" };
+  } else if (landNotArmed && workspace) {
+    // #2258 — the explicit "your branch did NOT enter the land lane" answer. Returned on every
+    // delivery (including a duplicate), because the caller that retries is exactly the one that
+    // needs to hear it.
+    land = {
+      requested: false,
+      triggered: false,
+      reason: landNotArmed.reason,
+      unmergedAhead: landNotArmed.unmergedAhead,
+      workspaceId: workspace.id,
+    };
+  }
+
+  // Commit this only after the whole chain (including the workspace hand-off) converges. If any
+  // effect throws — or the ready action returns an error — the marker stays absent and a retry
+  // re-drives the idempotent/keyed effects. A normal replay sees the marker and remains a strict
+  // duplicate no-op, even if an unrelated actor later changes the workspace back to active.
+  // #2518 — a held delivery converges once its park succeeded (a parkError keeps it re-drivable);
+  // a permanently-blocked arm refusal owes nothing further, so it converges immediately.
+  const heldParkConverged = land?.reason === "review-hold" && !("parkError" in land);
+  const blockedArmConverged = land?.reason === "workspace-land-blocked";
+  if (reconcileEffects && (nothingToLand || !wantsLand || land?.triggered === true || land?.reason === "already-requested" || heldParkConverged || blockedArmConverged)) {
+    await markTaskDeliverableEffectsCompleteAsync(taskId, delivery.event.id);
+  }
+  // The run routes this delivery (a review, the findings, the clear) before the caller hears back.
+  if (workflowStep && reconcileEffects) await workflowTaskDelivered();
+
+  return {
+    taskId,
+    event: delivery.event,
+    created: delivery.created,
+    delivery: eventMeta ?? delivery.event.metadata,
+    // Surface the associations at the moment a worker hands off. They are historical
+    // context, not a claim that they are the issue a commit will close (#1694).
+    linkedIssues: (getTaskDetail(taskId) ?? currentTask).issues.map((issue) => ({ provider: issue.provider, repo: issue.repo, externalKey: issue.externalKey, title: issue.title, status: issue.status })),
+    ...(land ? { land } : {}),
+    ...(reviewPublish ? { reviewPublish } : {}),
+  };
+}