agent-relay-server 0.16.0 → 0.18.0

package/src/routes.ts

@@ -85,6 +85,8 @@ import {
   getWorkspace,
   listWorkspaces,
   updateWorkspaceStatus,
+  setWorkspaceBranch,
+  patchWorkspaceMetadata,
   releaseMergeLease,
   listRepoStewards,
   listMergeLeases,
@@ -96,6 +98,7 @@ import {
   setMessageReaction,
   ValidationError,
 } from "./db";
+import { cleanString } from "./validation";
 import { getArtifactStorage, maxArtifactBytes, normalizeDigest } from "./artifact-storage";
 import {
   deleteConfig,
@@ -108,6 +111,8 @@ import {
   getStewardConfigEntry,
   getInsightsConfigEntry,
   setInsightsConfig,
+  getWorkspaceConfigEntry,
+  setWorkspaceConfig,
   listAgentProfiles,
   listSpawnPolicies,
   listConfig,
@@ -149,10 +154,14 @@ import { CONTRACT_VERSIONS, parseRuntimeCapabilities, parseRuntimeContracts, par
 import { listHostDirectories } from "./agent-spawn";
 import { defaultProviderConfig, loadProviderConfig, providerConfigPublic, writeProviderConfig } from "../runner/src/config";
 import type { ProviderConfig } from "../runner/src/adapter";
-import { resolveProviderSelection, type ProviderEffort } from "agent-relay-sdk/provider-catalog";
+import { type ProviderEffort } from "agent-relay-sdk/provider-catalog";
+import { isRecord, SPAWN_PROVIDERS, VALID_WORKSPACE_MODES, VALID_EFFORTS, APPROVAL_MODES, RELAY_TOKEN_HEADER } from "agent-relay-sdk";
 import { effectiveProviderCatalogList } from "./provider-catalog-store";
 import { buildManagedSpawnParams, effectiveManagedPolicyWorkspaceMode } from "./managed-policy";
+import { buildSpawnCommand, generateSpawnRequestId, resolveSpawnModelParams, type SpawnModelParams } from "./spawn-command";
 import { requestWorkspaceMerge } from "./workspace-merge";
+import { claimMetadataPatch, workspaceActiveClaim } from "./workspace-claim";
+import type { WorkspaceDiagnostics, WorkspaceGitState, WorkspaceRecord } from "./types";
 import {
   getComponentAuth,
   getIntegrationAuth,
@@ -189,7 +198,8 @@ import { assertMemoryCreateAllowed, assertMemoryUpdateAllowed } from "./memory-s
 import { captureTaskResultMemory, clearActiveMemories, injectAlwaysReloadMemories, injectMemoryContext, injectMemoryForMessageDelivery, injectMemoryForTaskClaim, memoryBroker, memoryBrokerConfig } from "./memory-service";
 import { postMcp } from "./mcp";
 import { readFileSync } from "node:fs";
-import { isAbsolute, relative, resolve } from "node:path";
+import { resolve } from "node:path";
+import { isPathWithinBase } from "./utils";
 import type { ArtifactKind, ArtifactSensitivity, AttachmentRef, ContextBudget, CreateMemoryInput, MemoryBrokerContext, MemoryConfidence, MemoryQuery, MemoryRedactionState, MemorySensitivity, MemoryType, MemoryVisibility, TaskRoutingHints, TokenConstraints, UpdateMemoryInput } from "./types";
 import { issueIntegrationRuntimeToken, issueInteractiveRunnerRuntimeToken, issueMcpRuntimeToken, issueOrchestratorRuntimeToken, reissueRunnerRuntimeToken, runnerRuntimeTokenEnv } from "./runtime-tokens";
 import { listMaintenanceJobs, runLegacyMaintenanceReaper, runMaintenanceJobNow } from "./maintenance";
@@ -320,14 +330,10 @@ function parseQueryInt(
 const VALID_AGENT_STATUSES = ["online", "idle", "busy", "stale", "offline"] as const;
 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", "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", "resume", "interrupt"] as const;
 const CLAUDE_RESUME_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-const VALID_AGENT_SPAWN_PROVIDERS = ["codex"] as const;
-const VALID_CODEX_SPAWN_APPROVALS = ["open", "guarded", "read-only"] as const;
-const VALID_PROVIDER_EFFORTS = ["low", "medium", "high", "xhigh", "max"] as const;
 const VALID_CONNECTOR_ACTIONS = ["install", "uninstall", "enable", "disable", "start", "stop", "restart", "status", "doctor"] as const;
 const VALID_TASK_SEVERITIES = ["info", "warning", "critical"] as const;
 const VALID_TASK_STATUSES = ["open", "claimed", "in_progress", "blocked", "orphaned", "done", "failed", "canceled"] as const;
@@ -346,34 +352,6 @@ const VALID_ARTIFACT_SENSITIVITIES = ["public", "normal", "sensitive", "secret"]
 const VALID_ARTIFACT_ROLES = ["media", "patch", "report", "log", "output", "input"] as const;
 const integrationRateBuckets = new Map<string, { windowStart: number; count: number }>();
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function pathWithinBase(path: string, baseDir: string): boolean {
-  const base = resolve(baseDir);
-  const target = resolve(path);
-  const rel = relative(base, target);
-  return rel === "" || (!!rel && !rel.startsWith("..") && !isAbsolute(rel));
-}
-
-function cleanString(
-  value: unknown,
-  field: string,
-  opts: { required?: boolean; max?: number } = {},
-): string | undefined {
-  if (value === undefined || value === null) {
-    if (opts.required) throw new ValidationError(`${field} required`);
-    return undefined;
-  }
-  if (typeof value !== "string") throw new ValidationError(`${field} must be a string`);
-  const trimmed = value.trim();
-  if (opts.required && !trimmed) throw new ValidationError(`${field} required`);
-  if (opts.max && trimmed.length > opts.max) {
-    throw new ValidationError(`${field} must be ${opts.max} characters or fewer`);
-  }
-  return trimmed || undefined;
-}
 
 function cleanNullableString(value: unknown, field: string, max: number): string | null | undefined {
   if (value === undefined) return undefined;
@@ -594,6 +572,12 @@ function normalizeMessageInput(body: unknown): SendMessageInput {
     }
     input.maxAgeSeconds = body.maxAgeSeconds;
   }
+  if (body.occurredAt !== undefined) {
+    if (typeof body.occurredAt !== "number" || !Number.isFinite(body.occurredAt) || body.occurredAt <= 0) {
+      throw new ValidationError("occurredAt must be a positive epoch-ms number");
+    }
+    input.occurredAt = body.occurredAt;
+  }
 
   const channel = cleanString(body.channel, "channel", { max: 120 });
   if (channel) input.channel = channel;
@@ -2272,38 +2256,22 @@ function restartSpawnParamsForAgent(
   const profileName = metaString(agent.meta, "profile");
   const agentProfile = profileName ? getAgentProfile(profileName)?.value : undefined;
   const workspaceMode = metaString(agent.meta, "workspaceMode") ?? "inherit";
-  let resolvedModel: Record<string, string> = {};
-  if (model || effort) {
-    try {
-      const selection = resolveProviderSelection({ provider, model, effort });
-      resolvedModel = {
-        ...(selection.modelAlias ? { model: selection.modelAlias } : {}),
-        ...(selection.providerModel ? { providerModel: selection.providerModel } : {}),
-        ...(selection.effort ? { effort: selection.effort } : {}),
-      };
-    } catch {
-      resolvedModel = {
-        ...(model ? { model } : {}),
-        ...(effort ? { effort } : {}),
-      };
-    }
-  }
-  const params = {
-    action: "spawn",
+  const resolvedModel = resolveSpawnModelParams(provider, model, effort, { onError: "passthrough", skipDefaultWhenEmpty: true });
+  const params = buildSpawnCommand({
     provider,
-    ...resolvedModel,
+    modelParams: resolvedModel,
     cwd,
     workspaceMode,
-    ...(profileName ? { profile: profileName } : {}),
-    ...(agentProfile ? { agentProfile } : {}),
-    ...(label ? { label } : {}),
+    profile: profileName || undefined,
+    agentProfile,
+    label: label || undefined,
     agentId: agent.id,
     tags: agent.tags,
     capabilities: agent.capabilities,
     approvalMode: approvalMode ?? "guarded",
     permissionMode: approvalMode ?? "guarded",
-    ...(providerArgs.length ? { providerArgs } : {}),
-    ...(policyName ? { policyName } : {}),
+    providerArgs: providerArgs.length ? providerArgs : undefined,
+    policyName: policyName || undefined,
     headless: true,
     spawnRequestId: requestId,
     env: runnerRuntimeTokenEnv({
@@ -2317,12 +2285,12 @@ function restartSpawnParamsForAgent(
     }),
     requestedBy,
     requestedAt: Date.now(),
-  };
+  });
   return opts.resumeId ? withClaudeResumeParams(params, opts.resumeId, agent.id) : params;
 }
 
 function spawnRequestIdForRestart(): string {
-  return `sp_${crypto.randomUUID()}`;
+  return generateSpawnRequestId();
 }
 
 function withClaudeResumeParams(params: Record<string, unknown>, resumeId: string, agentId: string): Record<string, unknown> {
@@ -2623,10 +2591,10 @@ const postAgentSpawn: Handler = async (req) => {
   if (!parsed.ok) return error(parsed.error, parsed.status);
   try {
     if (!isRecord(parsed.body)) return error("provider required");
-    const provider = cleanEnum(parsed.body.provider, "provider", [...VALID_AGENT_SPAWN_PROVIDERS, "claude"] as const);
+    const provider = cleanEnum(parsed.body.provider, "provider", SPAWN_PROVIDERS);
     if (!provider) return error("provider required");
     const selection = cleanSpawnSelection(parsed.body, provider as SpawnProvider);
-    const approvalMode = cleanEnum(parsed.body.approvalMode, "approvalMode", VALID_CODEX_SPAWN_APPROVALS, "guarded") as SpawnApprovalMode;
+    const approvalMode = cleanEnum(parsed.body.approvalMode, "approvalMode", APPROVAL_MODES, "guarded") as SpawnApprovalMode;
     const cwd = cleanString(parsed.body.cwd, "cwd", { max: 500 });
     const label = cleanString(parsed.body.label, "label", { max: 120 });
     const workspaceMode = cleanEnum(parsed.body.workspaceMode, "workspaceMode", VALID_WORKSPACE_MODES, "inherit") as WorkspaceMode;
@@ -2636,7 +2604,7 @@ const postAgentSpawn: Handler = async (req) => {
     );
 	    const orch = orchestrators[0];
 	    if (!orch) return error("no orchestrator available for provider: " + provider);
-	    if (cwd && !pathWithinBase(cwd, orch.baseDir)) {
+	    if (cwd && !isPathWithinBase(cwd, orch.baseDir)) {
 	      return error(`cwd must be within orchestrator base directory: ${orch.baseDir}`);
 	    }
 	    const requestId = spawnRequestId();
@@ -2650,10 +2618,9 @@ const postAgentSpawn: Handler = async (req) => {
 	      source: "system",
 	      target: orch.agentId,
 	      correlationId: requestId,
-	      params: {
-	        action: "spawn",
+	      params: buildSpawnCommand({
 	        provider,
-	        ...selection,
+	        modelParams: selection,
 	        cwd: cwd || orch.baseDir,
 	        workspaceMode,
 	        label,
@@ -2669,7 +2636,7 @@ const postAgentSpawn: Handler = async (req) => {
 	          spawnRequestId: requestId,
 	          createdBy: "dashboard",
 	        }),
-	      },
+	      }),
 	    });
     emitCommand(command);
     auditEvent({
@@ -2939,7 +2906,7 @@ const postInteractiveRunnerRuntimeToken: Handler = async (req) => {
   if (!parsed.ok) return error(parsed.error, parsed.status);
   try {
     if (!isRecord(parsed.body)) return error("runtime token body required");
-    const provider = cleanEnum(parsed.body.provider, "provider", VALID_ORCHESTRATOR_PROVIDERS)! as SpawnProvider;
+    const provider = cleanEnum(parsed.body.provider, "provider", SPAWN_PROVIDERS)! as SpawnProvider;
     const cwd = cleanString(parsed.body.cwd, "cwd", { required: true, max: 500 })!;
     const runnerId = cleanString(parsed.body.runnerId, "runnerId", { required: true, max: 240 })!;
     const agentId = cleanString(parsed.body.agentId, "agentId", { max: 240 });
@@ -3121,9 +3088,6 @@ const postTokenRevoke: Handler = (_req, params) => {
 
 // --- Orchestrator routes ---
 
-const VALID_ORCHESTRATOR_PROVIDERS = ["claude", "codex"] as const;
-const VALID_SPAWN_APPROVALS = ["open", "guarded", "read-only"] as const;
-
 function cleanJsonArray(value: unknown, field: string): unknown[] | undefined {
   if (value === undefined || value === null) return undefined;
   if (!Array.isArray(value)) throw new ValidationError(`${field} must be an array`);
@@ -3131,27 +3095,17 @@ function cleanJsonArray(value: unknown, field: string): unknown[] | undefined {
   return value;
 }
 
-function cleanSpawnSelection(body: Record<string, unknown>, provider: SpawnProvider): { model?: string; effort?: ProviderEffort; providerModel?: string } {
+function cleanSpawnSelection(body: Record<string, unknown>, provider: SpawnProvider): SpawnModelParams {
   const model = cleanString(body.model, "model", { max: 120 });
-  const effort = cleanEnum(body.effort, "effort", VALID_PROVIDER_EFFORTS) as ProviderEffort | undefined;
-  let resolved;
-  try {
-    resolved = resolveProviderSelection({ provider, model, effort });
-  } catch (error) {
-    throw new ValidationError(error instanceof Error ? error.message : String(error));
-  }
-  return {
-    model: resolved.modelAlias,
-    providerModel: resolved.providerModel,
-    effort: resolved.effort,
-  };
+  const effort = cleanEnum(body.effort, "effort", VALID_EFFORTS) as ProviderEffort | undefined;
+  return resolveSpawnModelParams(provider, model, effort);
 }
 
 function validateSpawnSelectionForOrchestrator(
   orch: NonNullable<ReturnType<typeof getOrchestrator>>,
   provider: SpawnProvider,
   body: Record<string, unknown>,
-): { model?: string; effort?: ProviderEffort; providerModel?: string } | Response {
+): SpawnModelParams | Response {
   if (!orch.providers.includes(provider)) {
     return error(`orchestrator does not have provider available: ${provider}`, 409);
   }
@@ -3211,8 +3165,8 @@ const postOrchestrator: Handler = async (req) => {
     const providers = cleanStringArray(parsed.body.providers, "providers") as SpawnProvider[] | undefined;
     if (providers) {
       for (const p of providers) {
-        if (!VALID_ORCHESTRATOR_PROVIDERS.includes(p as any)) {
-          return error(`invalid provider: ${p}. Must be one of: ${VALID_ORCHESTRATOR_PROVIDERS.join(", ")}`);
+        if (!SPAWN_PROVIDERS.includes(p as any)) {
+          return error(`invalid provider: ${p}. Must be one of: ${SPAWN_PROVIDERS.join(", ")}`);
         }
       }
     }
@@ -3295,7 +3249,7 @@ const postOrchestratorHeartbeat: Handler = async (req, params) => {
     };
     if (runtime.providers) {
       for (const p of runtime.providers) {
-        if (!VALID_ORCHESTRATOR_PROVIDERS.includes(p as any)) throw new ValidationError(`invalid provider: ${p}. Must be one of: ${VALID_ORCHESTRATOR_PROVIDERS.join(", ")}`);
+        if (!SPAWN_PROVIDERS.includes(p as any)) throw new ValidationError(`invalid provider: ${p}. Must be one of: ${SPAWN_PROVIDERS.join(", ")}`);
       }
     }
     const orch = orchestratorHeartbeat(params.id!, runtime);
@@ -3323,8 +3277,8 @@ const postOrchestratorBootstrap: Handler = async (req) => {
     const pathPrefix = cleanStringArray(parsed.body.pathPrefix, "pathPrefix");
     const providerList = providers?.length ? providers : ["claude", "codex"];
     for (const p of providerList) {
-      if (!VALID_ORCHESTRATOR_PROVIDERS.includes(p as any)) {
-        throw new ValidationError(`invalid provider: ${p}. Must be one of: ${VALID_ORCHESTRATOR_PROVIDERS.join(", ")}`);
+      if (!SPAWN_PROVIDERS.includes(p as any)) {
+        throw new ValidationError(`invalid provider: ${p}. Must be one of: ${SPAWN_PROVIDERS.join(", ")}`);
       }
     }
     const bootstrapToken = createToken({
@@ -3415,7 +3369,7 @@ const patchOrchestratorAgents: Handler = async (req, params) => {
         ?? cleanString(a.tmuxSession, "tmuxSession", { required: true, max: 240 })!;
       return {
         agentId: cleanString(a.agentId, "agentId", { max: 240 }) || "",
-        provider: cleanEnum(a.provider, "provider", VALID_ORCHESTRATOR_PROVIDERS)! as SpawnProvider,
+        provider: cleanEnum(a.provider, "provider", SPAWN_PROVIDERS)! as SpawnProvider,
         sessionName,
         tmuxSession: cleanString(a.tmuxSession, "tmuxSession", { max: 240 }) ?? sessionName,
         supervisor: cleanEnum(a.supervisor, "supervisor", ["process", "systemd", "launchd", "unknown"] as const),
@@ -3427,7 +3381,7 @@ const patchOrchestratorAgents: Handler = async (req, params) => {
         workspaceMode: cleanEnum(a.workspaceMode, "workspaceMode", VALID_WORKSPACE_MODES),
         workspace: cleanWorkspaceMetadata(a.workspace, "workspace"),
         label: cleanString(a.label, "label", { max: 120 }),
-        approvalMode: (cleanEnum(a.approvalMode, "approvalMode", VALID_SPAWN_APPROVALS, "guarded") ?? "guarded") as SpawnApprovalMode,
+        approvalMode: (cleanEnum(a.approvalMode, "approvalMode", APPROVAL_MODES, "guarded") ?? "guarded") as SpawnApprovalMode,
         policyName: cleanString(a.policyName, "policyName", { max: 120 }),
         spawnRequestId: cleanString(a.spawnRequestId, "spawnRequestId", { max: 160 }),
         automationRunId: cleanString(a.automationRunId, "automationRunId", { max: 160 }),
@@ -3492,7 +3446,7 @@ const patchOrchestratorAgents: Handler = async (req, params) => {
 
 function cleanManagedSessionExitDiagnostics(value: unknown, index: number): ManagedSessionExitDiagnostics {
   if (!isRecord(value)) throw new ValidationError(`exitedAgents[${index}] must be an object`);
-  const provider = cleanEnum(value.provider, `exitedAgents[${index}].provider`, VALID_ORCHESTRATOR_PROVIDERS);
+  const provider = cleanEnum(value.provider, `exitedAgents[${index}].provider`, SPAWN_PROVIDERS);
   if (!provider) throw new ValidationError(`exitedAgents[${index}].provider required`);
   const systemd = isRecord(value.systemd)
     ? {
@@ -3566,15 +3520,15 @@ const postOrchestratorSpawn: Handler = async (req, params) => {
     if (orch.status !== "online") return error("orchestrator is offline", 409);
 
     if (!isRecord(parsed.body)) return error("body required");
-    const provider = cleanEnum(parsed.body.provider, "provider", VALID_ORCHESTRATOR_PROVIDERS)! as SpawnProvider;
+    const provider = cleanEnum(parsed.body.provider, "provider", SPAWN_PROVIDERS)! as SpawnProvider;
     const selection = validateSpawnSelectionForOrchestrator(orch, provider, parsed.body);
     if (selection instanceof Response) return selection;
     const cwd = cleanString(parsed.body.cwd, "cwd", { max: 500 });
-    if (cwd && !pathWithinBase(cwd, orch.baseDir)) {
+    if (cwd && !isPathWithinBase(cwd, orch.baseDir)) {
       return error(`cwd must be within orchestrator base directory: ${orch.baseDir}`);
     }
     const label = cleanString(parsed.body.label, "label", { max: 120 });
-    const approvalMode = cleanEnum(parsed.body.approvalMode, "approvalMode", VALID_SPAWN_APPROVALS, "guarded") as SpawnApprovalMode;
+    const approvalMode = cleanEnum(parsed.body.approvalMode, "approvalMode", APPROVAL_MODES, "guarded") as SpawnApprovalMode;
     const prompt = cleanString(parsed.body.prompt, "prompt", { max: 16000 });
     const systemPromptAppend = cleanString(parsed.body.systemPromptAppend, "systemPromptAppend", { max: 64_000 });
     const tags = cleanStringArray(parsed.body.tags, "tags") ?? [];
@@ -3597,12 +3551,9 @@ const postOrchestratorSpawn: Handler = async (req, params) => {
       source: "system",
       target: orch.agentId,
 	      correlationId: requestId,
-      params: {
-        action: "spawn",
+      params: buildSpawnCommand({
         provider,
-        model: selection.model,
-        providerModel: selection.providerModel,
-        effort: selection.effort,
+        modelParams: { model: selection.model, providerModel: selection.providerModel, effort: selection.effort },
         cwd: cwd || orch.baseDir,
         workspaceMode,
         label,
@@ -3628,7 +3579,7 @@ const postOrchestratorSpawn: Handler = async (req, params) => {
 	        }),
 	        requestedBy: "dashboard",
         requestedAt: Date.now(),
-      },
+      }),
     });
     emitCommand(command);
     auditEvent({
@@ -3925,7 +3876,7 @@ async function proxyWorkspaceHostGet(workspaceId: string, hostPath: string, extr
     return json({ available: false, reason: "no isolated worktree" });
   }
   const orch = listOrchestrators().find(
-    (candidate) => candidate.status === "online" && candidate.apiUrl && pathWithinBase(workspace.sourceCwd, candidate.baseDir),
+    (candidate) => candidate.status === "online" && candidate.apiUrl && isPathWithinBase(workspace.sourceCwd, candidate.baseDir),
   );
   if (!orch?.apiUrl) return json({ available: false, reason: "owning orchestrator offline" });
   const query = new URLSearchParams({ path: workspace.worktreePath });
@@ -3934,7 +3885,7 @@ async function proxyWorkspaceHostGet(workspaceId: string, hostPath: string, extr
   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;
+  if (relayToken) headers[RELAY_TOKEN_HEADER] = relayToken;
   try {
     const res = await fetch(`${orch.apiUrl}${hostPath}?${query.toString()}`, {
       headers,
@@ -3976,11 +3927,11 @@ const getWorkspaceOrphans: Handler = async () => {
   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;
+  if (relayToken) headers[RELAY_TOKEN_HEADER] = relayToken;
   const orphans: WorkspaceOrphan[] = [];
 
   for (const repoRoot of repoRoots) {
-    const orch = orchestrators.find((candidate) => candidate.apiUrl && pathWithinBase(repoRoot, candidate.baseDir));
+    const orch = orchestrators.find((candidate) => candidate.apiUrl && isPathWithinBase(repoRoot, candidate.baseDir));
     if (!orch?.apiUrl) continue;
     let probe: WorkspaceProbe | undefined;
     try {
@@ -4018,7 +3969,7 @@ const postWorkspaceOrphanReclaim: Handler = async (req) => {
     // 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));
+    const orch = listOrchestrators().find((candidate) => candidate.status === "online" && isPathWithinBase(repoRoot, candidate.baseDir));
     if (!orch) return error("no online orchestrator owns this path", 409);
     const command = createCommand({
       type: "workspace.cleanup",
@@ -4044,6 +3995,165 @@ 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 };
+}
+
+// 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.
+async function fetchWorkspaceGitState(workspace: WorkspaceRecord): Promise<{ state: WorkspaceGitState } | { unavailable: string }> {
+  if (workspace.mode !== "isolated" || !workspace.worktreePath) return { unavailable: "no isolated worktree" };
+  const orch = listOrchestrators().find(
+    (candidate) => candidate.status === "online" && candidate.apiUrl && isPathWithinBase(workspace.sourceCwd, candidate.baseDir),
+  );
+  if (!orch?.apiUrl) return { unavailable: "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);
+  const headers: Record<string, string> = {};
+  const relayToken = process.env.AGENT_RELAY_TOKEN;
+  if (relayToken) headers[RELAY_TOKEN_HEADER] = relayToken;
+  try {
+    const res = await fetch(`${orch.apiUrl}/api/workspace/state?${query.toString()}`, { headers, signal: AbortSignal.timeout(10_000) });
+    if (!res.ok) return { unavailable: `host returned ${res.status}` };
+    return { state: await res.json() as WorkspaceGitState };
+  } catch (e) {
+    return { unavailable: `orchestrator unreachable: ${(e as Error).message}` };
+  }
+}
+
+// Recommend the next action for a workspace from its joined state — the steward's
+// (and a release agent's) "what should happen here?" without reconstructing it.
+function recommendWorkspaceAction(input: { workspace: WorkspaceRecord; ownerOnline: boolean; gitState?: WorkspaceGitState; claim: ReturnType<typeof workspaceActiveClaim> }): WorkspaceDiagnostics["recommendation"] {
+  const { workspace, ownerOnline, gitState, claim } = input;
+  if (claim) return { action: "wait", confidence: "high", reason: `claimed by ${claim.by ?? "steward"}` };
+  if (TERMINAL_WORKSPACE_STATUSES.has(workspace.status)) return { action: "none", confidence: "high", reason: `workspace is ${workspace.status}` };
+  if (!gitState || gitState.error) return { action: "review", confidence: "low", reason: gitState?.error ? `git state error: ${gitState.error}` : "git state unavailable" };
+  if (gitState.missing) return { action: "cleanup", confidence: "high", reason: "worktree no longer exists on disk" };
+  const ahead = gitState.unmergedAhead ?? gitState.ahead ?? 0;
+  const landed = gitState.landed === true;
+  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" };
+    return { action: "none", confidence: "medium", reason: "nothing to merge; owner active" };
+  }
+  if (ownerOnline && workspace.status !== "review_requested" && workspace.status !== "conflict") {
+    return { action: "wait", confidence: "medium", reason: "owner active and not awaiting review" };
+  }
+  if (workspace.status === "conflict") return { action: "rebase", confidence: "high", reason: "conflict — rebase onto base and resolve" };
+  if ((gitState.behind ?? 0) > 0) return { action: "rebase", confidence: "medium", reason: `${gitState.behind} behind base — rebase then merge` };
+  return { action: "merge", confidence: "high", reason: `${ahead} commit(s) ready to land` };
+}
+
+// Joined steward briefing for one workspace (#208): row + owner/orchestrator
+// liveness + live git state + branch mismatch + active claim + recommended action.
+const getWorkspaceDiagnostics: Handler = async (_req, params) => {
+  const workspace = getWorkspace(params.id!);
+  if (!workspace) return error("workspace not found", 404);
+  const owner = workspace.ownerAgentId ? getAgent(workspace.ownerAgentId) : null;
+  const ownerOnline = Boolean(owner) && owner!.status !== "offline";
+  const orch = listOrchestrators().find((candidate) => isPathWithinBase(workspace.sourceCwd, candidate.baseDir));
+  const orchOnline = Boolean(orch) && orch!.status === "online";
+  const fetched = await fetchWorkspaceGitState(workspace);
+  const gitState = "state" in fetched ? fetched.state : undefined;
+  const claim = workspaceActiveClaim(workspace);
+  const liveBranch = gitState?.branch;
+  const diagnostics: WorkspaceDiagnostics = {
+    workspaceId: workspace.id,
+    status: workspace.status,
+    mode: workspace.mode,
+    repoRoot: workspace.repoRoot,
+    worktreePath: workspace.worktreePath,
+    recordedBranch: workspace.branch,
+    liveBranch,
+    baseRef: workspace.baseRef,
+    branchMismatch: workspace.branch && liveBranch ? workspace.branch !== liveBranch : undefined,
+    owner: { id: workspace.ownerAgentId, status: owner?.status, online: ownerOnline },
+    orchestrator: { id: orch?.id, online: orchOnline },
+    ...(claim ? { claim: { by: claim.by, purpose: claim.purpose, expiresAt: claim.expiresAt } } : {}),
+    ...(gitState ? { gitState } : { gitStateUnavailable: "unavailable" in fetched ? fetched.unavailable : "unknown" }),
+    recommendation: recommendWorkspaceAction({ workspace, ownerOnline, gitState, claim }),
+  };
+  return json(diagnostics);
+};
+
+// Guarded batch cleanup of stale worktrees (#208 / steward report §3). Defaults to
+// dry-run and only ever proposes/cleans worktrees that are provably safe: offline
+// owner, not claimed, clean tree, and (landed-only) work already in base or empty.
+// Never touches a live owner. Reuses the same cleanup command path as the manual action.
+const postWorkspaceCleanupStale: 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);
+  const body = isRecord(parsed.body) ? parsed.body : {};
+  const repoRoot = cleanString(body.repoRoot, "repoRoot", { max: 1000 });
+  const dryRun = body.dryRun !== false; // safe by default
+  const landedOnly = body.landedOnly !== false;
+  const offlineOwnerOnly = body.offlineOwnerOnly !== false;
+
+  const candidates = listWorkspaces().filter((ws) =>
+    ws.mode === "isolated" && Boolean(ws.worktreePath) && !TERMINAL_WORKSPACE_STATUSES.has(ws.status) && (!repoRoot || ws.repoRoot === repoRoot),
+  );
+
+  const rows: Array<Record<string, unknown>> = [];
+  const cleaned: string[] = [];
+  for (const ws of candidates) {
+    const owner = ws.ownerAgentId ? getAgent(ws.ownerAgentId) : null;
+    const ownerOnline = Boolean(owner) && owner!.status !== "offline";
+    if (ownerOnline) continue;                         // never clean a live owner's worktree
+    if (offlineOwnerOnly && !ws.ownerAgentId) { /* no owner recorded — still eligible */ }
+    if (workspaceActiveClaim(ws)) continue;            // respect steward claims
+    const fetched = await fetchWorkspaceGitState(ws);
+    const gitState = "state" in fetched ? fetched.state : undefined;
+    const missing = gitState?.missing === true;
+    const dirtyCount = gitState?.dirtyCount;
+    const ahead = gitState?.unmergedAhead ?? gitState?.ahead ?? 0;
+    const landed = gitState?.landed === true;
+    // Safe = gone from disk, OR clean tree with no unmerged work (landed/empty).
+    const safe = missing || (gitState !== undefined && (dirtyCount ?? 1) === 0 && (!landedOnly || landed || ahead === 0));
+    const proof = { ownerStatus: owner?.status ?? "missing", ownerOnline, ahead, behind: gitState?.behind, landed, dirtyCount, missing, gitStateUnavailable: gitState ? undefined : ("unavailable" in fetched ? fetched.unavailable : undefined) };
+    const row: Record<string, unknown> = { workspaceId: ws.id, branch: ws.branch, worktreePath: ws.worktreePath, repoRoot: ws.repoRoot, safe, proof };
+    if (safe && !dryRun) {
+      const built = buildWorkspaceCleanupCommand(ws, "cleanup-stale");
+      if (built.ok) {
+        updateWorkspaceStatus(ws.id, "cleanup_requested", { lastWorkspaceAction: "cleanup-stale", lastWorkspaceActionAt: Date.now(), cleanupProof: proof });
+        emitCommand(built.command);
+        row.commandId = built.command.id;
+        cleaned.push(ws.id);
+      } else {
+        row.cleanupError = built.error;
+      }
+    }
+    rows.push(row);
+  }
+  return json({ dryRun, landedOnly, offlineOwnerOnly, repoRoot, scanned: candidates.length, eligible: rows.filter((r) => r.safe).length, cleaned, candidates: rows }, dryRun ? 200 : 202);
+};
+
 const postWorkspaceAction: Handler = async (req, params) => {
   const parsed = await parseBody<unknown>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);
@@ -4051,7 +4161,7 @@ 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", "merge", "abandon", "cleanup"] as const);
+    const action = cleanEnum(parsed.body.action, "action", ["status", "ready", "conflict-found", "request-review", "merge-plan", "merge", "abandon", "cleanup", "claim", "release-claim"] 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 });
@@ -4065,6 +4175,26 @@ const postWorkspaceAction: Handler = async (req, params) => {
     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") {
@@ -4112,30 +4242,9 @@ const postWorkspaceAction: Handler = async (req, params) => {
     let command: Command | undefined;
     if (requiresCommand) {
       // Only `cleanup` reaches here — `merge` returned early via the shared helper.
-      // 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 owners = listOrchestrators().filter((candidate) => pathWithinBase(workspace.sourceCwd, candidate.baseDir));
-      const onlineOwner = owners.find((candidate) => candidate.status === "online");
-      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",
-          workspaceId: workspace.id,
-          repoRoot: workspace.repoRoot,
-          worktreePath: workspace.worktreePath,
-          branch: workspace.branch,
-          requestedBy: agentId ?? "dashboard",
-          requestedAt: Date.now(),
-          deleteBranch: true,
-          queued: owner.status !== "online",
-        },
-      });
+      const built = buildWorkspaceCleanupCommand(workspace, agentId ?? "dashboard");
+      if (!built.ok) return error(built.error, built.status);
+      command = built.command;
       emitCommand(command);
     }
     auditEvent({
@@ -4187,7 +4296,7 @@ async function proxyOrchestratorGet(req: Request, orchestratorId: string, path:
   const proxyUrl = `${orch.apiUrl}${path}${incoming.search}`;
   const headers: Record<string, string> = {};
   const relayToken = process.env.AGENT_RELAY_TOKEN;
-  if (relayToken) headers["X-Agent-Relay-Token"] = relayToken;
+  if (relayToken) headers[RELAY_TOKEN_HEADER] = relayToken;
   try {
     const res = await fetch(proxyUrl, { headers, signal: AbortSignal.timeout(10_000) });
     const contentType = res.headers.get("content-type") ?? "";
@@ -4212,7 +4321,7 @@ async function proxyOrchestratorPost(req: Request, orchestratorId: string, path:
     "Content-Type": req.headers.get("content-type") ?? "application/json",
   };
   const relayToken = process.env.AGENT_RELAY_TOKEN;
-  if (relayToken) headers["X-Agent-Relay-Token"] = relayToken;
+  if (relayToken) headers[RELAY_TOKEN_HEADER] = relayToken;
   try {
     const body = await req.text();
     const res = await fetch(proxyUrl, {
@@ -4237,7 +4346,7 @@ async function proxyOrchestratorDelete(req: Request, orchestratorId: string, pat
   const proxyUrl = `${orch.apiUrl}${path}${incoming.search}`;
   const headers: Record<string, string> = {};
   const relayToken = process.env.AGENT_RELAY_TOKEN;
-  if (relayToken) headers["X-Agent-Relay-Token"] = relayToken;
+  if (relayToken) headers[RELAY_TOKEN_HEADER] = relayToken;
   try {
     const res = await fetch(proxyUrl, {
       method: "DELETE",
@@ -4258,7 +4367,7 @@ async function proxyOrchestratorJson(orchestratorId: string, path: string, metho
   if (orch.status !== "online") return error("orchestrator is offline", 422);
   const headers: Record<string, string> = { "Content-Type": "application/json" };
   const relayToken = process.env.AGENT_RELAY_TOKEN;
-  if (relayToken) headers["X-Agent-Relay-Token"] = relayToken;
+  if (relayToken) headers[RELAY_TOKEN_HEADER] = relayToken;
   try {
     const res = await fetch(`${orch.apiUrl}${path}`, {
       method,
@@ -4286,8 +4395,8 @@ const getOrchestratorProviders: Handler = async (req, params) => {
     const providers = cleanStringArray(payload.providers, "providers") as SpawnProvider[] | undefined;
     if (providers) {
       for (const p of providers) {
-        if (!VALID_ORCHESTRATOR_PROVIDERS.includes(p as any)) {
-          throw new ValidationError(`invalid provider: ${p}. Must be one of: ${VALID_ORCHESTRATOR_PROVIDERS.join(", ")}`);
+        if (!SPAWN_PROVIDERS.includes(p as any)) {
+          throw new ValidationError(`invalid provider: ${p}. Must be one of: ${SPAWN_PROVIDERS.join(", ")}`);
         }
       }
     }
@@ -4472,6 +4581,13 @@ const patchCommand: Handler = async (req, params) => {
             mergeCommandId: command.id,
             mergedAt: Date.now(),
           });
+          // Land-and-continue (#206): the worktree was recycled onto a fresh branch.
+          // Repoint the row so the next merge targets the live branch, not the deleted one.
+          const newBranch = cleanString(command.result.newBranch, "result.newBranch", { max: 240 });
+          if (newBranch) {
+            const mergedSha = cleanString(command.result.mergedSha, "result.mergedSha", { max: 64 });
+            setWorkspaceBranch(workspaceId, newBranch, mergedSha);
+          }
         }
       } else if (command.status === "failed" && command.correlationId) {
         // Merge couldn't complete — don't leave it stuck in merge_planned.
@@ -4599,6 +4715,25 @@ const putStewardConfigRoute: Handler = async (req) => {
   }
 };
 
+const getWorkspaceConfigRoute: Handler = () => json(getWorkspaceConfigEntry());
+
+const putWorkspaceConfigRoute: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const value = isRecord(parsed.body) && Object.prototype.hasOwnProperty.call(parsed.body, "value")
+      ? parsed.body.value
+      : parsed.body;
+    const updatedBy = isRecord(parsed.body) ? cleanString(parsed.body.updatedBy, "updatedBy", { max: 200 }) : undefined;
+    const entry = setWorkspaceConfig(value, updatedBy);
+    emitConfigChanged(entry.namespace, entry.key, entry.version);
+    return json(entry, entry.version === 1 ? 201 : 200);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
 // --- Insights / self-improvement (epic #183, docs/self-improvement.md) ---
 
 const getInsightsConfigRoute: Handler = () => json(getInsightsConfigEntry());
@@ -4635,6 +4770,14 @@ const getInsightsObservationsRoute: Handler = (req) => {
   });
 };
 
+// Accept a backfilled event time only when it's a sane epoch-ms value within a minute of
+// now (clock-skew guard); otherwise let recordObservation default to receive time.
+function sanitizeObservationOccurredAt(occurredAt: unknown): number | undefined {
+  if (typeof occurredAt !== "number" || !Number.isFinite(occurredAt)) return undefined;
+  if (occurredAt <= 0 || occurredAt > Date.now() + 60_000) return undefined;
+  return Math.floor(occurredAt);
+}
+
 const postInsightsObservationRoute: Handler = async (req) => {
   const parsed = await parseBody<unknown>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);
@@ -4656,6 +4799,10 @@ const postInsightsObservationRoute: Handler = async (req) => {
       value: isRecord(body.value) ? body.value : {},
       outcome: isRecord(body.outcome) ? body.outcome : undefined,
       source: body.source === "server" ? "server" : "agent",
+      // For insights the event time IS the record time (end-of-session). When the Runner
+      // backfilled this through its durable outbox (#196), occurredAt preserves the real
+      // moment rather than the later server-receive time.
+      createdAt: sanitizeObservationOccurredAt(body.occurredAt),
     });
     return json(observation, 201);
   } catch (e) {
@@ -4732,7 +4879,7 @@ const getConfigKeyHistory: Handler = (req, params) => {
 // --- Spawn policy routes ---
 
 function spawnRequestId(): string {
-  return `sp_${crypto.randomUUID()}`;
+  return generateSpawnRequestId();
 }
 
 function policyStatusPayload(policy: SpawnPolicy) {
@@ -6530,9 +6677,11 @@ const routes: Route[] = [
   route("GET", "/api/workspaces/orphans", getWorkspaceOrphans),
   route("POST", "/api/workspaces/orphans/reclaim", postWorkspaceOrphanReclaim),
   route("GET", "/api/workspaces/stewards", getWorkspaceStewards),
+  route("POST", "/api/workspaces/actions/cleanup-stale", postWorkspaceCleanupStale),
   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/diagnostics", getWorkspaceDiagnostics),
   route("GET", "/api/workspaces/:id/diff", getWorkspaceDiff),
   route("POST", "/api/workspaces/:id/actions", postWorkspaceAction),
   route("DELETE", "/api/workspaces/:id", deleteWorkspaceById),
@@ -6569,6 +6718,8 @@ const routes: Route[] = [
   route("DELETE", "/api/agent-profiles/:name", deleteAgentProfileRoute),
   route("GET", "/api/steward-config", getStewardConfigRoute),
   route("PUT", "/api/steward-config", putStewardConfigRoute),
+  route("GET", "/api/workspace-config", getWorkspaceConfigRoute),
+  route("PUT", "/api/workspace-config", putWorkspaceConfigRoute),
   route("GET", "/api/insights/config", getInsightsConfigRoute),
   route("PUT", "/api/insights/config", putInsightsConfigRoute),
   route("GET", "/api/insights/observations", getInsightsObservationsRoute),