agent-relay-server 0.21.0 → 0.22.0

package/src/routes.ts

@@ -158,6 +158,7 @@ import type { ActivityEventInput, ActivityKind, AgentCard, AgentKind, AgentProfi
 import { getIntegrationTokens, INTEGRATION_RATE_LIMIT_PER_MINUTE, MAX_BODY_BYTES, VERSION, type IntegrationTokenConfig } from "./config";
 import { CONTRACT_VERSIONS, parseRuntimeCapabilities, parseRuntimeContracts, parseRuntimePackage, type RuntimeCapabilities, type RuntimeContracts, type RuntimePackageMetadata } from "./contracts";
 import { listHostDirectories } from "./agent-spawn";
+import { planSend } from "./agent-ref";
 import { defaultProviderConfig, loadProviderConfig, providerConfigPublic, writeProviderConfig } from "../runner/src/config";
 import type { ProviderConfig } from "../runner/src/adapter";
 import { type ProviderEffort } from "agent-relay-sdk/provider-catalog";
@@ -167,6 +168,14 @@ import { buildManagedSpawnParams, effectiveManagedPolicyWorkspaceMode } from "./
 import { buildSpawnCommand, generateSpawnRequestId, resolveSpawnModelParams, type SpawnModelParams } from "./spawn-command";
 import { requestWorkspaceMerge } from "./workspace-merge";
 import { claimMetadataPatch, workspaceActiveClaim } from "./workspace-claim";
+import {
+  applyWorkspaceAction,
+  buildWorkspaceCleanupCommand,
+  buildWorkspaceDepsRefreshCommand,
+  waitForWorkspaceStatus,
+  WORKSPACE_ACTIONS,
+} from "./workspace-actions";
+import { describeWorkspacePhase, landReceipt, TERMINAL_WORKSPACE_STATUSES } from "./workspace-phase";
 import type { WorkspaceDiagnostics, WorkspaceGitState, WorkspaceRecord } from "./types";
 import {
   getComponentAuth,
@@ -3867,8 +3876,6 @@ const getWorkspaceDiff: Handler = (req, params) => {
   return proxyWorkspaceHostGet(params.id!, "/api/workspace/diff", patch === "0" ? { patch: "0" } : undefined);
 };
 
-const TERMINAL_WORKSPACE_STATUSES = new Set<WorkspaceStatus>(["cleaned", "merged", "abandoned"]);
-
 // Worktrees found on disk (agent/* branches) with no live workspace row — left
 // behind by crashes or failed cleanups. Probes each known repo's owning host
 // and subtracts active DB rows. Reclaim them via POST .../orphans/reclaim.
@@ -3947,59 +3954,8 @@ const postWorkspaceOrphanReclaim: Handler = async (req) => {
   }
 };
 
-// Build a `workspace.cleanup` command for a worktree's owning orchestrator. Shared
-// by the manual cleanup action and the cleanup-stale sweep (#208) so both resolve
-// the owner and shape params identically. Queues (no TTL) when the owner is offline;
-// hard-fails only when no orchestrator owns the path (DELETE is then the escape).
-function buildWorkspaceCleanupCommand(workspace: WorkspaceRecord, requestedBy: string): { ok: true; command: Command } | { ok: false; status: number; error: string } {
-  const owners = listOrchestrators().filter((candidate) => isPathWithinBase(workspace.sourceCwd, candidate.baseDir));
-  const owner = owners.find((candidate) => candidate.status === "online") ?? owners[0];
-  if (!owner) return { ok: false, status: 409, error: "no orchestrator owns this workspace path; use DELETE /api/workspaces/:id to purge the record" };
-  const command = createCommand({
-    type: "workspace.cleanup",
-    source: "system",
-    target: owner.agentId,
-    correlationId: workspace.id,
-    params: {
-      action: "cleanup",
-      workspaceId: workspace.id,
-      repoRoot: workspace.repoRoot,
-      worktreePath: workspace.worktreePath,
-      branch: workspace.branch,
-      requestedBy,
-      requestedAt: Date.now(),
-      deleteBranch: true,
-      queued: owner.status !== "online",
-    },
-  });
-  return { ok: true, command };
-}
-
-// Build a `workspace.deps-refresh` command for a worktree's owning orchestrator
-// (issue #51). Re-provisions deps the shared symlinked node_modules has gone stale
-// on, or — 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 owners = listOrchestrators().filter((candidate) => isPathWithinBase(workspace.sourceCwd, candidate.baseDir));
-  const owner = owners.find((candidate) => candidate.status === "online") ?? owners[0];
-  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 };
-}
+// buildWorkspaceCleanupCommand / buildWorkspaceDepsRefreshCommand now live in
+// ./workspace-actions (shared with the relay_workspace_* MCP tools) — imported above.
 
 // Fetch + parse a workspace's live git state from its owning host, or report why
 // it's unavailable. Thin typed wrapper over the same host route the proxy uses.
@@ -4037,6 +3993,13 @@ function recommendWorkspaceAction(input: { workspace: WorkspaceRecord; ownerOnli
   if ((gitState.dirtyCount ?? 0) > 0) return { action: "review", confidence: "medium", reason: `${gitState.dirtyCount} uncommitted change(s)` };
   if (ahead === 0 || landed) {
     if (!ownerOnline) return { action: "cleanup", confidence: "high", reason: landed ? "work already landed; owner offline" : "no unmerged commits; owner offline" };
+    // Owner active but the workspace is awaiting attention with nothing to land (#230):
+    // landing it is a safe no-op that resolves it to terminal `merged`, clearing the
+    // queue (the host keeps a live owner's worktree). Otherwise there's genuinely
+    // nothing to do.
+    if (workspace.status === "review_requested" || workspace.status === "conflict") {
+      return { action: "merge", confidence: "high", reason: landed ? "work already landed; resolve the no-op" : "nothing to merge; resolve the no-op" };
+    }
     return { action: "none", confidence: "medium", reason: "nothing to merge; owner active" };
   }
   if (ownerOnline && workspace.status !== "review_requested" && workspace.status !== "conflict") {
@@ -4139,129 +4102,64 @@ const postWorkspaceAction: Handler = async (req, params) => {
     if (!isRecord(parsed.body)) return error("body required");
     const workspace = getWorkspace(params.id!);
     if (!workspace) return error("workspace not found", 404);
-    const action = optionalEnum(parsed.body.action, "action", ["status", "ready", "conflict-found", "request-review", "merge-plan", "merge", "abandon", "cleanup", "claim", "release-claim", "deps-refresh"] as const);
+    const action = optionalEnum(parsed.body.action, "action", WORKSPACE_ACTIONS);
     if (!action) return error("action required", 400);
     const agentId = cleanString(parsed.body.agentId, "agentId", { max: 240 });
-    const detail = cleanString(parsed.body.detail, "detail", { max: 4000 });
-    const metadata = cleanMeta(parsed.body.metadata) ?? {};
     const requiresCommand = action === "cleanup" || action === "merge";
-    // Shared-mode rows are occupancy markers with no worktree — there is nothing
-    // on disk to merge or clean. Reject host commands against them up front.
+    // Shared-mode rows are occupancy markers with no worktree — reject host commands
+    // up front, before authz, preserving the original 422-before-auth ordering.
     if (requiresCommand && (workspace.mode !== "isolated" || !workspace.worktreePath)) {
       return error(`workspace ${workspace.id} has no worktree to ${action}`, 422);
     }
     const denied = authorizeRoute(req, { scope: requiresCommand ? "command:write" : "agent:write", resource: { agentId, cwd: workspace.worktreePath } });
     if (denied) return denied;
-    if (action === "status") return json(workspace);
-    // 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 purpose = cleanString(parsed.body.purpose, "purpose", { max: 120 });
-      const updated = patchWorkspaceMetadata(workspace.id, claimMetadataPatch(release, agentId ?? "steward", purpose));
-      if (!updated) return error("workspace not found", 404);
-      auditEvent({
-        clientId: `workspace-${action}-${workspace.id}-${Date.now()}`,
-        kind: "state",
-        title: release ? "Workspace claim released" : "Workspace claimed",
-        body: detail ?? purpose ?? workspace.worktreePath,
-        meta: workspace.branch ?? workspace.id,
-        icon: "ti-lock",
-        view: "orchestrators",
-        agentId,
-        metadata: { action, workspaceId: workspace.id, repoRoot: workspace.repoRoot, ...authAuditMetadata(req) },
-      });
-      return json({ workspace: updated, claim: workspaceActiveClaim(updated) });
-    }
-    // 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") {
-      const strategy = optionalEnum(parsed.body.strategy, "strategy", ["pr", "rebase-ff", "auto"] as const, "auto") as WorkspaceMergeStrategy;
-      const result = requestWorkspaceMerge(workspace, {
-        requestedBy: agentId ?? "dashboard",
-        strategy,
-        deleteBranch: parsed.body.deleteBranch !== false,
-        prTitle: cleanString(parsed.body.prTitle, "prTitle", { max: 240 }),
-        prBody: cleanString(parsed.body.prBody, "prBody", { max: 8000 }),
-        metadata: { ...metadata, ...(detail ? { detail } : {}), ...(agentId ? { updatedByAgentId: agentId } : {}) },
-      });
-      if (!result.ok) return error(result.error, result.status);
-      emitCommand(result.command);
-      auditEvent({
-        clientId: `workspace-merge-${workspace.id}-${Date.now()}`,
-        kind: "state",
-        title: "Workspace merge",
-        body: detail ?? workspace.worktreePath,
-        meta: workspace.branch ?? workspace.id,
-        icon: "ti-git-merge",
-        view: "orchestrators",
-        agentId,
-        metadata: { action: "merge", workspaceId: workspace.id, repoRoot: workspace.repoRoot, worktreePath: workspace.worktreePath, status: result.workspace.status, commandId: result.command.id, ...authAuditMetadata(req) },
-      });
-      return json({ workspace: result.workspace, command: result.command }, 202);
-    }
-    // Deps refresh (#51): self-service for the owning agent — re-provision deps the
-    // shared symlinked node_modules has gone stale on. Emits a host command but is
-    // authorized at agent:write (it only touches the agent's own worktree), so the
-    // agent can run it themselves the moment typecheck reports a missing module.
-    if (action === "deps-refresh") {
-      if (workspace.mode !== "isolated" || !workspace.worktreePath) {
-        return error(`workspace ${workspace.id} has no isolated worktree to refresh`, 422);
+
+    // status: optionally long-poll until the workspace transitions — after a `ready`,
+    // block until the auto-merge job lands it (→ merged/recycled-to-active) or it
+    // stalls into conflict/review_requested, instead of the caller busy-polling.
+    if (action === "status") {
+      if (parsed.body.wait === true) {
+        const timeoutSeconds = typeof parsed.body.timeoutSeconds === "number" && parsed.body.timeoutSeconds > 0 ? parsed.body.timeoutSeconds : undefined;
+        const waited = await waitForWorkspaceStatus(workspace.id, timeoutSeconds ? { timeoutMs: timeoutSeconds * 1000 } : {});
+        if (!waited.workspace) return error("workspace not found", 404);
+        const landed = waited.transitioned ? landReceipt(waited.fromStatus, waited.workspace) : null;
+        // Mirror the relay_workspace_status MCP tool: bare record (legacy fields)
+        // plus the directive projection + land receipt so the CLI `--wait` and any
+        // HTTP caller get the same legible answer.
+        return json({
+          workspace: waited.workspace,
+          guidance: describeWorkspacePhase(waited.workspace),
+          ...(landed ? { landed } : {}),
+          fromStatus: waited.fromStatus,
+          transitioned: waited.transitioned,
+          timedOut: waited.timedOut,
+        });
       }
-      const checkOnly = parsed.body.checkOnly === true;
-      const built = buildWorkspaceDepsRefreshCommand(workspace, agentId ?? "agent", checkOnly);
-      if (!built.ok) return error(built.error, built.status);
-      emitCommand(built.command);
-      auditEvent({
-        clientId: `workspace-deps-refresh-${workspace.id}-${Date.now()}`,
-        kind: "state",
-        title: checkOnly ? "Workspace deps check" : "Workspace deps refresh",
-        body: detail ?? workspace.worktreePath,
-        meta: workspace.branch ?? workspace.id,
-        icon: "ti-package",
-        view: "orchestrators",
-        agentId,
-        metadata: { action, workspaceId: workspace.id, repoRoot: workspace.repoRoot, worktreePath: workspace.worktreePath, checkOnly, commandId: built.command.id, ...authAuditMetadata(req) },
-      });
-      return json({ workspace, command: built.command }, 202);
-    }
-    const statusByAction: Record<string, WorkspaceStatus | undefined> = {
-      status: undefined,
-      ready: "ready",
-      "conflict-found": "conflict",
-      "request-review": "review_requested",
-      "merge-plan": "merge_planned",
-      abandon: "abandoned",
-      cleanup: "cleanup_requested",
-    };
-    const updated = updateWorkspaceStatus(workspace.id, statusByAction[action]!, {
-      ...metadata,
-      ...(detail ? { detail } : {}),
-      ...(agentId ? { updatedByAgentId: agentId } : {}),
-      lastWorkspaceAction: action,
-      lastWorkspaceActionAt: Date.now(),
-    });
-    if (!updated) return error("workspace not found", 404);
-    let command: Command | undefined;
-    if (requiresCommand) {
-      // Only `cleanup` reaches here — `merge` returned early via the shared helper.
-      const built = buildWorkspaceCleanupCommand(workspace, agentId ?? "dashboard");
-      if (!built.ok) return error(built.error, built.status);
-      command = built.command;
-      emitCommand(command);
+      return json(workspace);
     }
-    auditEvent({
-      clientId: `workspace-${action}-${workspace.id}-${Date.now()}`,
-      kind: "state",
-      title: `Workspace ${action}`,
-      body: detail ?? workspace.worktreePath,
-      meta: workspace.branch ?? workspace.id,
-      icon: action === "cleanup" ? "ti-trash" : action === "conflict-found" ? "ti-alert-triangle" : "ti-git-branch",
-      view: "orchestrators",
+
+    // Everything else delegates to the shared core (one home, shared with the
+    // relay_workspace_* MCP tools); the core self-audits and returns any command to
+    // emit, mirroring requestWorkspaceMerge's "caller emits" contract.
+    const result = applyWorkspaceAction(workspace, {
+      action,
       agentId,
-      metadata: { action, workspaceId: workspace.id, repoRoot: workspace.repoRoot, worktreePath: workspace.worktreePath, status: updated.status, commandId: command?.id, ...authAuditMetadata(req) },
+      detail: cleanString(parsed.body.detail, "detail", { max: 4000 }),
+      metadata: cleanMeta(parsed.body.metadata) ?? {},
+      strategy: optionalEnum(parsed.body.strategy, "strategy", ["pr", "rebase-ff", "auto"] as const, "auto") as WorkspaceMergeStrategy,
+      deleteBranch: typeof parsed.body.deleteBranch === "boolean" ? parsed.body.deleteBranch : undefined,
+      prTitle: cleanString(parsed.body.prTitle, "prTitle", { max: 240 }),
+      prBody: cleanString(parsed.body.prBody, "prBody", { max: 8000 }),
+      purpose: cleanString(parsed.body.purpose, "purpose", { max: 120 }),
+      checkOnly: parsed.body.checkOnly === true,
+      auditMetadata: authAuditMetadata(req),
     });
-    return json({ workspace: updated, command }, requiresCommand ? 202 : 200);
+    if (!result.ok) return error(result.error, result.httpStatus);
+    if (result.command) emitCommand(result.command);
+    const payload: Record<string, unknown> = { workspace: result.workspace };
+    if (result.command) payload.command = result.command;
+    if (result.claim !== undefined) payload.claim = result.claim;
+    return json(payload, result.httpStatus);
   } catch (e) {
     if (e instanceof ValidationError) return error(e.message, 400);
     throw e;
@@ -5285,11 +5183,25 @@ const postMessage: Handler = async (req) => {
       resource: { target: input.to, channel: input.channel, agentId: input.from },
     });
     if (denied) return denied;
+    // Resolve the target through the shared planner — the SAME matcher the MCP send tool
+    // uses (planSend → matchAgents) — so a bare label / name / id-segment that matches an
+    // existing agent is rewritten to its canonical id. Poll-time matching is exact, so
+    // without this a bare label is stored verbatim and reaches no one (#234). An ambiguous
+    // direct ref can't be delivered, so reject it up front. Unknown targets are left
+    // untouched on purpose: sending to an id that isn't registered yet is a supported
+    // "store-ahead" pattern (delivered once that agent registers and polls). Fan-out and
+    // reserved/policy targets carry through unchanged (and may legitimately match zero now).
+    //
     // "session" = observed assistant turn (Phase 1 live-session lane). It is captured
     // from the provider transcript and stored for the dashboard chat; it must persist
     // regardless of target liveness and never be re-delivered into a session.
     const bypassKinds = ["system", "control", "session"];
-    if (isDirectTarget(input.to) && !bypassKinds.includes(input.kind ?? "")) {
+    if (!bypassKinds.includes(input.kind ?? "")) {
+      const plan = planSend(input.to, listAgents());
+      if (plan.kind === "ambiguous") return error(plan.message, 409);
+      if (plan.kind !== "not_found") input.to = plan.to;
+      // Long-standing guard: refuse a direct send to a known-offline agent (now also
+      // catches a ref that resolved to an offline agent by label/segment).
       const target = getAgent(input.to);
       if (target && target.status === "offline") {
         return error(`agent "${input.to}" is offline`, 422);

package/src/workspace-actions.ts

@@ -0,0 +1,336 @@
+// 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 { isPathWithinBase } from "./utils";
+import {
+  createActivityEvent,
+  getWorkspace,
+  listOrchestrators,
+  patchWorkspaceMetadata,
+  updateWorkspaceStatus,
+} from "./db";
+import { emitActivityEvent } from "./sse";
+import { requestWorkspaceMerge } from "./workspace-merge";
+import { claimMetadataPatch, workspaceActiveClaim } from "./workspace-claim";
+import type { Command, WorkspaceMergeStrategy, WorkspaceRecord, WorkspaceStatus } from "./types";
+
+// 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",
+  "ready",
+  "conflict-found",
+  "request-review",
+  "merge-plan",
+  "merge",
+  "abandon",
+  "cleanup",
+  "claim",
+  "release-claim",
+  "deps-refresh",
+] as const;
+export type WorkspaceAction = (typeof WORKSPACE_ACTIONS)[number];
+
+export interface ApplyWorkspaceActionInput {
+  action: WorkspaceAction;
+  agentId?: string;
+  detail?: string;
+  metadata?: Record<string, unknown>;
+  // merge
+  strategy?: WorkspaceMergeStrategy;
+  deleteBranch?: boolean;
+  prTitle?: string;
+  prBody?: string;
+  // claim / release-claim
+  purpose?: string;
+  // deps-refresh
+  checkOnly?: boolean;
+  // 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>;
+}
+
+export 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",
+};
+
+// Mirror of routes.ts `auditEvent` (source-tagged, never-throws) so the activity
+// feed gets identical entries whether the action came over HTTP or MCP.
+function recordWorkspaceAudit(a: {
+  action: WorkspaceAction;
+  workspace: WorkspaceRecord;
+  agentId?: string;
+  title: string;
+  body?: string;
+  icon: string;
+  auditMetadata?: Record<string, unknown>;
+  extra?: Record<string, unknown>;
+}): void {
+  try {
+    const event = createActivityEvent({
+      clientId: `workspace-${a.action}-${a.workspace.id}-${Date.now()}`,
+      kind: "state",
+      title: a.title,
+      body: a.body,
+      meta: a.workspace.branch ?? a.workspace.id,
+      icon: a.icon,
+      view: "orchestrators",
+      agentId: a.agentId,
+      metadata: {
+        source: "server",
+        action: a.action,
+        workspaceId: a.workspace.id,
+        repoRoot: a.workspace.repoRoot,
+        worktreePath: a.workspace.worktreePath,
+        ...(a.extra ?? {}),
+        ...(a.auditMetadata ?? {}),
+      },
+    });
+    emitActivityEvent(event);
+  } catch {
+    // Audit trail writes must never block relay behavior.
+  }
+}
+
+export function applyWorkspaceAction(workspace: WorkspaceRecord, input: ApplyWorkspaceActionInput): WorkspaceActionResult {
+  const { action } = input;
+  const agentId = input.agentId;
+  const detail = input.detail;
+  const metadata = input.metadata ?? {};
+  const requiresCommand = action === "cleanup" || action === "merge";
+
+  // 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 };
+  }
+
+  // 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 updated = patchWorkspaceMetadata(workspace.id, claimMetadataPatch(release, agentId ?? "steward", input.purpose));
+    if (!updated) return { ok: false, httpStatus: 404, error: "workspace not found" };
+    recordWorkspaceAudit({
+      action,
+      workspace: updated,
+      agentId,
+      title: release ? "Workspace claim released" : "Workspace claimed",
+      body: detail ?? input.purpose ?? updated.worktreePath,
+      icon: "ti-lock",
+      auditMetadata: input.auditMetadata,
+    });
+    return { ok: true, httpStatus: 200, workspace: updated, claim: workspaceActiveClaim(updated) };
+  }
+
+  // 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") {
+    const result = requestWorkspaceMerge(workspace, {
+      requestedBy: agentId ?? "dashboard",
+      strategy: input.strategy ?? "auto",
+      deleteBranch: input.deleteBranch !== false,
+      prTitle: input.prTitle,
+      prBody: input.prBody,
+      metadata: { ...metadata, ...(detail ? { detail } : {}), ...(agentId ? { updatedByAgentId: agentId } : {}) },
+    });
+    if (!result.ok) return { ok: false, httpStatus: result.status, error: result.error };
+    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 },
+    });
+    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 };
+    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}` };
+
+  const updated = updateWorkspaceStatus(workspace.id, nextStatus, {
+    ...metadata,
+    ...(detail ? { detail } : {}),
+    ...(agentId ? { updatedByAgentId: agentId } : {}),
+    lastWorkspaceAction: action,
+    lastWorkspaceActionAt: Date.now(),
+  });
+  if (!updated) return { ok: false, httpStatus: 404, error: "workspace not found" };
+
+  let command: Command | undefined;
+  if (requiresCommand) {
+    // Only `cleanup` reaches here — `merge` returned early via the shared helper.
+    const built = buildWorkspaceCleanupCommand(workspace, agentId ?? "dashboard");
+    if (!built.ok) return { ok: false, httpStatus: built.status, error: built.error };
+    command = built.command;
+  }
+  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 };
+}
+
+// Build a `workspace.cleanup` command for the worktree's owning orchestrator.
+// Moved here (from routes.ts) so the MCP surface reaches it without importing routes.
+export function buildWorkspaceCleanupCommand(
+  workspace: WorkspaceRecord,
+  requestedBy: string,
+): { ok: true; command: Command } | { ok: false; status: number; error: string } {
+  const owners = listOrchestrators().filter((candidate) => isPathWithinBase(workspace.sourceCwd, candidate.baseDir));
+  const owner = owners.find((candidate) => candidate.status === "online") ?? owners[0];
+  if (!owner) return { ok: false, status: 409, error: "no orchestrator owns this workspace path; use DELETE /api/workspaces/:id to purge the record" };
+  const command = createCommand({
+    type: "workspace.cleanup",
+    source: "system",
+    target: owner.agentId,
+    correlationId: workspace.id,
+    params: {
+      action: "cleanup",
+      workspaceId: workspace.id,
+      repoRoot: workspace.repoRoot,
+      worktreePath: workspace.worktreePath,
+      branch: workspace.branch,
+      requestedBy,
+      requestedAt: Date.now(),
+      deleteBranch: true,
+      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.
+export function buildWorkspaceDepsRefreshCommand(
+  workspace: WorkspaceRecord,
+  requestedBy: string,
+  checkOnly: boolean,
+): { ok: true; command: Command } | { ok: false; status: number; error: string } {
+  const owners = listOrchestrators().filter((candidate) => isPathWithinBase(workspace.sourceCwd, candidate.baseDir));
+  const owner = owners.find((candidate) => candidate.status === "online") ?? owners[0];
+  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 };
+}
+
+export const DEFAULT_WORKSPACE_WAIT_MS = 300_000;
+export const MAX_WORKSPACE_WAIT_MS = 600_000;
+
+export 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;
+}
+
+// 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 };
+  const fromStatus = 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 !== fromStatus) {
+      return { workspace: current, fromStatus, transitioned: true, timedOut: false };
+    }
+  }
+  return { workspace: current, fromStatus, transitioned: false, timedOut: true };
+}