agent-relay-server 0.32.2 → 0.32.3

package/src/routes/artifacts.ts

@@ -0,0 +1,226 @@
+// Auto-split from routes.ts (#299). Domain: artifacts.
+import { VALID_ARTIFACT_KINDS, error, json, parseQueryInt, type Handler } from "./_shared";
+import { ValidationError, artifactBlobReferenceCount, createArtifact, deleteArtifact, deleteArtifactBlob, getArtifact, getArtifactBlob, listArtifacts, upsertArtifactBlob } from "../db";
+import { bytesToStream } from "../http-body";
+import { cleanMeta, cleanString, optionalEnum } from "../validation";
+import { emitRelayEvent } from "../events";
+import { getArtifactStorage, maxArtifactBytes, normalizeDigest } from "../artifact-storage";
+import { getComponentAuth, getIntegrationAuth } from "../security";
+import { type ArtifactKind, type ArtifactSensitivity } from "../types";
+
+const VALID_ARTIFACT_SENSITIVITIES = ["public", "normal", "sensitive", "secret"] as const;
+
+function artifactActor(req: Request): string {
+  const component = getComponentAuth(req);
+  if (component) return component.sub;
+  const integration = getIntegrationAuth(req);
+  if (integration) return integration.name;
+  return "server";
+}
+
+function inferArtifactKind(mediaType: string, filename?: string): ArtifactKind {
+  const lowerName = filename?.toLowerCase() ?? "";
+  if (mediaType.startsWith("image/")) return "image";
+  if (mediaType.startsWith("audio/")) return "audio";
+  if (mediaType.startsWith("video/")) return "video";
+  if (["application/zip", "application/gzip", "application/x-tar"].includes(mediaType) || /\.(zip|tgz|tar|gz)$/.test(lowerName)) return "archive";
+  if (
+    mediaType.startsWith("text/") ||
+    ["application/pdf", "application/json", "application/xml"].includes(mediaType) ||
+    /\.(pdf|txt|md|json|csv|diff|patch)$/.test(lowerName)
+  ) return "document";
+  return "other";
+}
+
+function sniffMediaType(bytes: Uint8Array, hinted?: string, filename?: string): string {
+  if (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return "image/jpeg";
+  if (bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47) return "image/png";
+  if (bytes[0] === 0x47 && bytes[1] === 0x49 && bytes[2] === 0x46) return "image/gif";
+  if (bytes[0] === 0x25 && bytes[1] === 0x50 && bytes[2] === 0x44 && bytes[3] === 0x46) return "application/pdf";
+  if (bytes[0] === 0x50 && bytes[1] === 0x4b) return "application/zip";
+  const lower = filename?.toLowerCase() ?? "";
+  if (lower.endsWith(".svg")) return "image/svg+xml";
+  if (lower.endsWith(".md")) return "text/markdown";
+  if (lower.endsWith(".json")) return "application/json";
+  if (lower.endsWith(".csv")) return "text/csv";
+  if (lower.endsWith(".diff") || lower.endsWith(".patch")) return "text/x-diff";
+  return hinted || "application/octet-stream";
+}
+
+function safeDispositionFilename(filename: string | undefined): string {
+  const cleaned = filename?.replace(/[\\/\r\n"]/g, "_").trim();
+  return cleaned || "artifact";
+}
+
+function artifactContentDisposition(filename: string | undefined, mediaType: string): string {
+  const disposition = mediaType.startsWith("image/") && mediaType !== "image/svg+xml" ? "inline" : "attachment";
+  return `${disposition}; filename="${safeDispositionFilename(filename)}"`;
+}
+
+function parseArtifactMetadata(value: FormDataEntryValue | null): Record<string, unknown> | undefined {
+  if (value === null) return undefined;
+  if (typeof value !== "string") throw new ValidationError("metadata must be a JSON object");
+  if (!value.trim()) return undefined;
+  const parsed = JSON.parse(value);
+  return cleanMeta(parsed);
+}
+
+async function artifactUploadInput(req: Request): Promise<{
+  bytes: Uint8Array;
+  filename?: string;
+  mediaType?: string;
+  digest?: string;
+  sensitivity?: ArtifactSensitivity;
+  kind?: ArtifactKind;
+  metadata?: Record<string, unknown>;
+  expiresAt?: number;
+}> {
+  const maxBytes = maxArtifactBytes();
+  const contentType = req.headers.get("content-type") ?? "";
+  if (contentType.includes("multipart/form-data")) {
+    const form = await req.formData();
+    const file = form.get("file");
+    if (!(file instanceof File)) throw new ValidationError("multipart upload requires file");
+    if (file.size > maxBytes) throw new ValidationError(`artifact exceeds ${maxBytes} bytes`);
+    const sensitivity = optionalEnum(form.get("sensitivity"), "sensitivity", VALID_ARTIFACT_SENSITIVITIES, "normal") as ArtifactSensitivity;
+    const kind = optionalEnum(form.get("kind"), "kind", VALID_ARTIFACT_KINDS) as ArtifactKind | undefined;
+    const expiresAtRaw = form.get("expiresAt");
+    const expiresAt = typeof expiresAtRaw === "string" && expiresAtRaw.trim() ? Number(expiresAtRaw) : undefined;
+    if (expiresAt !== undefined && (!Number.isSafeInteger(expiresAt) || expiresAt <= Date.now())) throw new ValidationError("expiresAt must be a future unix timestamp in milliseconds");
+    return {
+      bytes: new Uint8Array(await file.arrayBuffer()),
+      filename: cleanString(form.get("filename") ?? file.name, "filename", { max: 240 }),
+      mediaType: file.type || undefined,
+      digest: cleanString(form.get("digest"), "digest", { max: 80 }),
+      sensitivity,
+      kind,
+      metadata: parseArtifactMetadata(form.get("metadata")),
+      expiresAt,
+    };
+  }
+
+  const length = req.headers.get("content-length");
+  if (length && Number(length) > maxBytes) throw new ValidationError(`artifact exceeds ${maxBytes} bytes`);
+  const bytes = new Uint8Array(await req.arrayBuffer());
+  if (bytes.byteLength > maxBytes) throw new ValidationError(`artifact exceeds ${maxBytes} bytes`);
+  const expiresAtRaw = req.headers.get("X-Artifact-Expires-At");
+  const expiresAt = expiresAtRaw ? Number(expiresAtRaw) : undefined;
+  if (expiresAt !== undefined && (!Number.isSafeInteger(expiresAt) || expiresAt <= Date.now())) throw new ValidationError("X-Artifact-Expires-At must be a future unix timestamp in milliseconds");
+  return {
+    bytes,
+    filename: cleanString(req.headers.get("X-Artifact-Filename"), "filename", { max: 240 }),
+    mediaType: contentType || undefined,
+    digest: cleanString(req.headers.get("X-Artifact-Digest"), "digest", { max: 80 }),
+    sensitivity: optionalEnum(req.headers.get("X-Artifact-Sensitivity"), "sensitivity", VALID_ARTIFACT_SENSITIVITIES, "normal") as ArtifactSensitivity,
+    kind: optionalEnum(req.headers.get("X-Artifact-Kind"), "kind", VALID_ARTIFACT_KINDS) as ArtifactKind | undefined,
+    metadata: undefined,
+    expiresAt,
+  };
+}
+
+function artifactErrorResponse(e: unknown): Response {
+  if (e instanceof ValidationError) return error(e.message, 400);
+  if (e instanceof SyntaxError) return error("metadata must be valid JSON", 400);
+  throw e;
+}
+
+export const postArtifact: Handler = async (req) => {
+  try {
+    const input = await artifactUploadInput(req);
+    const mediaType = sniffMediaType(input.bytes, input.mediaType, input.filename);
+    const storage = getArtifactStorage();
+    const stored = await storage.store(bytesToStream(input.bytes), {
+      mediaType,
+      size: input.bytes.byteLength,
+      digest: input.digest ? normalizeDigest(input.digest) : undefined,
+    });
+    upsertArtifactBlob({
+      digest: stored.digest,
+      storageUri: stored.storageUri,
+      mediaType,
+      size: stored.size,
+    });
+    const artifact = createArtifact({
+      blobDigest: stored.digest,
+      mediaType,
+      kind: input.kind ?? inferArtifactKind(mediaType, input.filename),
+      filename: input.filename,
+      size: stored.size,
+      sensitivity: input.sensitivity,
+      createdBy: artifactActor(req),
+      expiresAt: input.expiresAt,
+      metadata: input.metadata,
+    });
+    emitRelayEvent({ type: "artifact.created", source: "server", subject: artifact.id, data: { artifact } });
+    return json(artifact, 201);
+  } catch (e) {
+    return artifactErrorResponse(e);
+  }
+};
+
+export const getArtifacts: Handler = (req) => {
+  try {
+    const params = new URL(req.url).searchParams;
+    const limitRaw = parseQueryInt(params.get("limit"), { min: 1, max: 500 });
+    if (Number.isNaN(limitRaw)) return error("limit must be an integer between 1 and 500");
+    const messageIdRaw = parseQueryInt(params.get("messageId"), { min: 1, max: Number.MAX_SAFE_INTEGER });
+    if (Number.isNaN(messageIdRaw)) return error("messageId must be a positive integer");
+    const taskIdRaw = parseQueryInt(params.get("taskId"), { min: 1, max: Number.MAX_SAFE_INTEGER });
+    if (Number.isNaN(taskIdRaw)) return error("taskId must be a positive integer");
+    return json(listArtifacts({
+      messageId: messageIdRaw ?? undefined,
+      taskId: taskIdRaw ?? undefined,
+      createdBy: cleanString(params.get("createdBy"), "createdBy", { max: 200 }),
+      limit: limitRaw ?? 100,
+    }));
+  } catch (e) {
+    return artifactErrorResponse(e);
+  }
+};
+
+export const getArtifactById: Handler = (_req, params) => {
+  const artifact = getArtifact(params.id!);
+  return artifact ? json(artifact) : error("artifact not found", 404);
+};
+
+export const getArtifactContent: Handler = async (_req, params) => {
+  const artifact = getArtifact(params.id!);
+  if (!artifact) return error("artifact not found", 404);
+  const blob = getArtifactBlob(artifact.blobDigest);
+  if (!blob) return error("artifact blob not found", 404);
+  const content = await getArtifactStorage().retrieve(blob.storageUri);
+  return new Response(content.stream, {
+    headers: {
+      "Content-Type": artifact.mediaType,
+      "Content-Length": String(content.size),
+      "Content-Disposition": artifactContentDisposition(artifact.filename, artifact.mediaType),
+      "X-Artifact-Digest": artifact.digest,
+    },
+  });
+};
+
+export const headArtifactContent: Handler = (_req, params) => {
+  const artifact = getArtifact(params.id!);
+  if (!artifact) return new Response(null, { status: 404 });
+  return new Response(null, {
+    headers: {
+      "Content-Type": artifact.mediaType,
+      "Content-Length": String(artifact.size),
+      "Content-Disposition": artifactContentDisposition(artifact.filename, artifact.mediaType),
+      "X-Artifact-Digest": artifact.digest,
+    },
+  });
+};
+
+export const deleteArtifactById: Handler = async (_req, params) => {
+  const artifact = getArtifact(params.id!);
+  if (!artifact) return error("artifact not found", 404);
+  const blob = getArtifactBlob(artifact.blobDigest);
+  if (!deleteArtifact(artifact.id)) return error("artifact not found", 404);
+  if (blob && artifactBlobReferenceCount(blob.digest) === 0) {
+    await getArtifactStorage().delete(blob.storageUri);
+    deleteArtifactBlob(blob.digest);
+  }
+  emitRelayEvent({ type: "artifact.deleted", source: "server", subject: artifact.id, data: { artifactId: artifact.id } });
+  return json({ ok: true });
+};

package/src/routes/automations.ts

@@ -0,0 +1,83 @@
+// Auto-split from routes.ts (#299). Domain: automations.
+import { ValidationError } from "../db";
+import { createAutomation, deleteAutomation, getAutomation, listAutomationRuns, listAutomations, runAutomationNow, updateAutomation, type AutomationDispatchResult } from "../automations";
+import { emitCommand, error, json, parseBody, parseQueryInt, type Handler } from "./_shared";
+import { emitNewMessage, emitTaskChanged } from "../sse";
+import { emitRelayEvent } from "../events";
+
+function emitAutomationDispatch(result: AutomationDispatchResult): void {
+  if (result.command) emitCommand(result.command);
+  if (result.message) emitNewMessage(result.message);
+  if (result.task) emitTaskChanged(result.task, "task.created");
+  emitRelayEvent({
+    type: "automation.run",
+    source: "server",
+    subject: result.run.id,
+    data: { automation: result.automation, run: result.run, task: result.task },
+  });
+}
+
+export const getAutomations: Handler = () => {
+  return json(listAutomations());
+};
+
+export const postAutomation: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const automation = createAutomation(parsed.body as any);
+    emitRelayEvent({ type: "automation.created", source: "server", subject: automation.id, data: { automation } });
+    return json(automation, 201);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const getAutomationById: Handler = (_req, params) => {
+  const automation = getAutomation(params.id!);
+  return automation ? json(automation) : error("automation not found", 404);
+};
+
+export const patchAutomation: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const automation = updateAutomation(params.id!, parsed.body as any);
+    if (!automation) return error("automation not found", 404);
+    emitRelayEvent({ type: "automation.updated", source: "server", subject: automation.id, data: { automation } });
+    return json(automation);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const deleteAutomationById: Handler = (_req, params) => {
+  if (!deleteAutomation(params.id!)) return error("automation not found", 404);
+  emitRelayEvent({ type: "automation.deleted", source: "server", subject: params.id!, data: { automationId: params.id! } });
+  return json({ ok: true });
+};
+
+export const postAutomationRun: Handler = (_req, params) => {
+  try {
+    const result = runAutomationNow(params.id!);
+    if (!result) return error("automation not found", 404);
+    emitAutomationDispatch(result);
+    return json(result, 202);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const getAutomationRuns: Handler = (req) => {
+  const url = new URL(req.url);
+  const limitRaw = parseQueryInt(url.searchParams.get("limit"), { min: 1, max: 500 });
+  if (Number.isNaN(limitRaw)) return error("limit must be an integer between 1 and 500");
+  return json(listAutomationRuns({
+    automationId: url.searchParams.get("automationId") ?? undefined,
+    status: url.searchParams.get("status") ?? undefined,
+    limit: limitRaw ?? 100,
+  }));
+};

package/src/routes/commands.ts

@@ -0,0 +1,317 @@
+// Auto-split from routes.ts (#299). Domain: commands.
+import { VALID_AGENT_ACTIONS, agentControlActionIcon, auditEvent, authorizeRoute, emitCommand, error, json, parseBody, parseQueryInt, type AgentControlAction, type Handler } from "./_shared";
+import { VALID_WORKSPACE_STATUSES, cleanParams, cleanString, optionalEnum } from "../validation";
+import { ValidationError, deleteWorkspace, getOrchestrator, getWorkspace, patchWorkspaceMetadata, releaseMergeLease, setOrchestratorUpgradeState, setWorkspaceBranch, updateWorkspaceStatus } from "../db";
+import { applyCommandToRecipe } from "../recipe-runner";
+import { claimMetadataPatch } from "../workspace-claim";
+import { clearActiveMemories, injectAlwaysReloadMemories } from "../memory-service";
+import { createCommand, getCommand, listCommands, updateCommand } from "../commands-db";
+import { emitOrchestratorStatus } from "../sse";
+import { getCompactionWatch } from "../compaction-watch";
+import { isRecord } from "agent-relay-sdk";
+import { isRequestAuthorizedFor } from "../security";
+import { notifyBranchLanded } from "../branch-landed";
+import { type Command, type CommandStatus, type CreateCommandInput, type WorkspaceStatus } from "../types";
+
+const VALID_COMMAND_STATUSES = ["pending", "accepted", "running", "succeeded", "failed", "timed_out", "rejected", "canceled"] as const;
+
+function auditCommandOutcome(command: Command): void {
+  if (command.status !== "succeeded" && command.status !== "failed") return;
+  if (command.type !== "agent.restart" && command.type !== "agent.shutdown" && command.type !== "agent.reconnect") return;
+  const paramAction = typeof command.params?.action === "string" && (VALID_AGENT_ACTIONS as readonly string[]).includes(command.params.action)
+    ? command.params.action as AgentControlAction
+    : null;
+  const action = paramAction ?? agentControlActionFromCommandType(command.type);
+  if (!action) return;
+  const agentId = typeof command.params?.agentId === "string" ? command.params.agentId : command.target;
+  const succeeded = command.status === "succeeded";
+  auditEvent({
+    clientId: `server-command-${command.id}-${command.status}`,
+    kind: "state",
+    title: succeeded
+      ? agentControlActionCompletedTitle(action)
+      : `Agent ${action} failed`,
+    body: succeeded ? action : (command.error ?? action),
+    meta: agentId,
+    icon: succeeded
+      ? agentControlActionIcon(action)
+      : "ti-alert-triangle",
+    view: "agents",
+    agentId,
+    metadata: { action, commandId: command.id, outcome: command.status },
+  });
+}
+
+function agentControlActionFromCommandType(type: string): AgentControlAction | null {
+  if (type === "agent.restart") return "restart";
+  if (type === "agent.shutdown") return "shutdown";
+  if (type === "agent.reconnect") return "reconnect";
+  if (type === "agent.compact") return "compact";
+  if (type === "agent.clearContext") return "clearContext";
+  if (type === "agent.interrupt") return "interrupt";
+  return null;
+}
+
+function agentControlActionCompletedTitle(action: AgentControlAction): string {
+  if (action === "restart") return "Agent restarted";
+  if (action === "resume") return "Agent resumed";
+  if (action === "shutdown") return "Agent shut down";
+  if (action === "compact") return "Agent compacted";
+  if (action === "clearContext") return "Agent context cleared";
+  if (action === "interrupt") return "Agent interrupted";
+  return "Agent reconnected";
+}
+
+function settleFailedOrchestratorUpgrade(command: Command): void {
+  if (command.type !== "orchestrator.upgrade" || command.status !== "failed") return;
+  const orchestratorId = typeof command.params?.orchestratorId === "string" ? command.params.orchestratorId : undefined;
+  if (!orchestratorId) return;
+  const orch = getOrchestrator(orchestratorId);
+  const up = orch?.upgrade;
+  if (!orch || !up || up.status !== "pending" || up.commandId !== command.id) return;
+  const errMsg = command.error ?? "orchestrator upgrade failed";
+  setOrchestratorUpgradeState(orch.id, { ...up, status: "failed", settledAt: Date.now(), error: errMsg });
+  auditEvent({
+    clientId: `server-orchestrator-upgrade-command-failed-${orch.id}-${command.id}`,
+    kind: "state",
+    title: "Orchestrator upgrade failed",
+    body: errMsg,
+    meta: orch.id,
+    icon: "ti-alert-triangle",
+    view: "orchestrators",
+    metadata: { orchestratorId: orch.id, commandId: command.id },
+  });
+  emitOrchestratorStatus(orch.id);
+}
+
+function normalizeCommandInput(body: unknown): CreateCommandInput {
+  if (!isRecord(body)) throw new ValidationError("command body must be an object");
+  const type = cleanString(body.type, "type", { required: true, max: 120 })!;
+  const source = cleanString(body.source, "source", { required: true, max: 240 })!;
+  const target = cleanString(body.target, "target", { required: true, max: 240 })!;
+  const params = cleanParams(body.params) ?? {};
+  const correlationId = cleanString(body.correlationId, "correlationId", { max: 240 });
+  let ttlMs: number | undefined;
+  if (body.ttlMs !== undefined) {
+    if (typeof body.ttlMs !== "number" || !Number.isSafeInteger(body.ttlMs) || body.ttlMs <= 0) {
+      throw new ValidationError("ttlMs must be a positive integer");
+    }
+    ttlMs = body.ttlMs;
+  }
+  return { type, source, target, params, correlationId, ttlMs };
+}
+
+function commandAuthorizationResource(input: Pick<CreateCommandInput, "target" | "params">): Parameters<typeof isRequestAuthorizedFor>[1]["resource"] {
+  const params = isRecord(input.params) ? input.params : {};
+  return {
+    target: input.target,
+    agentId: cleanString(params.agentId, "params.agentId", { max: 240 }) ?? input.target,
+    policyName: cleanString(params.policyName, "params.policyName", { max: 120 }),
+    orchestratorId: cleanString(params.orchestratorId, "params.orchestratorId", { max: 120 }),
+    cwd: cleanString(params.cwd, "params.cwd", { max: 500 }),
+    spawnRequestId: cleanString(params.spawnRequestId, "params.spawnRequestId", { max: 160 }),
+  };
+}
+
+export const postCommand: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const input = normalizeCommandInput(parsed.body);
+    const denied = authorizeRoute(req, { scope: "command:write", resource: commandAuthorizationResource(input) });
+    if (denied) return denied;
+    const command = createCommand(input);
+    emitCommand(command);
+    return json(command, 201);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const getCommands: Handler = (req) => {
+  const url = new URL(req.url);
+  const limitRaw = parseQueryInt(url.searchParams.get("limit"), { min: 1, max: 500 });
+  if (Number.isNaN(limitRaw)) return error("limit must be an integer between 1 and 500");
+  const sinceRaw = parseQueryInt(url.searchParams.get("since"), { min: 0, max: Number.MAX_SAFE_INTEGER });
+  if (Number.isNaN(sinceRaw)) return error("since must be a non-negative integer");
+  const status = url.searchParams.get("status") ?? undefined;
+  if (status && !VALID_COMMAND_STATUSES.includes(status as any)) {
+    return error(`status must be one of: ${VALID_COMMAND_STATUSES.join(", ")}`);
+  }
+  return json(listCommands({
+    target: url.searchParams.get("target") ?? undefined,
+    status: status as CommandStatus | undefined,
+    type: url.searchParams.get("type") ?? undefined,
+    since: sinceRaw ?? undefined,
+    limit: limitRaw ?? undefined,
+  }));
+};
+
+export const getCommandById: Handler = (_req, params) => {
+  const command = getCommand(params.id!);
+  return command ? json(command) : error("command not found", 404);
+};
+
+export const patchCommand: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  if (!isRecord(parsed.body)) return error("command body must be an object");
+  try {
+    const current = getCommand(params.id!);
+    if (!current) return error("command not found", 404);
+    const denied = authorizeRoute(req, { scope: "command:write", resource: commandAuthorizationResource(current) });
+    if (denied) return denied;
+    const status = optionalEnum(parsed.body.status, "status", VALID_COMMAND_STATUSES);
+    const result = cleanParams(parsed.body.result, "result");
+    const err = cleanString(parsed.body.error, "error", { max: 4000 });
+    const command = updateCommand(params.id!, { status: status as CommandStatus | undefined, result, error: err });
+    if (!command) return error("command not found", 404);
+    applyCommandToRecipe(command);
+    if ((command.type === "agent.compact" || command.type === "agent.clearContext") && command.status === "succeeded") {
+      await clearActiveMemories(command.target, command.type === "agent.compact" ? "compact" : "clearContext");
+    }
+    if (command.type === "agent.compact" && command.status === "succeeded") {
+      const tags = alwaysReloadMemoryTags(command.params);
+      if (tags.length) {
+        const injection = await injectAlwaysReloadMemories(command.target, tags, "post-compaction reload");
+        if (injection) emitCommand(injection.command);
+      }
+    }
+    if ((command.type === "agent.compact" || command.type === "agent.clearContext") && command.status === "succeeded") {
+      // Keystrokes confirmed delivered — start watching for the real provider
+      // hook so a command that landed in the wrong context gets flagged.
+      getCompactionWatch().noteCommandSucceeded(command.type, command.id, command.target);
+    }
+    if (command.type === "workspace.cleanup" && command.status === "succeeded" && isRecord(command.result)) {
+      const workspaceId = cleanString(command.result.workspaceId, "result.workspaceId", { max: 160 });
+      if (workspaceId) {
+        updateWorkspaceStatus(workspaceId, "cleaned", {
+          cleanupResult: command.result,
+          cleanupCommandId: command.id,
+        });
+      }
+    }
+    if (command.type === "workspace.merge") {
+      // Merge settled (either way) — free the per-repo merge lease so the next
+      // base merge can proceed (issue #157).
+      if (command.status === "succeeded" || command.status === "failed") {
+        releaseMergeLease({ commandId: command.id });
+      }
+      if (command.status === "succeeded" && isRecord(command.result)) {
+        const workspaceId = cleanString(command.result.workspaceId, "result.workspaceId", { max: 160 });
+        const resultStatus = optionalEnum(command.result.status, "result.status", VALID_WORKSPACE_STATUSES) as WorkspaceStatus | undefined;
+        if (workspaceId && resultStatus) {
+          // Snapshot the row BEFORE the recycle repoints `branch` (#206) — the landed
+          // branch name + author (#239 branch.landed push) come from this pre-mutation state.
+          const landedWorkspace = getWorkspace(workspaceId);
+          const newBranch = cleanString(command.result.newBranch, "result.newBranch", { max: 240 });
+          const normalizedStatus = command.result.merged === true
+            && !newBranch
+            && ["review_requested", "merge_planned", "conflict"].includes(resultStatus)
+            ? "merged"
+            : resultStatus;
+          updateWorkspaceStatus(workspaceId, normalizedStatus, {
+            mergeResult: command.result,
+            mergeCommandId: command.id,
+            mergedAt: Date.now(),
+            ...(normalizedStatus !== resultStatus ? { mergeStatusNormalizedFrom: resultStatus } : {}),
+            // The land consumes the steward's claim (#208 steward contract / vent
+            // #62): a successful land must release it, or `steward inspect` keeps
+            // showing a stale claim on the recycled workspace and blocks the next
+            // automation. Clearing a null claim (auto-merge path) is a harmless no-op.
+            ...claimMetadataPatch(true),
+          });
+          // 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 mergedSha = cleanString(command.result.mergedSha, "result.mergedSha", { max: 64 });
+          // base_sha tracks the tip the recycled workspace forks from. On a no-ff land
+          // (#287) that's the merge commit (result.baseSha), not the preserved landed
+          // commit (mergedSha); fall back to mergedSha for older orchestrators.
+          const baseSha = cleanString(command.result.baseSha, "result.baseSha", { max: 64 });
+          if (newBranch) {
+            setWorkspaceBranch(workspaceId, newBranch, baseSha ?? mergedSha);
+          }
+          // #239 — push the author a "your branch landed" notice (no polling). Only on a
+          // real land; a no-op resolution (#230) merged nothing, so it earns no notice.
+          if (command.result.merged === true && landedWorkspace) {
+            notifyBranchLanded({
+              workspace: landedWorkspace,
+              mergedSha,
+              subject: cleanString(command.result.subject, "result.subject", { max: 200 }),
+              newBranch,
+              pushed: typeof command.result.pushed === "boolean" ? command.result.pushed : undefined,
+            });
+          }
+        }
+      } 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 = optionalEnum(command.result.status, "result.status", VALID_WORKSPACE_STATUSES) as WorkspaceStatus | undefined;
+      const removed = command.result.removed === true;
+      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")) {
+          if (removed) {
+            // The owner exited and the worktree had no work — the orchestrator
+            // already deleted it on disk. Drop the DB row immediately instead of
+            // parking it at `cleaned` for 24h: a no-change session is pure junk
+            // from the user's view, so it should leave the Workspaces panel now.
+            deleteWorkspace(workspaceId);
+            auditEvent({
+              clientId: `workspace-reconcile-removed-${workspaceId}-${Date.now()}`,
+              kind: "state",
+              title: "Workspace removed (no changes)",
+              body: current.worktreePath,
+              meta: current.branch ?? workspaceId,
+              icon: "ti-trash",
+              view: "orchestrators",
+              metadata: { reconcileCommandId: command.id, workspaceId, repoRoot: current.repoRoot },
+            });
+          } else {
+            updateWorkspaceStatus(workspaceId, resultStatus, {
+              reconcileResult: command.result,
+              reconcileCommandId: command.id,
+              reconciledAt: Date.now(),
+            });
+          }
+        }
+      }
+    }
+    if (command.type === "workspace.deps-refresh" && command.status === "succeeded" && isRecord(command.result)) {
+      // Record the outcome on the row without touching status (#51) — observability
+      // for the dashboard; the CLI reads the result straight off the command.
+      const workspaceId = cleanString(command.result.workspaceId, "result.workspaceId", { max: 160 });
+      if (workspaceId) {
+        patchWorkspaceMetadata(workspaceId, { lastDepsRefresh: command.result, lastDepsRefreshCommandId: command.id, lastDepsRefreshAt: Date.now() });
+      }
+    }
+    settleFailedOrchestratorUpgrade(command);
+    emitCommand(command);
+    auditCommandOutcome(command);
+    return json(command);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+function alwaysReloadMemoryTags(params: Record<string, unknown>): string[] {
+  const memory = params.memory;
+  if (!isRecord(memory)) return [];
+  const raw = memory.alwaysReload;
+  if (!Array.isArray(raw)) return [];
+  return [...new Set(raw.filter((item): item is string => typeof item === "string").map((item) => item.trim()).filter(Boolean))];
+}