agent-relay-server 0.10.20 → 0.10.21

package/src/routes.ts

@@ -80,10 +80,12 @@ import {
   getOrchestrator,
   listOrchestrators,
   orchestratorHeartbeat,
+  setOrchestratorUpgradeState,
   updateManagedAgents,
   getWorkspace,
   listWorkspaces,
   updateWorkspaceStatus,
+  deleteWorkspace,
   deleteOrchestrator,
   evaluatePoolBindings,
   findMessageByTelegramSource,
@@ -133,7 +135,7 @@ import {
   updateAutomation,
   type AutomationDispatchResult,
 } from "./automations";
-import type { ActivityEventInput, ActivityKind, AgentCard, AgentKind, AgentProfile, AgentSessionGuard, ChannelBinding, ChannelBindingMode, ChannelDirection, ChannelRouteTarget, ChannelSummary, Command, CommandStatus, CreateCommandInput, CreatePairInput, IntegrationEventInput, IntegrationSummary, ManagedAgent, ManagedSessionExitDiagnostics, Message, OrchestratorRuntimeInput, PairActionInput, PairMessageInput, PairStatus, RegisterAgentInput, RegisterOrchestratorInput, SendMessageInput, SpawnApprovalMode, SpawnPolicy, SpawnProvider, TaskStatus, TaskStatusInput, WorkspaceMetadata, WorkspaceMode, WorkspaceProbe, WorkspaceStatus } from "./types";
+import type { ActivityEventInput, ActivityKind, AgentCard, AgentKind, AgentProfile, AgentSessionGuard, ChannelBinding, ChannelBindingMode, ChannelDirection, ChannelRouteTarget, ChannelSummary, Command, CommandStatus, CreateCommandInput, CreatePairInput, IntegrationEventInput, IntegrationSummary, ManagedAgent, ManagedSessionExitDiagnostics, Message, OrchestratorRuntimeInput, PairActionInput, PairMessageInput, PairStatus, RegisterAgentInput, RegisterOrchestratorInput, SendMessageInput, SpawnApprovalMode, SpawnPolicy, SpawnProvider, TaskStatus, TaskStatusInput, WorkspaceMetadata, WorkspaceMode, WorkspaceOrphan, WorkspaceProbe, WorkspaceStatus } from "./types";
 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";
@@ -309,7 +311,7 @@ const VALID_AGENT_STATUSES = ["online", "idle", "busy", "stale", "offline"] as c
 const VALID_AGENT_KINDS = ["provider", "channel", "orchestrator", "system", "user"] as const;
 const VALID_CHANNEL_BINDING_TARGET_TYPES = ["agent", "label", "tag", "capability", "broadcast", "orchestrator", "pool", "policy"] as const;
 const VALID_WORKSPACE_MODES = ["isolated", "shared", "inherit"] as const;
-const VALID_WORKSPACE_STATUSES = ["active", "ready", "conflict", "review_requested", "merge_planned", "abandoned", "cleanup_requested", "cleaned"] as const;
+const VALID_WORKSPACE_STATUSES = ["active", "ready", "conflict", "review_requested", "merge_planned", "merged", "abandoned", "cleanup_requested", "cleaned"] as const;
 const VALID_CHANNEL_BINDING_MODES = ["exclusive", "broadcast"] as const;
 const VALID_AGENT_ACTIONS = ["restart", "shutdown", "reconnect", "compact", "clearContext"] as const;
 const VALID_AGENT_SPAWN_PROVIDERS = ["codex"] as const;
@@ -3041,6 +3043,7 @@ const postOrchestrator: Handler = async (req) => {
       providerCatalog: providerCatalog as RegisterOrchestratorInput["providerCatalog"],
       meta,
     });
+    reconcileOrchestratorUpgrade(orch);
 	    auditEvent({
       clientId: "server-orchestrator-register-" + id + "-" + Date.now(),
       kind: "state",
@@ -3096,6 +3099,7 @@ const postOrchestratorHeartbeat: Handler = async (req, params) => {
     }
     const orch = orchestratorHeartbeat(params.id!, runtime);
     if (!orch) return error("orchestrator not found", 404);
+    reconcileOrchestratorUpgrade(orch);
     return json({ ok: true });
   } catch (e) {
     if (e instanceof ValidationError) return error(e.message, 400);
@@ -3443,6 +3447,64 @@ const postOrchestratorSpawn: Handler = async (req, params) => {
   }
 };
 
+const ORCH_UPGRADE_DEADLINE_MS = 5 * 60_000;
+const ORCH_UPGRADE_SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+const VALID_ORCH_UPGRADE_PROVIDERS = ["auto", "all", "codex", "claude", "orchestrator"] as const;
+
+function semverCore(v: string): [number, number, number] | null {
+  const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v);
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+
+function compareSemverCore(a: string, b: string): number {
+  const ca = semverCore(a), cb = semverCore(b);
+  if (!ca || !cb) return 0;
+  for (let i = 0; i < 3; i++) if (ca[i] !== cb[i]) return ca[i]! - cb[i]!;
+  return 0;
+}
+
+/**
+ * Settle an in-flight orchestrator upgrade by comparing the version the
+ * orchestrator now reports against the desired version (decision 2a). Called on
+ * every register/heartbeat — the only signal that survives the self-restart.
+ */
+function reconcileOrchestratorUpgrade(orch: ReturnType<typeof getOrchestrator>): void {
+  if (!orch) return;
+  const up = orch.upgrade;
+  if (!up || up.status !== "pending") return;
+  const reported = orch.version;
+  if (reported && reported === up.desiredVersion) {
+    if (up.commandId) updateCommand(up.commandId, { status: "succeeded", result: { version: reported, ...(up.fromVersion ? { fromVersion: up.fromVersion } : {}) } });
+    setOrchestratorUpgradeState(orch.id, { ...up, status: "succeeded", settledAt: Date.now() });
+    auditEvent({
+      clientId: `server-orchestrator-upgraded-${orch.id}-${Date.now()}`,
+      kind: "state",
+      title: "Orchestrator upgraded",
+      body: `${up.fromVersion ?? "?"} → ${reported}`,
+      meta: orch.id,
+      icon: "ti-arrow-up-circle",
+      view: "orchestrators",
+      metadata: { orchestratorId: orch.id, version: reported, commandId: up.commandId },
+    });
+    emitOrchestratorStatus(orch.id);
+  } else if (Date.now() - up.requestedAt > ORCH_UPGRADE_DEADLINE_MS) {
+    const errMsg = `upgrade timed out; orchestrator still reports ${reported ?? "unknown"} (wanted ${up.desiredVersion})`;
+    if (up.commandId) updateCommand(up.commandId, { status: "failed", error: errMsg });
+    setOrchestratorUpgradeState(orch.id, { ...up, status: "failed", settledAt: Date.now(), error: errMsg });
+    auditEvent({
+      clientId: `server-orchestrator-upgrade-failed-${orch.id}-${Date.now()}`,
+      kind: "state",
+      title: "Orchestrator upgrade failed",
+      body: errMsg,
+      meta: orch.id,
+      icon: "ti-alert-triangle",
+      view: "orchestrators",
+      metadata: { orchestratorId: orch.id, commandId: up.commandId },
+    });
+    emitOrchestratorStatus(orch.id);
+  }
+}
+
 const postOrchestratorAction: Handler = async (req, params) => {
   const parsed = await parseBody<unknown>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);
@@ -3451,8 +3513,52 @@ const postOrchestratorAction: Handler = async (req, params) => {
     if (!orch) return error("orchestrator not found", 404);
 
     if (!isRecord(parsed.body)) return error("body required");
-    const action = cleanEnum(parsed.body.action, "action", ["restart", "shutdown"] as const);
+    const action = cleanEnum(parsed.body.action, "action", ["restart", "shutdown", "upgrade"] as const);
     if (!action) return error("action required");
+
+    if (action === "upgrade") {
+      const denied = authorizeRoute(req, { scope: "command:write", resource: { orchestratorId: orch.id } });
+      if (denied) return denied;
+      const targetVersion = cleanString(parsed.body.targetVersion, "targetVersion", { max: 80 }) ?? VERSION;
+      if (!ORCH_UPGRADE_SEMVER_RE.test(targetVersion)) return error("targetVersion must be a semver like 0.10.20");
+      const force = parsed.body.force === true;
+      const providers = (cleanStringArray(parsed.body.providers, "providers") ?? ["orchestrator"])
+        .filter((p) => (VALID_ORCH_UPGRADE_PROVIDERS as readonly string[]).includes(p));
+      if (!providers.length) return error(`providers must be any of: ${VALID_ORCH_UPGRADE_PROVIDERS.join(", ")}`);
+      if (!force && orch.version && compareSemverCore(targetVersion, orch.version) < 0) {
+        return error(`refusing downgrade ${orch.version} → ${targetVersion}; pass force to override`, 409);
+      }
+      const requestedAt = Date.now();
+      const command = createCommand({
+        type: "orchestrator.upgrade",
+        source: "system",
+        target: orch.agentId,
+        ttlMs: ORCH_UPGRADE_DEADLINE_MS + 5 * 60_000,
+        params: { targetVersion, providers, force, orchestratorId: orch.id, requestedBy: "dashboard", requestedAt },
+      });
+      setOrchestratorUpgradeState(orch.id, {
+        desiredVersion: targetVersion,
+        status: "pending",
+        commandId: command.id,
+        providers,
+        ...(orch.version ? { fromVersion: orch.version } : {}),
+        requestedBy: "dashboard",
+        requestedAt,
+      });
+      emitCommand(command);
+      emitOrchestratorStatus(orch.id);
+      auditEvent({
+        clientId: `server-orchestrator-upgrade-${orch.id}-${command.id}`,
+        kind: "state",
+        title: "Orchestrator upgrade requested",
+        body: `${orch.version ?? "?"} → ${targetVersion}`,
+        meta: orch.id,
+        icon: "ti-arrow-up-circle",
+        view: "orchestrators",
+        metadata: { orchestratorId: orch.id, targetVersion, providers, commandId: command.id, ...authAuditMetadata(req) },
+      });
+      return json({ ok: true, action, command, targetVersion }, 202);
+    }
     const agentId = cleanString(parsed.body.agentId, "agentId", { max: 240 });
     const policyName = cleanString(parsed.body.policyName, "policyName", { max: 120 });
     const spawnRequestId = cleanString(parsed.body.spawnRequestId, "spawnRequestId", { max: 160 });
@@ -3558,6 +3664,135 @@ const getWorkspaceById: Handler = (_req, params) => {
   return json(workspace);
 };
 
+// Proxy a read-only workspace interrogation to the owning orchestrator's host
+// API. Degrades to { available: false } rather than erroring so the dashboard
+// can render a placeholder when the host is offline or there's no worktree.
+async function proxyWorkspaceHostGet(workspaceId: string, hostPath: string, extraQuery?: Record<string, string>): Promise<Response> {
+  const workspace = getWorkspace(workspaceId);
+  if (!workspace) return error("workspace not found", 404);
+  if (workspace.mode !== "isolated" || !workspace.worktreePath) {
+    return json({ available: false, reason: "no isolated worktree" });
+  }
+  const orch = listOrchestrators().find(
+    (candidate) => candidate.status === "online" && candidate.apiUrl && pathWithinBase(workspace.sourceCwd, candidate.baseDir),
+  );
+  if (!orch?.apiUrl) return json({ available: false, reason: "owning orchestrator offline" });
+  const query = new URLSearchParams({ path: workspace.worktreePath });
+  if (workspace.baseRef) query.set("baseRef", workspace.baseRef);
+  if (workspace.baseSha) query.set("baseSha", workspace.baseSha);
+  for (const [key, value] of Object.entries(extraQuery ?? {})) query.set(key, value);
+  const headers: Record<string, string> = {};
+  const relayToken = process.env.AGENT_RELAY_TOKEN;
+  if (relayToken) headers["X-Agent-Relay-Token"] = relayToken;
+  try {
+    const res = await fetch(`${orch.apiUrl}${hostPath}?${query.toString()}`, {
+      headers,
+      signal: AbortSignal.timeout(10_000),
+    });
+    const body = await res.text();
+    return new Response(body, { status: res.status, headers: { "Content-Type": res.headers.get("content-type") || "application/json" } });
+  } catch (e) {
+    return json({ available: false, reason: `orchestrator unreachable: ${(e as Error).message}` });
+  }
+}
+
+// Live git state of a workspace's worktree (ahead/behind/dirty/last commit).
+const getWorkspaceGitState: Handler = (_req, params) => proxyWorkspaceHostGet(params.id!, "/api/workspace/state");
+
+// Pre-flight check for merging a workspace: clean-ff vs would-conflict, plus
+// the strategy `auto` would choose. Lets the dashboard warn before merging.
+const getWorkspaceMergePreview: Handler = (req, params) => {
+  const strategy = new URL(req.url).searchParams.get("strategy");
+  return proxyWorkspaceHostGet(params.id!, "/api/workspace/merge-preview", strategy ? { strategy } : undefined);
+};
+
+// Diff of a workspace's committed work against base — per-file line counts and
+// a capped unified patch, so work can be eyeballed without an SSH session.
+const getWorkspaceDiff: Handler = (req, params) => {
+  const patch = new URL(req.url).searchParams.get("patch");
+  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.
+const getWorkspaceOrphans: Handler = async () => {
+  const orchestrators = listOrchestrators().filter((orch) => orch.status === "online" && orch.apiUrl);
+  if (!orchestrators.length) return json({ orphans: [], reason: "no online orchestrators" });
+  const all = listWorkspaces();
+  const repoRoots = [...new Set(all.map((ws) => ws.repoRoot).filter(Boolean))];
+  const headers: Record<string, string> = {};
+  const relayToken = process.env.AGENT_RELAY_TOKEN;
+  if (relayToken) headers["X-Agent-Relay-Token"] = relayToken;
+  const orphans: WorkspaceOrphan[] = [];
+
+  for (const repoRoot of repoRoots) {
+    const orch = orchestrators.find((candidate) => candidate.apiUrl && pathWithinBase(repoRoot, candidate.baseDir));
+    if (!orch?.apiUrl) continue;
+    let probe: WorkspaceProbe | undefined;
+    try {
+      const res = await fetch(`${orch.apiUrl}/api/workspace/probe?path=${encodeURIComponent(repoRoot)}`, { headers, signal: AbortSignal.timeout(10_000) });
+      if (!res.ok) continue;
+      probe = await res.json() as WorkspaceProbe;
+    } catch {
+      continue;
+    }
+    const rowsByPath = new Map(all.filter((ws) => ws.repoRoot === repoRoot && ws.worktreePath).map((ws) => [resolve(ws.worktreePath), ws]));
+    for (const worktree of probe?.worktrees ?? []) {
+      if (!worktree.path || resolve(worktree.path) === resolve(repoRoot)) continue;
+      // Only agent-relay-created worktrees (agent/* branches) are reclaimable —
+      // never touch a user's own linked worktrees.
+      if (!worktree.branch?.startsWith("agent/")) continue;
+      const row = rowsByPath.get(resolve(worktree.path));
+      if (row && !TERMINAL_WORKSPACE_STATUSES.has(row.status)) continue; // tracked & live
+      orphans.push({ worktreePath: worktree.path, repoRoot, branch: worktree.branch, headSha: worktree.headSha, hadTerminalRow: Boolean(row) });
+    }
+  }
+  return json({ orphans });
+};
+
+const postWorkspaceOrphanReclaim: Handler = async (req) => {
+  const denied = authorizeRoute(req, { scope: "command:write" });
+  if (denied) return denied;
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    if (!isRecord(parsed.body)) return error("body required");
+    const worktreePath = cleanString(parsed.body.worktreePath, "worktreePath", { max: 1000 });
+    const repoRoot = cleanString(parsed.body.repoRoot, "repoRoot", { max: 1000 });
+    const branch = cleanString(parsed.body.branch, "branch", { max: 240 });
+    if (!worktreePath || !repoRoot) return error("worktreePath and repoRoot required", 400);
+    // Refuse to reclaim a path that still backs a live workspace row.
+    const live = listWorkspaces().find((ws) => ws.worktreePath && resolve(ws.worktreePath) === resolve(worktreePath) && !TERMINAL_WORKSPACE_STATUSES.has(ws.status));
+    if (live) return error(`path backs live workspace ${live.id}; clean it through the workspace, not orphan reclaim`, 409);
+    const orch = listOrchestrators().find((candidate) => candidate.status === "online" && pathWithinBase(repoRoot, candidate.baseDir));
+    if (!orch) return error("no online orchestrator owns this path", 409);
+    const command = createCommand({
+      type: "workspace.cleanup",
+      source: "system",
+      target: orch.agentId,
+      params: { action: "cleanup", worktreePath, repoRoot, branch, deleteBranch: true, reclaim: true, requestedBy: "dashboard", requestedAt: Date.now() },
+    });
+    emitCommand(command);
+    auditEvent({
+      clientId: `workspace-orphan-reclaim-${Date.now()}`,
+      kind: "state",
+      title: "Workspace orphan reclaim",
+      body: worktreePath,
+      meta: branch ?? repoRoot,
+      icon: "ti-trash",
+      view: "orchestrators",
+      metadata: { worktreePath, repoRoot, branch, commandId: command.id, ...authAuditMetadata(req) },
+    });
+    return json({ command }, 202);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
 const postWorkspaceAction: Handler = async (req, params) => {
   const parsed = await parseBody<unknown>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);
@@ -3565,12 +3800,18 @@ 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 = cleanEnum(parsed.body.action, "action", ["status", "ready", "conflict-found", "request-review", "merge-plan", "abandon", "cleanup"] as const);
+    const action = cleanEnum(parsed.body.action, "action", ["status", "ready", "conflict-found", "request-review", "merge-plan", "merge", "abandon", "cleanup"] as const);
     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 denied = authorizeRoute(req, { scope: action === "cleanup" ? "command:write" : "agent:write", resource: { agentId, cwd: workspace.worktreePath } });
+    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.
+    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);
     const statusByAction: Record<string, WorkspaceStatus | undefined> = {
@@ -3579,6 +3820,7 @@ const postWorkspaceAction: Handler = async (req, params) => {
       "conflict-found": "conflict",
       "request-review": "review_requested",
       "merge-plan": "merge_planned",
+      merge: "merge_planned",
       abandon: "abandoned",
       cleanup: "cleanup_requested",
     };
@@ -3591,23 +3833,52 @@ const postWorkspaceAction: Handler = async (req, params) => {
     });
     if (!updated) return error("workspace not found", 404);
     let command: Command | undefined;
-    if (action === "cleanup") {
-      const orch = listOrchestrators().find((candidate) => candidate.status === "online" && pathWithinBase(workspace.sourceCwd, candidate.baseDir));
-      if (!orch) return error("no online orchestrator available for workspace cleanup", 409);
-      command = createCommand({
-        type: "workspace.cleanup",
-        source: "system",
-        target: orch.agentId,
-        correlationId: workspace.id,
-        params: {
-          action: "cleanup",
-          workspaceId: workspace.id,
-          repoRoot: workspace.repoRoot,
-          worktreePath: workspace.worktreePath,
-          requestedBy: agentId ?? "dashboard",
-          requestedAt: Date.now(),
-        },
-      });
+    if (requiresCommand) {
+      // All orchestrators whose baseDir contains the workspace; prefer an online one.
+      const owners = listOrchestrators().filter((candidate) => pathWithinBase(workspace.sourceCwd, candidate.baseDir));
+      const onlineOwner = owners.find((candidate) => candidate.status === "online");
+      const baseParams = {
+        workspaceId: workspace.id,
+        repoRoot: workspace.repoRoot,
+        worktreePath: workspace.worktreePath,
+        branch: workspace.branch,
+        requestedBy: agentId ?? "dashboard",
+        requestedAt: Date.now(),
+      };
+      if (action === "merge") {
+        // Merge needs a live host: rebasing against a stale base later is unsafe.
+        if (!onlineOwner) return error("no online orchestrator available for workspace merge", 409);
+        const strategy = cleanEnum(parsed.body.strategy, "strategy", ["pr", "rebase-ff", "auto"] as const, "auto");
+        command = createCommand({
+          type: "workspace.merge",
+          source: "system",
+          target: onlineOwner.agentId,
+          correlationId: workspace.id,
+          params: {
+            action: "merge",
+            ...baseParams,
+            baseRef: workspace.baseRef,
+            baseSha: workspace.baseSha,
+            strategy,
+            deleteBranch: parsed.body.deleteBranch !== false,
+            prTitle: cleanString(parsed.body.prTitle, "prTitle", { max: 240 }),
+            prBody: cleanString(parsed.body.prBody, "prBody", { max: 8000 }),
+          },
+        });
+      } else {
+        // Cleanup may queue: if the owning orchestrator is offline, the command
+        // (no TTL) waits and reconciles when it reconnects. Only hard-fail when
+        // no orchestrator owns the path at all — then DELETE is the escape.
+        const owner = onlineOwner ?? owners[0];
+        if (!owner) return error("no orchestrator owns this workspace path; use DELETE /api/workspaces/:id to purge the record", 409);
+        command = createCommand({
+          type: "workspace.cleanup",
+          source: "system",
+          target: owner.agentId,
+          correlationId: workspace.id,
+          params: { action: "cleanup", ...baseParams, deleteBranch: true, queued: owner.status !== "online" },
+        });
+      }
       emitCommand(command);
     }
     auditEvent({
@@ -3616,18 +3887,40 @@ const postWorkspaceAction: Handler = async (req, params) => {
       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",
+      icon: action === "cleanup" ? "ti-trash" : action === "merge" ? "ti-git-merge" : action === "conflict-found" ? "ti-alert-triangle" : "ti-git-branch",
       view: "orchestrators",
       agentId,
       metadata: { action, workspaceId: workspace.id, repoRoot: workspace.repoRoot, worktreePath: workspace.worktreePath, status: updated.status, commandId: command?.id, ...authAuditMetadata(req) },
     });
-    return json({ workspace: updated, command }, action === "cleanup" ? 202 : 200);
+    return json({ workspace: updated, command }, requiresCommand ? 202 : 200);
   } catch (e) {
     if (e instanceof ValidationError) return error(e.message, 400);
     throw e;
   }
 };
 
+// Last-resort purge of a workspace DB row. Does NOT touch disk — use the
+// cleanup action for that. For stuck rows whose orchestrator is gone for good.
+const deleteWorkspaceById: Handler = (req, params) => {
+  const denied = authorizeRoute(req, { scope: "command:write" });
+  if (denied) return denied;
+  const workspace = getWorkspace(params.id!);
+  if (!workspace) return error("workspace not found", 404);
+  const removed = deleteWorkspace(workspace.id);
+  if (!removed) return error("workspace not found", 404);
+  auditEvent({
+    clientId: `workspace-delete-${workspace.id}-${Date.now()}`,
+    kind: "state",
+    title: "Workspace record purged",
+    body: workspace.worktreePath,
+    meta: workspace.branch ?? workspace.id,
+    icon: "ti-trash",
+    view: "orchestrators",
+    metadata: { workspaceId: workspace.id, repoRoot: workspace.repoRoot, worktreePath: workspace.worktreePath, status: workspace.status, diskUntouched: true, ...authAuditMetadata(req) },
+  });
+  return json({ deleted: true, workspace });
+};
+
 async function proxyOrchestratorGet(req: Request, orchestratorId: string, path: string): Promise<Response> {
   const orch = getOrchestrator(orchestratorId);
   if (!orch) return error("orchestrator not found", 404);
@@ -3907,6 +4200,44 @@ const patchCommand: Handler = async (req, params) => {
         });
       }
     }
+    if (command.type === "workspace.merge") {
+      if (command.status === "succeeded" && isRecord(command.result)) {
+        const workspaceId = cleanString(command.result.workspaceId, "result.workspaceId", { max: 160 });
+        const resultStatus = cleanEnum(command.result.status, "result.status", VALID_WORKSPACE_STATUSES) as WorkspaceStatus | undefined;
+        if (workspaceId && resultStatus) {
+          updateWorkspaceStatus(workspaceId, resultStatus, {
+            mergeResult: command.result,
+            mergeCommandId: command.id,
+            mergedAt: Date.now(),
+          });
+        }
+      } else if (command.status === "failed" && command.correlationId) {
+        // Merge couldn't complete — don't leave it stuck in merge_planned.
+        const current = getWorkspace(command.correlationId);
+        if (current && current.status === "merge_planned") {
+          updateWorkspaceStatus(command.correlationId, "review_requested", {
+            mergeCommandId: command.id,
+            mergeError: command.error ?? "merge failed",
+          });
+        }
+      }
+    }
+    if (command.type === "workspace.reconcile" && command.status === "succeeded" && isRecord(command.result)) {
+      const workspaceId = cleanString(command.result.workspaceId, "result.workspaceId", { max: 160 });
+      const resultStatus = cleanEnum(command.result.status, "result.status", VALID_WORKSPACE_STATUSES) as WorkspaceStatus | undefined;
+      if (workspaceId && resultStatus) {
+        // Only act on workspaces the agent left in a live state; never overwrite
+        // a status a human/agent has since moved on (merge_planned, abandoned, …).
+        const current = getWorkspace(workspaceId);
+        if (current && (current.status === "active" || current.status === "ready")) {
+          updateWorkspaceStatus(workspaceId, resultStatus, {
+            reconcileResult: command.result,
+            reconcileCommandId: command.id,
+            reconciledAt: Date.now(),
+          });
+        }
+      }
+    }
     emitCommand(command);
     auditCommandOutcome(command);
     return json(command);
@@ -5835,8 +6166,15 @@ const routes: Route[] = [
   route("DELETE", "/api/orchestrators/:id", deleteOrchestratorById),
 
   route("GET", "/api/workspaces", getWorkspaces),
+  // Static segments before :id so "/workspaces/orphans" isn't captured as an id.
+  route("GET", "/api/workspaces/orphans", getWorkspaceOrphans),
+  route("POST", "/api/workspaces/orphans/reclaim", postWorkspaceOrphanReclaim),
   route("GET", "/api/workspaces/:id", getWorkspaceById),
+  route("GET", "/api/workspaces/:id/git-state", getWorkspaceGitState),
+  route("GET", "/api/workspaces/:id/merge-preview", getWorkspaceMergePreview),
+  route("GET", "/api/workspaces/:id/diff", getWorkspaceDiff),
   route("POST", "/api/workspaces/:id/actions", postWorkspaceAction),
+  route("DELETE", "/api/workspaces/:id", deleteWorkspaceById),
 
   route("POST", "/api/system/broadcast", postSystemBroadcast),
   route("GET", "/api/recipes", getRecipes),