@humwick/server 0.0.0-stage → 0.130.0

package/src/workspace-actions.ts

@@ -0,0 +1,689 @@
+import { recordWorkspaceAudit } from "./workspace-action-audit";
+import { WORKSPACE_MERGE_HOLD_MESSAGE } from "./db/workspace-merge-hold";
+import { stewardGenerationCanceled } from "./db/workspace-steward-fence";
+import { getAgent } from "./db/agents";
+import { stringValue } from "@humwick/sdk";
+// Single home for workspace lifecycle actions, shared by the HTTP route
+// (`POST /api/workspaces/:id/actions`) and the `relay_workspace_*` MCP tools.
+//
+// Why this module exists: the action→status mapping, claim/merge/deps branching,
+// and the per-action audit descriptors are exactly the kind of rule that used to
+// live in one handler and silently drift when a second surface re-implemented it.
+// Both surfaces authorize FIRST (route via authorizeRoute, MCP via token scopes)
+// and then call `applyWorkspaceAction` — which does NO auth. Like
+// `requestWorkspaceMerge`, the core does not emit the command event; it returns
+// the Command and the caller emits via its own `emitCommand` (kept module-local).
+
+import { createCommand } from "./commands-db";
+import { requestWorkspaceRekey } from "./workspace-rekey";
+import { isWorkspaceSteward, workspaceStewardRefusal } from "./workspace-steward-authority";
+import { getStewardConfig } from "./config-store";
+import { cancelPendingLegacyLandingsAsync } from "./commands-landing-async";
+import { workspaceOwnerOrchestrator } from "./workspace-host";
+import {
+  getWorkspace,
+  claimWorkspaceMetadataAsync,
+  listOrchestrators,
+  patchWorkspaceMetadataAsync,
+  releaseWorkspaceClaimMetadataAsync,
+  setWorkspaceMergeHoldAsync,
+  transitionWorkspaceLandStateAsync,
+  updateWorkspaceStatusAsync,
+} from "./db";
+import { isOwnerAlive, requestWorkspaceMerge } from "./workspace-merge";
+import { buildWorkspaceCleanupCommand } from "./workspace-cleanup-stale";
+// Re-export the land-strategy contract so the MCP land tool validates against the same
+// tuple as the HTTP route without a second import hop (one source: workspace-merge, #304).
+export { LAND_STRATEGIES } from "./workspace-merge";
+import { claimMetadataPatch, workspaceActiveClaim, workspaceStewardHandbackPending } from "./workspace-claim";
+import { DIRTY_WORKTREE_LAND_SKIP_REASON, LAND_IN_FLIGHT_STATUSES, READY_TO_LAND_STATUSES, TERMINAL_WORKSPACE_STATUSES, worktreeReapable } from "./workspace-phase";
+import { LAND_BLOCK_REJECT_MESSAGE, stripReservedWorkspaceMetadataKeys } from "./land-block";
+import { REVIEW_HOLD_REJECT_MESSAGE, workspaceLandBarrier } from "./db";
+import { CLEAR_MERGE_NO_PROGRESS, scheduleRepoMerge } from "./workspace-auto-merge";
+import { archiveLandAttempt, CLEAR_LAST_ATTEMPT_VERDICT, CLEAR_MERGE_RETRY } from "./workspace-merge-progress";
+import { fetchHostMergePreview, refreshWorkspaceGitState } from "./workspace-probe";
+import { recordLandStopped } from "./workspace-land-stopped";
+import { finishWorkspaceStewardHandoff } from "./steward-handoff";
+import { stewardHandoffIdentity } from "./steward-provenance";
+import type { Command, WorkspaceAutoMergePolicy, WorkspaceLandingPolicy, WorkspaceMergeStrategy, WorkspaceRecord, WorkspaceStatus } from "./types";
+import type { WorkspaceLandGateLevel } from "./types";
+import type { WorkspaceLandGateAuth } from "./workspace-land-gate";
+
+// Single source of truth for the action verb set. The route's `optionalEnum` and
+// the MCP tool surface both import this so they can never drift out of sync.
+export const WORKSPACE_ACTIONS = [
+  "status",
+  "hold-merge",
+  "resume-merge",
+  "ready",
+  "conflict-found",
+  "request-review",
+  "merge-plan",
+  "merge",
+  "abandon",
+  "cleanup",
+  "claim",
+  "release-claim",
+  "deps-refresh",
+  "rekey",
+] as const;
+export type WorkspaceAction = (typeof WORKSPACE_ACTIONS)[number];
+
+// Explicit blocks refuse land-directed actions before a row can become ready. The separate
+// workspace.publish-review command still lets a blocked agent publish its diff for review.
+const LAND_BLOCKED_ACTIONS = new Set<WorkspaceAction>(["ready", "request-review", "merge", "merge-plan"]);
+
+interface ApplyWorkspaceActionInput {
+  action: WorkspaceAction;
+  agentId?: string;
+  detail?: string;
+  metadata?: Record<string, unknown>;
+  // merge
+  strategy?: WorkspaceMergeStrategy | WorkspaceLandingPolicy;
+  deleteBranch?: boolean;
+  prTitle?: string;
+  prBody?: string;
+  autoMerge?: WorkspaceAutoMergePolicy;
+  reviewer?: string;
+  gateLevel?: WorkspaceLandGateLevel;
+  gateReason?: string;
+  gateAuth?: WorkspaceLandGateAuth;
+  // cleanup
+  force?: boolean;
+  /** Internal dead-owner path only. The host repeats this proof before removal. */
+  autoReclaim?: "origin-captured";
+  // claim / release-claim
+  purpose?: string;
+  /** Set only by an already-authorized workspace recovery surface. */
+  releaseClaimAny?: boolean;
+  // deps-refresh
+  checkOnly?: boolean;
+  // #2518 — INTERNAL ONLY (task-delivery.ts held-delivery park). Never settable from HTTP/MCP:
+  // lets the server's own held `complete` delivery park the branch in `review_requested` past
+  // the review-hold barrier — a park arms nothing (a held delivery has no land authorization
+  // or ingress), it only makes the held state visible. The permanent block still refuses.
+  reviewHoldPark?: boolean;
+  /** Host-attested delivery head, verified before the delivery event was committed. */
+  deliveryHeadSha?: string;
+  // #2518 round-2 BLOCKER B — INTERNAL ONLY (task-review-hold.ts clear re-drive). Never settable
+  // from HTTP/MCP: pins this READY hand-off's `landRequestHeadSha` to the coordinator-approved
+  // REVIEWED head (the promoted delivery's server-attested sourceHeadSha) instead of re-probing
+  // the live branch, and stamps `reviewHoldPromotedHeadSha` so every later explicit merge of
+  // this row is CAS-pinned to exactly that sha — a worker commit pushed after the review can
+  // never become the land request head nor merge past the reviewed pin.
+  reviewHoldPromotedHeadSha?: string;
+  // Provenance merged into the activity-event metadata (who/how) — the HTTP route
+  // passes `authAuditMetadata(req)`, the MCP surface passes `{ via: "mcp", actor }`.
+  auditMetadata?: Record<string, unknown>;
+  // #2826 — set ONLY by the HTTP + MCP explicit-land surfaces below. Internal callers
+  // (delivery park, hold-clear re-drive, reaper) stay on the scoped hold predicate.
+  ownerExplicitLand?: boolean;
+}
+
+type WorkspaceActionResult =
+  | {
+      ok: true;
+      httpStatus: number;
+      workspace: WorkspaceRecord;
+      command?: Command;
+      claim?: ReturnType<typeof workspaceActiveClaim>;
+    }
+  | { ok: false; httpStatus: number; error: string };
+
+// Map of the plain status-transition actions to their target status. merge/cleanup
+// (command-emitting) and status/claim/release/deps (special) are handled explicitly.
+const STATUS_BY_ACTION: Partial<Record<WorkspaceAction, WorkspaceStatus>> = {
+  ready: "ready",
+  "conflict-found": "conflict",
+  "request-review": "review_requested",
+  "merge-plan": "merge_planned",
+  abandon: "abandoned",
+  cleanup: "cleanup_requested",
+};
+
+function metadataNumber(metadata: Record<string, unknown>, key: string): number | undefined {
+  const value = metadata[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+async function cleanupWorkSafety(workspace: WorkspaceRecord, allowOriginCapture = false): Promise<{ ok: true } | { ok: false; error: string }> {
+  // The durable Relay receipt is authoritative. Git patch-equivalence below is
+  // retained only for the external-land -> receipt-write crash window and for
+  // worktrees that were landed outside Relay.
+  if (workspace.landedAt !== undefined && workspace.landedSha) return { ok: true };
+  const owner = workspaceOwnerOrchestrator(workspace, listOrchestrators(), { requireApiUrl: true });
+  if (!owner?.apiUrl) return { ok: false, error: "owning orchestrator unavailable for cleanup safety probe" };
+  const preview = await fetchHostMergePreview(owner.apiUrl, workspace, { checkPr: false, requireRemoteBase: true, requireOriginCapture: allowOriginCapture });
+  if (!preview) return { ok: false, error: "cleanup safety probe unavailable" };
+  if ("available" in preview && preview.available === false) return { ok: false, error: "cleanup safety probe unavailable" };
+  const p = preview as Exclude<typeof preview, { available: false }>;
+  if (p.missing) return { ok: true };
+  if (p.error) return { ok: false, error: `cleanup safety probe error: ${p.error}` };
+  if (allowOriginCapture && p.originCaptured === true) return { ok: true };
+  if (worktreeReapable({ landed: p.landed, ahead: p.ahead, unmergedAhead: p.unmergedAhead, dirtyCount: p.dirtyCount })) return { ok: true };
+  const dirtyCount = p.dirtyCount ?? 0;
+  if (dirtyCount > 0) return { ok: false, error: `${dirtyCount} uncommitted change(s)` };
+  const ahead = p.unmergedAhead ?? p.ahead ?? 0;
+  return { ok: false, error: `${ahead} unlanded commit(s)` };
+}
+
+export async function applyWorkspaceAction(workspace: WorkspaceRecord, input: ApplyWorkspaceActionInput): Promise<WorkspaceActionResult> {
+  const { action } = input;
+  const agentId = input.agentId;
+  const detail = input.detail;
+  // #1482/#2518 — authority-owned metadata (the permanent block and reviewed-head promotion pin)
+  // is writable only through its trusted internal path. Strip it from caller metadata at the shared
+  // HTTP+MCP chokepoint; DB mutation helpers re-strip as defense-in-depth.
+  const currentWorkspace = getWorkspace(workspace.id) ?? workspace;
+  if (action !== "status" && (workspaceStewardHandbackPending(currentWorkspace)
+    || (agentId && stewardGenerationCanceled(agentId, stringValue(getAgent(agentId)?.meta?.spawnRequestId))))) {
+    return { ok: false, httpStatus: 409, error: "steward hand-back pending: workspace mutations are fenced until host process-tree proof" };
+  }
+  const metadata = stripReservedWorkspaceMetadataKeys(input.metadata ?? {});
+  const requiresCommand = action === "cleanup" || action === "merge" || action === "rekey";
+  if (action === "claim" && (input.purpose === "steward" || isWorkspaceSteward(agentId, workspace)) && !getStewardConfig().enabled) {
+    return { ok: false, httpStatus: 403, error: "automatic stewardship is disabled" };
+  }
+  // A promoted review clear supplies its own authority for the internal READY hand-off.
+  if (!(action === "ready" && input.reviewHoldPromotedHeadSha) && agentId !== workspace.ownerAgentId && isWorkspaceSteward(agentId, workspace) && LAND_BLOCKED_ACTIONS.has(action)) {
+    const refusal = workspaceStewardRefusal(workspace, agentId);
+    if (refusal) return { ok: false, httpStatus: 403, error: refusal };
+  }
+
+  // Explicit spawn blocks are permanent. A review hold clears only by reviewed-HEAD CAS;
+  // the internal held-delivery park requests review without arming a land.
+  if (LAND_BLOCKED_ACTIONS.has(action)) {
+    // #2826 — an explicit owner land/merge honours a held Task owned by the same agent
+    // that is not yet bound to any workspace (the barrier names it in the 403).
+    const barrier = workspaceLandBarrier(workspace, {
+      ...(input.ownerExplicitLand === true ? { ownerExplicitLand: true as const } : {}),
+      ...(agentId ? { callerAgentId: agentId } : {}),
+    });
+    if (barrier.mergeHeld && (action === "merge" || action === "merge-plan")) {
+      return { ok: false, httpStatus: 409, error: WORKSPACE_MERGE_HOLD_MESSAGE };
+    }
+    if (barrier.landBlocked) {
+      return { ok: false, httpStatus: 403, error: LAND_BLOCK_REJECT_MESSAGE };
+    }
+    if (barrier.reviewHeld && input.reviewHoldPark !== true) {
+      const blocking = barrier.reviewHeldTaskId != null ? ` (blocking held task T${barrier.reviewHeldTaskId})` : "";
+      return { ok: false, httpStatus: 403, error: `${REVIEW_HOLD_REJECT_MESSAGE}${blocking}` };
+    }
+  }
+
+  // Shared-mode rows are occupancy markers with no worktree — nothing on disk to
+  // merge or clean. Reject host commands against them up front.
+  if (requiresCommand && (workspace.mode !== "isolated" || !workspace.worktreePath)) {
+    return { ok: false, httpStatus: 422, error: `workspace ${workspace.id} has no worktree to ${action}` };
+  }
+
+  if (action === "status") {
+    return { ok: true, httpStatus: 200, workspace };
+  }
+  if (action === "hold-merge" || action === "resume-merge") {
+    const hold = action === "hold-merge";
+    if (hold && LAND_IN_FLIGHT_STATUSES.has(currentWorkspace.status)) return { ok: false, httpStatus: 409, error: "merge already admitted; wait for it to settle before holding retries" };
+    const updated = await setWorkspaceMergeHoldAsync(workspace.id, hold
+      ? { actor: agentId ?? "operator", heldAt: Date.now(), ...(detail ? { reason: detail } : {}) }
+      : undefined);
+    if (!updated) return { ok: false, httpStatus: 404, error: "workspace not found" };
+    await recordWorkspaceAudit({ action, workspace: updated, agentId, title: hold ? "Workspace merge held" : "Workspace merge resumed", body: detail, icon: "ti-git-branch", auditMetadata: input.auditMetadata });
+    if (!hold) scheduleRepoMerge(updated.repoRoot, updated.baseRef);
+    return { ok: true, httpStatus: 200, workspace: updated };
+  }
+  if (action === "rekey") {
+    const result = await requestWorkspaceRekey(workspace, agentId, metadata);
+    if (result.ok) await recordWorkspaceAudit({ action, workspace, agentId, title: "Steward rekey requested", icon: "ti-git-branch", extra: { commandId: result.command.id, ...metadata }, auditMetadata: input.auditMetadata });
+    return result;
+  }
+
+  // Steward claim/lease (#208): a TTL'd metadata lease that auto-merge yields to,
+  // so deterministic landing can't race a steward mid-validation. No status change.
+  if (action === "claim" || action === "release-claim") {
+    const release = action === "release-claim";
+    const claimant = agentId ?? "steward";
+    const result = release
+      ? await releaseWorkspaceClaimMetadataAsync(
+        workspace.id,
+        claimant,
+        claimMetadataPatch(true),
+        Date.now(),
+        { allowOtherClaimant: input.releaseClaimAny === true },
+      )
+      : await claimWorkspaceMetadataAsync(workspace.id, claimant, { ...claimMetadataPatch(false, claimant, input.purpose), ...stewardHandoffIdentity(typeof workspace.metadata.stewardPolicy === "string" ? workspace.metadata.stewardPolicy : undefined, claimant) }, Date.now());
+    if (!result.ok) {
+      if (result.reason === "not-found") return { ok: false, httpStatus: 404, error: "workspace not found" };
+      const active = result.workspace ? workspaceActiveClaim(result.workspace) : null;
+      const owner = active?.by ? ` by ${active.by}` : "";
+      return { ok: false, httpStatus: 409, error: `workspace ${workspace.id} is already claimed${owner}` };
+    }
+    const updated = result.workspace;
+    await transitionWorkspaceLandStateAsync(updated.id, release ? "steward-requested" : "steward-claimed");
+    const lifecycleWorkspace = getWorkspace(updated.id) ?? updated;
+    await recordWorkspaceAudit({
+      action,
+      workspace: lifecycleWorkspace,
+      agentId,
+      title: release ? "Workspace claim released" : "Workspace claimed",
+      body: detail ?? input.purpose ?? updated.worktreePath,
+      icon: "ti-lock",
+      auditMetadata: input.auditMetadata,
+    });
+    if (release) await finishWorkspaceStewardHandoff(workspace);
+    return { ok: true, httpStatus: 200, workspace: lifecycleWorkspace, claim: workspaceActiveClaim(lifecycleWorkspace) };
+  }
+
+  // Base merges go through the shared helper (lease + command + bind), the same
+  // path the auto-merge job uses, so both serialize per repo (issue #157).
+  if (action === "merge") {
+    // #2518 round-2 BLOCKER B — a review-hold promotion pins the coordinator-approved REVIEWED
+    // sha on the row (`reviewHoldPromotedHeadSha`). Supply it as `expectedHeadSha` so the shared
+    // dispatcher rejects a branch whose live HEAD moved past the reviewed sha (worker commits
+    // pushed after the review must not land through the explicit action lane); an unmodified
+    // head still lands exactly as approved. Rows without a promotion pin merge as before.
+    const promotedPin = typeof workspace.metadata.reviewHoldPromotedHeadSha === "string" && workspace.metadata.reviewHoldPromotedHeadSha.trim()
+      ? workspace.metadata.reviewHoldPromotedHeadSha.trim()
+      : undefined;
+    const result = await requestWorkspaceMerge(workspace, {
+      requestedBy: agentId ?? "dashboard",
+      ...(promotedPin ? { expectedHeadSha: promotedPin } : {}),
+      // Pass the strategy through verbatim (undefined when unset) — the single
+      // config-aware default lives in requestWorkspaceMerge, so land surfaces
+      // resolve it identically instead of each applying its own fallback.
+      strategy: input.strategy,
+      deleteBranch: input.deleteBranch !== false,
+      prTitle: input.prTitle,
+      prBody: input.prBody,
+      autoMerge: input.autoMerge,
+      reviewer: input.reviewer,
+      gateLevel: input.gateLevel,
+      gateReason: input.gateReason,
+      gateAuth: input.gateAuth,
+      metadata: { ...metadata, ...(detail ? { detail } : {}), ...(agentId ? { updatedByAgentId: agentId } : {}) },
+    });
+    if (!result.ok) return { ok: false, httpStatus: result.status, error: result.error };
+    await recordWorkspaceAudit({
+      action: "merge",
+      workspace: result.workspace,
+      agentId,
+      title: "Workspace merge",
+      body: detail ?? workspace.worktreePath,
+      icon: "ti-git-merge",
+      auditMetadata: input.auditMetadata,
+      extra: {
+        status: result.workspace.status,
+        commandId: result.command.id,
+        ...(result.gate.level !== "full" ? { gateSkipped: true, gateLevel: result.gate.level, gateReason: result.gate.reason, gateRequestedBy: result.gate.by } : {}),
+      },
+    });
+    return { ok: true, httpStatus: 202, workspace: result.workspace, command: result.command };
+  }
+
+  // Deps refresh (#51): self-service for the owning agent — re-provision deps the
+  // shared symlinked node_modules has gone stale on (or, checkOnly, just report).
+  if (action === "deps-refresh") {
+    if (workspace.mode !== "isolated" || !workspace.worktreePath) {
+      return { ok: false, httpStatus: 422, error: `workspace ${workspace.id} has no isolated worktree to refresh` };
+    }
+    const checkOnly = input.checkOnly === true;
+    const built = buildWorkspaceDepsRefreshCommand(workspace, agentId ?? "agent", checkOnly);
+    if (!built.ok) return { ok: false, httpStatus: built.status, error: built.error };
+    await recordWorkspaceAudit({
+      action,
+      workspace,
+      agentId,
+      title: checkOnly ? "Workspace deps check" : "Workspace deps refresh",
+      body: detail ?? workspace.worktreePath,
+      icon: "ti-package",
+      auditMetadata: input.auditMetadata,
+      extra: { checkOnly, commandId: built.command.id },
+    });
+    return { ok: true, httpStatus: 202, workspace, command: built.command };
+  }
+
+  const nextStatus = STATUS_BY_ACTION[action];
+  if (!nextStatus) return { ok: false, httpStatus: 400, error: `unsupported action: ${action}` };
+
+  // #1937 — the HEAD this land is being requested against. Pin it on the ready/request-review hand-off
+  // so a later re-delivery can distinguish a stale `already-requested` guard (HEAD unchanged → dedup) from
+  // a genuine rebase/force-push re-attempt (HEAD advanced → re-enter land evaluation against the new HEAD).
+  let landRequestHeadSha: string | undefined;
+  // #2518 round-2 BLOCKER B — the review-hold clear re-drive pins the REVIEWED head here instead
+  // of the probed live head; a FRESH (unpinned) hand-off clears the promotion pin, because new
+  // work was armed/reviewed since and the stale reviewed sha must no longer CAS later merges.
+  let clearReviewHoldPromotedPin = false;
+  if (input.deliveryHeadSha && (action === "ready" || (input.reviewHoldPark && action === "request-review"))) {
+    const dirtyCount = metadataNumber((getWorkspace(workspace.id) ?? workspace).metadata, "gitDirtyCount") ?? 0;
+    if (dirtyCount > 0) return { ok: false, httpStatus: 409, error: `workspace ${workspace.id} cannot be marked ${nextStatus}: ${DIRTY_WORKTREE_LAND_SKIP_REASON} (${dirtyCount} dirty file${dirtyCount === 1 ? "" : "s"}); commit or stash first` };
+    landRequestHeadSha = input.deliveryHeadSha;
+    clearReviewHoldPromotedPin = true;
+  } else if (READY_TO_LAND_STATUSES.has(nextStatus)) {
+    // #2140 — verify (and auto-push if missing) the branch on origin before this row can
+    // ever enter a ready-to-land status; without it a codex worker that forgot `git push`
+    // wedges the land pipeline at merge_planned with nothing on origin to merge. Only
+    // rejects on a CONFIRMED push failure (host reachable, branch missing, push failed) —
+    // `pushed` stays undefined when the host preview is unavailable/unrelated, which must
+    // never block a transition.
+    const probe = await refreshWorkspaceGitState(workspace, { ensurePushed: true });
+    const freshWorkspace = getWorkspace(workspace.id) ?? workspace;
+    const dirtyCount = metadataNumber(freshWorkspace.metadata, "gitDirtyCount") ?? 0;
+    if (dirtyCount > 0) {
+      return {
+        ok: false,
+        httpStatus: 409,
+        error: `workspace ${workspace.id} cannot be marked ${nextStatus}: ${DIRTY_WORKTREE_LAND_SKIP_REASON} (${dirtyCount} dirty file${dirtyCount === 1 ? "" : "s"}); commit or stash first`,
+      };
+    }
+    if (probe.pushed === false) {
+      return {
+        ok: false,
+        httpStatus: 422,
+        error: `workspace ${workspace.id} cannot be marked ${nextStatus}: branch not found on origin and auto-push failed${probe.pushError ? ` (${probe.pushError})` : ""}; push the branch to origin first`,
+      };
+    }
+    const promotedPin = typeof input.reviewHoldPromotedHeadSha === "string" ? input.reviewHoldPromotedHeadSha.trim() : "";
+    if (promotedPin) {
+      landRequestHeadSha = promotedPin;
+    } else {
+      clearReviewHoldPromotedPin = true;
+      const head = freshWorkspace.metadata.gitHeadSha;
+      if (typeof head === "string") landRequestHeadSha = head;
+    }
+  }
+
+  if (
+    action === "cleanup" &&
+    input.force !== true &&
+    workspace.mode === "isolated" &&
+    !TERMINAL_WORKSPACE_STATUSES.has(workspace.status) &&
+    isOwnerAlive(workspace.ownerAgentId)
+  ) {
+    return {
+      ok: false,
+      httpStatus: 409,
+      error: `workspace ${workspace.id} owner is still online; pass force:true to clean it up intentionally`,
+    };
+  }
+
+  let command: Command | undefined;
+  if (requiresCommand) {
+    // Only `cleanup` reaches here — `merge` returned early via the shared helper.
+    const safety = await cleanupWorkSafety(workspace, input.autoReclaim === "origin-captured");
+    if (!safety.ok && !(input.force === true && Boolean(detail?.trim()))) {
+      return {
+        ok: false,
+        httpStatus: 409,
+        error: `workspace ${workspace.id} cannot be cleaned up safely: ${safety.error}; pass force:true with a detail reason only if intentionally discarding work`,
+      };
+    }
+    const built = buildWorkspaceCleanupCommand(workspace, agentId ?? "dashboard", {
+      force: input.force === true,
+      reason: detail,
+      autoReclaim: input.autoReclaim,
+    });
+    if (!built.ok) return { ok: false, httpStatus: built.status, error: built.error };
+    command = built.command;
+  }
+
+  const actionAt = Date.now();
+  const updated = await updateWorkspaceStatusAsync(workspace.id, nextStatus, {
+    ...metadata,
+    ...(detail ? { detail } : {}),
+    ...(agentId ? { updatedByAgentId: agentId } : {}),
+    // #638 — a fresh ready/request-review hand-off means the owner did more work, so a
+    // prior auto-merge no-progress back-off should clear: the new commits may resolve
+    // whatever blocked the land (e.g. a base that's since been synced). Re-arm the lane.
+    ...(READY_TO_LAND_STATUSES.has(nextStatus) ? CLEAR_MERGE_NO_PROGRESS : {}),
+    // #2299 RC1 — a ready/request-review hand-off is also a successful (re-)arm: archive the prior
+    // attempt's verdict into `lastLandAttempt`, then clear it so it doesn't sit stamped next to the
+    // NEW land this hand-off queues (see workspace-merge-progress.ts for why).
+    ...(READY_TO_LAND_STATUSES.has(nextStatus) ? {
+      ...archiveLandAttempt(workspace.metadata),
+      ...CLEAR_LAST_ATTEMPT_VERDICT,
+      ...CLEAR_MERGE_RETRY,
+      // Stable across automatic redispatches of this hand-off, but replaced even when the owner
+      // explicitly re-hands the same HEAD to recovery.
+      landRequestAttemptAt: actionAt,
+    } : {}),
+    // #1937 — record the head this land is requested against (see landRequestHeadSha above).
+    ...(landRequestHeadSha ? { landRequestHeadSha } : {}),
+    // #1747 — an abandon must RELEASE any steward claim, not leave the row leased. Clearing it
+    // here (shallow-merged over existing metadata) makes the released row immediately claimable
+    // for recovery and stops a dead claim from blocking auto-merge yield logic.
+    ...(action === "abandon" ? claimMetadataPatch(true) : {}),
+    lastWorkspaceAction: action,
+    lastWorkspaceActionAt: actionAt,
+  }, {
+    // The promotion pin is stamped atomically by clearTaskReviewHoldBody, never here after the
+    // awaited host probe. Only a genuinely fresh unpinned hand-off may retire the reserved pin.
+    clearReviewHoldPromotedHeadSha: clearReviewHoldPromotedPin,
+  });
+  if (!updated) return { ok: false, httpStatus: 404, error: "workspace not found" };
+
+  // #1747 — an abandon is a CONTAINMENT control: it must actually stop the merge it targets,
+  // not merely relabel the workspace `abandoned`. Cancel every still-pending workspace.merge
+  // command correlated to this row so the looping merge can no longer be claimed by a host (a
+  // claimed/running one is left to settle). Without this the pending merge stays claimable —
+  // claimPendingCommand never re-checks workspace state — and the runaway continues.
+  if (action === "abandon") {
+    await recordLandStopped(workspace.id, "abandoned", detail);
+    await cancelPendingLegacyLandingsAsync(workspace.id);
+  }
+
+  // #237: a ready/request-review hand-off kicks the per-repo auto-merge inline right
+  // then, instead of waiting up to the backstop interval — this is what makes "mark
+  // ready → land" take seconds, not minutes (the #235 root-cause fix). Fire-and-forget
+  // + lease-serialized; a non-landable row is a harmless no-op (autoMergeForRepo re-checks).
+  if (READY_TO_LAND_STATUSES.has(nextStatus)) scheduleRepoMerge(updated.repoRoot);
+
+  await recordWorkspaceAudit({
+    action,
+    workspace: updated,
+    agentId,
+    title: `Workspace ${action}`,
+    body: detail ?? workspace.worktreePath,
+    icon: action === "cleanup" ? "ti-trash" : action === "conflict-found" ? "ti-alert-triangle" : "ti-git-branch",
+    auditMetadata: input.auditMetadata,
+    extra: { status: updated.status, commandId: command?.id },
+  });
+  return { ok: true, httpStatus: requiresCommand ? 202 : 200, workspace: updated, command };
+}
+
+// #1452 — build a REVIEW-ONLY publish command: ask the owning host to push the delivered tip to
+// origin's refs/review/* namespace so a reviewer can fetch it without an author handshake. The
+// host DERIVES + asserts the actual push ref itself (never trusts a caller-supplied target) and
+// self-gates on its own flag; the relay only passes identity hints (branch, workspaceId) and the
+// captured delivered `sha`. #1452 round-5 H4: the relay deliberately does NOT derive or return a
+// ref — the AUTHORITATIVE ref is whatever the HOST reports back on the command result (the host may
+// run a different sanitizer version), and the ledger records it only after that settlement.
+export function buildWorkspacePublishReviewCommand(
+  workspace: WorkspaceRecord,
+  requestedBy: string,
+  opts: { taskId?: number; sha?: string; reviewRef?: string } = {},
+): { ok: true; command: Command } | { ok: false; status: number; error: string } {
+  if (workspace.mode !== "isolated" || !workspace.worktreePath) {
+    return { ok: false, status: 422, error: `workspace ${workspace.id} has no worktree to publish for review` };
+  }
+  const owner = workspaceOwnerOrchestrator(workspace, listOrchestrators(), { onlineOnly: false });
+  if (!owner) return { ok: false, status: 409, error: "no orchestrator owns this workspace path" };
+  const command = createCommand({
+    type: "workspace.publish-review",
+    source: "system",
+    target: owner.agentId,
+    correlationId: workspace.id,
+    params: {
+      action: "publish-review",
+      workspaceId: workspace.id,
+      repoRoot: workspace.repoRoot,
+      worktreePath: workspace.worktreePath,
+      branch: workspace.branch,
+      ...(opts.sha ? { sha: opts.sha } : {}),
+      // #1452 round-9 — the relay-pinned expected ref. The host asserts its OWN derivation equals this
+      // before pushing (fail-closed on a sanitizer skew), so the ledger's pinned ref == the pushed ref.
+      ...(opts.reviewRef ? { reviewRef: opts.reviewRef } : {}),
+      ...(opts.taskId ? { taskId: opts.taskId } : {}),
+      requestedBy,
+      requestedAt: Date.now(),
+      queued: owner.status !== "online",
+    },
+  });
+  return { ok: true, command };
+}
+
+// #1452 round-4/round-5 — build a REVIEW-ONLY unpublish command from RAW ledger fields rather than a
+// live WorkspaceRecord, so the durable reconciler can still delete a leaked ref AFTER the workspace
+// row is purged/reaped (the "retain across DB purge" fix). The owning host is re-resolved each call
+// from the stored orchestratorId/repoRoot (robust to orchestrator agentId churn). Round-5 H4: the
+// caller passes the EXACT host-confirmed `ref` from the ledger and the host deletes THAT ref verbatim
+// (after asserting it is under refs/review/*) — it no longer re-derives the target from branch/
+// workspaceId, which could diverge across a relay/host sanitizer skew and leak the real ref.
+export function buildReviewRefUnpublishCommandFromFields(
+  fields: { workspaceId: string; repoRoot: string; worktreePath?: string; branch?: string; orchestratorId?: string; ref?: string },
+  requestedBy: string,
+): { ok: true; command: Command } | { ok: false; status: number; error: string } {
+  const synthetic = {
+    orchestratorId: fields.orchestratorId,
+    sourceCwd: fields.repoRoot,
+    repoRoot: fields.repoRoot,
+    worktreePath: fields.worktreePath,
+    mode: "isolated",
+  } as unknown as WorkspaceRecord;
+  const owner = workspaceOwnerOrchestrator(synthetic, listOrchestrators(), { onlineOnly: false });
+  if (!owner) return { ok: false, status: 409, error: "no orchestrator owns this repo path" };
+  const command = createCommand({
+    type: "workspace.unpublish-review",
+    source: "system",
+    target: owner.agentId,
+    correlationId: fields.workspaceId,
+    params: {
+      action: "unpublish-review",
+      workspaceId: fields.workspaceId,
+      repoRoot: fields.repoRoot,
+      ...(fields.worktreePath ? { worktreePath: fields.worktreePath } : {}),
+      ...(fields.branch ? { branch: fields.branch } : {}),
+      ...(fields.ref ? { ref: fields.ref } : {}),
+      requestedBy,
+      requestedAt: Date.now(),
+      queued: owner.status !== "online",
+    },
+  });
+  return { ok: true, command };
+}
+
+// Build a `workspace.deps-refresh` command for a worktree's owning orchestrator
+// (issue #51). checkOnly just reports staleness. Same owner-resolution as cleanup.
+function buildWorkspaceDepsRefreshCommand(
+  workspace: WorkspaceRecord,
+  requestedBy: string,
+  checkOnly: boolean,
+): { ok: true; command: Command } | { ok: false; status: number; error: string } {
+  const owner = workspaceOwnerOrchestrator(workspace, listOrchestrators(), { onlineOnly: false });
+  if (!owner) return { ok: false, status: 409, error: "no online orchestrator owns this workspace path" };
+  const command = createCommand({
+    type: "workspace.deps-refresh",
+    source: "system",
+    target: owner.agentId,
+    correlationId: workspace.id,
+    params: {
+      action: "deps-refresh",
+      workspaceId: workspace.id,
+      repoRoot: workspace.repoRoot,
+      worktreePath: workspace.worktreePath,
+      checkOnly,
+      requestedBy,
+      requestedAt: Date.now(),
+      queued: owner.status !== "online",
+    },
+  });
+  return { ok: true, command };
+}
+
+const DEFAULT_WORKSPACE_WAIT_MS = 300_000;
+const MAX_WORKSPACE_WAIT_MS = 600_000;
+
+interface WaitForWorkspaceResult {
+  workspace: WorkspaceRecord | null;
+  /** The status when the wait began. */
+  fromStatus?: WorkspaceStatus;
+  /** True when the status changed before the deadline (the actionable signal). */
+  transitioned: boolean;
+  /** True when the deadline was reached without a transition. */
+  timedOut: boolean;
+}
+
+// A land that completed BEFORE this wait was issued (#288): the terminal
+// `merge_planned → recycled-active` (or `merged`) hop fires in the gap between
+// the agent's previous wait returning and this one starting. The status has
+// already settled by the time we capture the baseline, so a plain edge-triggered
+// poll never sees a change and blocks to the deadline — the agent mis-reads the
+// landed branch as a 300s stall. `mergedAt` is stamped on every land (the
+// `workspace.merge` command handler in routes.ts); we report each land at most
+// once by acking its timestamp into `landReportedAt`. Returns the unacked land
+// timestamp, or null when there's no fresh land to deliver. Only `active`/`merged`
+// qualify — a fresh, never-landed `active` row has no `mergedAt`, so it can't
+// false-fire.
+function pendingLandTimestamp(ws: WorkspaceRecord): number | null {
+  if (ws.status !== "active" && ws.status !== "merged" && ws.status !== "landed") return null;
+  const mergedAt = typeof ws.metadata?.mergedAt === "number" ? ws.metadata.mergedAt : null;
+  if (mergedAt == null) return null;
+  const reportedAt = typeof ws.metadata?.landReportedAt === "number" ? ws.metadata.landReportedAt : 0;
+  return mergedAt > reportedAt ? mergedAt : null;
+}
+
+// Mark a land as delivered so a subsequent wait won't replay it. Metadata-only
+// (no status churn / steward election) — pure bookkeeping on the same row.
+async function ackLand(id: string, mergedAt: number): Promise<void> {
+  await patchWorkspaceMetadataAsync(id, { landReportedAt: mergedAt });
+}
+
+// Long-poll a workspace until its status changes (the actionable signal after a
+// `ready`: the auto-merge job either lands it → `merged`/recycled-to-`active`, or
+// stalls into `conflict`/`review_requested`), or until the deadline. A plain
+// handler-side poll loop — no workspace event bus exists, and this stays correct
+// and cheap. `sleep` is injectable so tests don't wait real time.
+export async function waitForWorkspaceStatus(
+  id: string,
+  opts: { timeoutMs?: number; pollMs?: number; sleep?: (ms: number) => Promise<void> } = {},
+): Promise<WaitForWorkspaceResult> {
+  const timeoutMs = Math.min(Math.max(opts.timeoutMs ?? DEFAULT_WORKSPACE_WAIT_MS, 0), MAX_WORKSPACE_WAIT_MS);
+  const pollMs = opts.pollMs ?? 750;
+  const sleep = opts.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+
+  const start = getWorkspace(id);
+  if (!start) return { workspace: null, transitioned: false, timedOut: false };
+
+  // Lost-wakeup guard (#288): if the land already settled before we captured the
+  // baseline, deliver it immediately instead of polling for an edge that's in the
+  // past. Report `fromStatus: "merge_planned"` so `landReceipt` produces the land
+  // confirmation — the truthful prior state of a freshly-recycled row.
+  const racedLand = pendingLandTimestamp(start);
+  if (racedLand != null) {
+    await ackLand(id, racedLand);
+    return { workspace: start, fromStatus: "merge_planned", transitioned: true, timedOut: false };
+  }
+  const fromStatus = start.status;
+  let observedStatus = start.status;
+  const deadline = Date.now() + timeoutMs;
+
+  let current = start;
+  while (Date.now() < deadline) {
+    const remaining = deadline - Date.now();
+    await sleep(Math.min(pollMs, Math.max(0, remaining)));
+    const next = getWorkspace(id);
+    if (!next) return { workspace: null, fromStatus, transitioned: false, timedOut: false };
+    current = next;
+    if (current.status !== observedStatus) {
+      // gate_running and merging are progress within one land attempt, not a settled answer to the
+      // caller waiting for that land. Keep polling until the row leaves the in-flight pipeline.
+      if (LAND_IN_FLIGHT_STATUSES.has(observedStatus) && LAND_IN_FLIGHT_STATUSES.has(current.status)) {
+        observedStatus = current.status;
+        continue;
+      }
+      // Ack a land we observed live, so a follow-up wait doesn't replay it.
+      const landedAt = pendingLandTimestamp(current);
+      if (landedAt != null) await ackLand(id, landedAt);
+      return { workspace: current, fromStatus, transitioned: true, timedOut: false };
+    }
+  }
+  return { workspace: current, fromStatus, transitioned: false, timedOut: true };
+}