agent-relay-server 0.17.0 → 0.19.0

package/src/automations.ts

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import { parseJson } from "./utils";
 import {
   getAgent,
   getDb,
@@ -12,8 +13,11 @@ import {
   ValidationError,
 } from "./db";
 import { createCommand } from "./commands-db";
-import { getAgentProfile, getSpawnPolicy, workspaceSpawnParams } from "./config-store";
-import { resolveProviderSelection, type ProviderEffort } from "agent-relay-sdk/provider-catalog";
+import { cleanEnum, cleanString, cleanStringArray, optionalEnum } from "./validation";
+import { getAgentProfile, getSpawnPolicy } from "./config-store";
+import { buildSpawnCommand, resolveSpawnModelParams } from "./spawn-command";
+import { resolveProviderSelection, type ProviderEffort, VALID_EFFORTS } from "agent-relay-sdk/provider-catalog";
+import { errMessage, VALID_WORKSPACE_MODES } from "agent-relay-sdk";
 import { runnerRuntimeTokenEnv } from "./runtime-tokens";
 import type {
   AgentCard,
@@ -43,8 +47,6 @@ const BLOCKING_RUN_STATUSES = new Set<AutomationRunStatus>(["dispatching", "wait
 const OPEN_RUN_STATUSES = new Set<AutomationRunStatus>(["scheduled", "dispatching", "waiting_agent", "running"]);
 const CLOSED_TASK_STATUS = new Set(["done", "failed", "canceled"]);
 const MAX_CRON_SCAN_MINUTES = 366 * 24 * 60;
-const VALID_EFFORTS = ["low", "medium", "high", "xhigh", "max"] as const;
-const VALID_WORKSPACE_MODES = ["isolated", "shared", "inherit"] as const;
 const MIN_RUNTIME_BUDGET_MS = 60_000;
 const MAX_RUNTIME_BUDGET_MS = 24 * 60 * 60 * 1000;
 
@@ -75,15 +77,6 @@ function ensureAutomationTables(): void {
   initializedDb = current;
 }
 
-function parseJson<T>(value: unknown, fallback: T): T {
-  if (typeof value !== "string" || !value) return fallback;
-  try {
-    return JSON.parse(value) as T;
-  } catch {
-    return fallback;
-  }
-}
-
 function rowToAutomation(row: any): Automation {
   return {
     id: row.id,
@@ -126,39 +119,12 @@ function rowToAutomationRun(row: any): AutomationRun {
   };
 }
 
-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 cleanStringArray(value: unknown, field: string): string[] | undefined {
-  if (value === undefined || value === null) return undefined;
-  if (!Array.isArray(value)) throw new ValidationError(`${field} must be an array`);
-  return [...new Set(value.map((item) => cleanString(item, `${field} item`, { max: 100 })).filter(Boolean) as string[])];
-}
-
 function cleanBool(value: unknown, field: string): boolean | undefined {
   if (value === undefined || value === null) return undefined;
   if (typeof value !== "boolean") throw new ValidationError(`${field} must be a boolean`);
   return value;
 }
 
-function cleanEnum<T extends readonly string[]>(value: unknown, field: string, valid: T, fallback?: T[number]): T[number] {
-  if (value === undefined || value === null) {
-    if (fallback !== undefined) return fallback;
-    throw new ValidationError(`${field} required`);
-  }
-  if (typeof value !== "string" || !valid.includes(value)) throw new ValidationError(`${field} must be one of: ${valid.join(", ")}`);
-  return value as T[number];
-}
-
 function cleanMeta(value: unknown, field = "metadata"): Record<string, unknown> | undefined {
   if (value === undefined || value === null) return undefined;
   if (typeof value !== "object" || Array.isArray(value)) throw new ValidationError(`${field} must be an object`);
@@ -172,7 +138,7 @@ function normalizeTaskTemplate(value: unknown): AutomationTaskTemplate {
   return {
     title: cleanString(input.title, "taskTemplate.title", { required: true, max: 240 })!,
     body: cleanString(input.body, "taskTemplate.body", { required: true, max: 200_000 })!,
-    severity: cleanEnum(input.severity, "taskTemplate.severity", ["info", "warning", "critical"] as const, "info") as TaskSeverity,
+    severity: optionalEnum(input.severity, "taskTemplate.severity", ["info", "warning", "critical"] as const, "info") as TaskSeverity,
     dedupeKey: cleanString(input.dedupeKey, "taskTemplate.dedupeKey", { max: 240 }),
     externalUrl: cleanString(input.externalUrl, "taskTemplate.externalUrl", { max: 1000 }),
     metadata: cleanMeta(input.metadata, "taskTemplate.metadata"),
@@ -226,13 +192,13 @@ function normalizeTargetPolicy(value: unknown): AutomationTargetPolicy {
       selector: {
         provider: cleanString(selectorInput.provider, "targetPolicy.selector.provider", { max: 40 }) as "claude" | "codex" | undefined,
         label: cleanString(selectorInput.label, "targetPolicy.selector.label", { max: 120 }),
-        tags: cleanStringArray(selectorInput.tags, "targetPolicy.selector.tags"),
-        capabilities: cleanStringArray(selectorInput.capabilities, "targetPolicy.selector.capabilities"),
+        tags: cleanStringArray(selectorInput.tags, "targetPolicy.selector.tags", { itemMax: 100 }),
+        capabilities: cleanStringArray(selectorInput.capabilities, "targetPolicy.selector.capabilities", { itemMax: 100 }),
       },
-      ifNoMatch: cleanEnum(input.ifNoMatch, "targetPolicy.ifNoMatch", ["fail", "spawn"] as const, "fail"),
+      ifNoMatch: optionalEnum(input.ifNoMatch, "targetPolicy.ifNoMatch", ["fail", "spawn"] as const, "fail"),
     };
   }
-  const provider = cleanEnum(input.provider, "targetPolicy.provider", ["claude", "codex"] as const, "codex");
+  const provider = optionalEnum(input.provider, "targetPolicy.provider", ["claude", "codex"] as const, "codex");
   const model = cleanString(input.model, "targetPolicy.model", { max: 120 });
   const effort = input.effort === undefined || input.effort === null ? undefined : cleanEnum(input.effort, "targetPolicy.effort", VALID_EFFORTS) as ProviderEffort;
   const profile = cleanString(input.profile, "targetPolicy.profile", { max: 120 });
@@ -240,7 +206,7 @@ function normalizeTargetPolicy(value: unknown): AutomationTargetPolicy {
   try {
     resolveProviderSelection({ provider, model, effort });
   } catch (error) {
-    throw new ValidationError(error instanceof Error ? error.message : String(error));
+    throw new ValidationError(errMessage(error));
   }
   return {
     mode,
@@ -248,9 +214,9 @@ function normalizeTargetPolicy(value: unknown): AutomationTargetPolicy {
     model,
     effort,
     cwd: cleanString(input.cwd, "targetPolicy.cwd", { max: 500 }),
-    workspaceMode: cleanEnum(input.workspaceMode, "targetPolicy.workspaceMode", VALID_WORKSPACE_MODES, "inherit"),
+    workspaceMode: optionalEnum(input.workspaceMode, "targetPolicy.workspaceMode", VALID_WORKSPACE_MODES, "inherit"),
     profile,
-    approvalMode: cleanEnum(input.approvalMode, "targetPolicy.approvalMode", ["open", "guarded", "read-only"] as const, "guarded"),
+    approvalMode: optionalEnum(input.approvalMode, "targetPolicy.approvalMode", ["open", "guarded", "read-only"] as const, "guarded"),
     keepAlive: cleanBool(input.keepAlive, "targetPolicy.keepAlive") ?? false,
     runtimeBudget: normalizeRuntimeBudget(input),
     shutdownAfterMs: typeof input.shutdownAfterMs === "number" && Number.isSafeInteger(input.shutdownAfterMs) && input.shutdownAfterMs >= 0
@@ -270,8 +236,8 @@ function normalizeCreateInput(input: CreateAutomationInput): Required<Omit<Creat
     enabled: cleanBool(input.enabled, "enabled") ?? true,
     schedule,
     timezone,
-    catchUpPolicy: cleanEnum(input.catchUpPolicy, "catchUpPolicy", ["skip", "run_once", "run_all"] as const, DEFAULT_CATCH_UP),
-    concurrencyPolicy: cleanEnum(input.concurrencyPolicy, "concurrencyPolicy", ["skip", "queue", "replace"] as const, DEFAULT_CONCURRENCY),
+    catchUpPolicy: optionalEnum(input.catchUpPolicy, "catchUpPolicy", ["skip", "run_once", "run_all"] as const, DEFAULT_CATCH_UP),
+    concurrencyPolicy: optionalEnum(input.concurrencyPolicy, "concurrencyPolicy", ["skip", "queue", "replace"] as const, DEFAULT_CONCURRENCY),
     orchestratorId: cleanString(input.orchestratorId, "orchestratorId", { required: true, max: 160 })!,
     targetPolicy: normalizeTargetPolicy(input.targetPolicy),
     taskTemplate: normalizeTaskTemplate(input.taskTemplate),
@@ -530,7 +496,7 @@ function dispatchAutomationRun(automation: Automation, run: AutomationRun, now:
     updateRun(run.id, {
       status: "failed",
       finishedAt: now,
-      error: e instanceof Error ? e.message : String(e),
+      error: errMessage(e),
     }, now);
     return { automation, run: getAutomationRun(run.id)! };
   }
@@ -544,22 +510,17 @@ function dispatchOnDemandAutomation(
   now: number,
 ): AutomationDispatchResult {
   if (!orchestrator.providers.includes(policy.provider)) throw new ValidationError(`orchestrator ${orchestrator.id} does not have provider available: ${policy.provider}`);
-  const selection = resolveProviderSelection({ provider: policy.provider, model: policy.model, effort: policy.effort });
   const agentProfile = policy.profile ? getAgentProfile(policy.profile)?.value : undefined;
   const label = automationRunLabel(automation.id, run.id);
   const command = createCommand({
     type: "agent.spawn",
     source: "automation",
     target: orchestrator.agentId,
-    params: {
-      action: "spawn",
+    params: buildSpawnCommand({
       provider: policy.provider,
-      model: selection.modelAlias,
-      providerModel: selection.providerModel,
-      effort: selection.effort,
+      modelParams: resolveSpawnModelParams(policy.provider, policy.model, policy.effort),
       profile: policy.profile,
       agentProfile,
-      ...workspaceSpawnParams(),
       cwd: policy.cwd || orchestrator.baseDir,
       workspaceMode: policy.workspaceMode ?? "inherit",
       label,
@@ -575,7 +536,7 @@ function dispatchOnDemandAutomation(
         label,
         createdBy: "automation",
       }),
-    },
+    }),
   });
   const result = createRunTask(automation, run, `label:${label}`, now, {
     targetMode: "on_demand_agent",

package/src/bus.ts

@@ -3,6 +3,7 @@ import { createActivityEvent, getAgent, getDb, heartbeat, markReady, mergeAgentM
 import { getOldestOutboxCursor, getOutboxCursor, replayEvents, type BusEvent } from "./bus-outbox";
 import { emitRelayEvent, subscribeRelayEvents, type RelayEvent } from "./events";
 import { createCommand, getCommand, updateCommand } from "./commands-db";
+import { emitCommandEvent } from "./command-events";
 import { getLifecycleManager } from "./lifecycle-manager";
 import { noteAgentTimelineEvent, noteCompactionCommandCompleted } from "./compaction-watch";
 import { applyCommandToRecipe } from "./recipe-runner";
@@ -13,6 +14,7 @@ import {
   type BusFrame,
   type RegisterFrame,
 } from "agent-relay-sdk/protocol";
+import { errMessage, isRecord, stringValue } from "agent-relay-sdk";
 import { getComponentAuth, isComponentAuthorizedFor, isAuthorized, isOriginAllowed, unauthorized } from "./security";
 import type { AgentCard, Command, ComponentToken, ContextState, Message, ProviderCapabilities, Task } from "./types";
 
@@ -77,7 +79,7 @@ export function busHandleMessage(ws: BusWebSocket, data: string | Buffer): void
   try {
     handleFrame(ws, frame);
   } catch (error) {
-    sendError(ws, frame.id, "FRAME_FAILED", error instanceof Error ? error.message : String(error));
+    sendError(ws, frame.id, "FRAME_FAILED", errMessage(error));
   }
 }
 
@@ -611,15 +613,6 @@ function providerStateKey(state: Record<string, unknown> | null): string | null
   return [state.state, typeof state.reason === "string" ? state.reason : ""].join(":");
 }
 
-function emitCommandEvent(command: Command, type: string): void {
-  emitRelayEvent({
-    type,
-    source: command.source,
-    subject: command.id,
-    data: { command },
-  });
-}
-
 function sendCommandResult(
   ws: BusWebSocket,
   commandId: string,
@@ -638,14 +631,6 @@ function sendCommandResult(
   });
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
-
-function stringValue(value: unknown): string | undefined {
-  return typeof value === "string" && value.length > 0 ? value : undefined;
-}
-
 function send(ws: BusWebSocket, frame: Record<string, unknown>): void {
   ws.send(JSON.stringify(frame));
 }

package/src/cli.ts

@@ -44,6 +44,9 @@ import {
 import { formatMemoryBrokerSmokeResult, runMemoryBrokerSmoke } from "./memory-broker-smoke";
 import { MAX_BODY_BYTES, VERSION } from "./config";
 import { DEFAULT_CONTEXT_PROBE_STATE_DIR, runContextProbe } from "agent-relay-sdk/context-probe";
+import { shellQuote } from "agent-relay-sdk/shell-utils";
+import { RELAY_TOKEN_HEADER } from "agent-relay-sdk";
+import type { WorkspaceDepsRefreshResult } from "agent-relay-sdk";
 
 const HELP = `
 agent-relay ${VERSION}
@@ -62,6 +65,8 @@ Usage:
   agent-relay context-probe [print-status-line] [--wrap COMMAND] [--agent-id ID] [--state-dir DIR] [--standalone]
   agent-relay token <create|list|revoke|verify> [options]
   agent-relay pair <target|create|status|accept|reject|hangup|send> [options]
+  agent-relay workspace <status|diagnostics|ready|land|claim|release|list|cleanup-stale|deps> [--id ID] [--strategy …] [--purpose TEXT] [--repo PATH] [--check] [--execute] [--json]
+  agent-relay steward <queue|inspect|checks> [WORKSPACE_ID] [--repo PATH] [--json]
   agent-relay message <target> <body> [options]
   agent-relay get-message <messageId> [--json|--body]
   agent-relay /pair <target|accept|reject|send|status> [...]
@@ -219,6 +224,21 @@ Labels and tags
   agent-relay /label [LABEL]
   agent-relay /tags [TAG ...]
 
+Isolated workspaces
+  If you are working in an isolated workspace (a git worktree on an agent
+  branch, not the main checkout), you do NOT rebase, merge, or push yourself —
+  Relay does. Just commit your work in the worktree, then:
+    agent-relay workspace ready    Hand off: Relay rebases onto the latest base,
+                                   lands your work, and pushes.
+    agent-relay workspace status   Show your workspace's branch, base, status.
+  The base branch will move as other agents land in parallel — that is normal,
+  let the merge handle it. Never push your branch yourself; it is local-only.
+  If typecheck/build fails on a missing module (a dep added to the base after
+  your worktree was created), do NOT run a clean install — it mutates the shared
+  node_modules. Instead refresh your worktree's deps in isolation:
+    agent-relay workspace deps     Re-provision deps that have gone stale.
+    agent-relay workspace deps --check   Report staleness without installing.
+
 Rules of thumb
   If you are handling relay message #123, reply with:
     agent-relay /reply 123 "<response>"
@@ -347,6 +367,14 @@ export async function handleCli(args: string[]): Promise<"start" | "handled"> {
     await handleTagsCommand(args.slice(1));
     return "handled";
   }
+  if (command === "workspace" || command === "workspaces") {
+    await handleWorkspaceCommand(args.slice(1));
+    return "handled";
+  }
+  if (command === "steward" || command === "stewards") {
+    await handleStewardCommand(args.slice(1));
+    return "handled";
+  }
   if (command === "/reconnect") {
     console.log("Reconnect is handled automatically by provider runners; use `agent-relay pair status` to inspect current pair state.");
     return "handled";
@@ -605,10 +633,6 @@ async function readStdin(): Promise<string> {
   return value;
 }
 
-function shellQuote(value: string): string {
-  return `'${value.replace(/'/g, `'\\''`)}'`;
-}
-
 function currentClaudeStatusLineCommand(): string | undefined {
   const settingsPath = join(process.env.HOME || homedir(), ".claude", "settings.json");
   try {
@@ -994,7 +1018,7 @@ async function exchangeOrchestratorBootstrapToken(relayUrl: string, bootstrapTok
     method: "POST",
     headers: {
       "Content-Type": "application/json",
-      "X-Agent-Relay-Token": bootstrapToken,
+      [RELAY_TOKEN_HEADER]: bootstrapToken,
     },
     body: JSON.stringify({ id, baseDir }),
   });
@@ -1376,6 +1400,219 @@ async function handlePairCommand(args: string[]): Promise<void> {
   }
 }
 
+// The agent's own isolated-workspace id, published in AGENT_RELAY_WORKSPACE_JSON
+// by the orchestrator at spawn. Undefined for shared-workspace / non-managed agents.
+function currentWorkspaceId(): string | undefined {
+  const json = process.env.AGENT_RELAY_WORKSPACE_JSON;
+  if (!json) return undefined;
+  try {
+    const parsed = JSON.parse(json) as { id?: string };
+    return typeof parsed.id === "string" && parsed.id ? parsed.id : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function formatWorkspaceStatus(ws: any): string {
+  const lines = [
+    `Workspace ${ws.id}`,
+    `  status:   ${ws.status}`,
+    `  branch:   ${ws.branch ?? "(none)"}`,
+    `  base:     ${ws.baseRef ?? "(none)"}`,
+    `  worktree: ${ws.worktreePath ?? "(none)"}`,
+  ];
+  return lines.join("\n");
+}
+
+// Poll a command to a terminal state (succeeded/failed). Returns undefined on
+// timeout so the caller can degrade to "dispatched, check later".
+async function pollCommand(id: string, timeoutMs: number): Promise<{ status?: string; result?: unknown; error?: string } | undefined> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const cmd = await apiRequest("GET", `/api/commands/${encodeURIComponent(id)}`) as { status?: string; result?: unknown; error?: string };
+    if (cmd.status === "succeeded" || cmd.status === "failed") return cmd;
+    await new Promise((r) => setTimeout(r, 1000));
+  }
+  return undefined;
+}
+
+function formatDepsRefresh(result: WorkspaceDepsRefreshResult, checkOnly: boolean): string {
+  if (result.error && (!result.dirs || result.dirs.length === 0)) return `Deps ${checkOnly ? "check" : "refresh"}: ${result.error}`;
+  const lines: string[] = [];
+  for (const d of result.dirs) {
+    const icon = d.status === "installed" ? "↻" : d.status === "stale" ? "✗" : d.status === "failed" ? "!" : "✓";
+    const detail = d.status === "ok" ? "up to date"
+      : d.status === "installed" ? `reinstalled${d.wasSymlink ? " (was symlinked)" : ""}`
+      : d.status === "stale" ? `stale — missing ${d.missing?.join(", ") ?? "?"}`
+      : `failed — ${d.error ?? "unknown"}`;
+    lines.push(`  ${icon} ${d.dir}: ${detail}`);
+  }
+  const header = checkOnly
+    ? (result.stale ? "Deps check: stale dirs found — run `agent-relay workspace deps` to refresh" : "Deps check: all dirs up to date")
+    : (result.refreshed ? "Deps refreshed" : result.error ? "Deps refresh hit errors" : "Deps already up to date");
+  return [header, ...lines].join("\n");
+}
+
+// Self-service workspace lifecycle for agents in isolated worktrees (#205) plus
+// steward coordination (#208).
+//   status — read your workspace row     ready — hand off for review/landing
+//   land   — request a base merge (operator)   list — all workspaces
+//   diagnostics — joined briefing + recommended action
+//   claim/release — TTL'd steward lease auto-merge yields to
+//   cleanup-stale — guarded batch cleanup of stale worktrees (dry-run by default)
+async function handleWorkspaceCommand(args: string[]): Promise<void> {
+  const action = args[0];
+  const valid = new Set(["status", "ready", "land", "list", "diagnostics", "diag", "claim", "release", "cleanup-stale", "deps"]);
+  if (!action || !valid.has(action)) {
+    throw new Error("Usage: agent-relay workspace <status|diagnostics|ready|land|claim|release|list|cleanup-stale|deps> [--id ID] [--strategy …] [--purpose TEXT] [--repo PATH] [--check] [--execute] [--json]");
+  }
+
+  let id = currentWorkspaceId();
+  let strategy: string | undefined;
+  let purpose: string | undefined;
+  let repo: string | undefined;
+  let execute = false;
+  let check = false;
+  let json = false;
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--id" && i + 1 < args.length) id = args[++i];
+    else if (arg === "--strategy" && i + 1 < args.length) strategy = args[++i];
+    else if (arg === "--purpose" && i + 1 < args.length) purpose = args[++i];
+    else if (arg === "--repo" && i + 1 < args.length) repo = args[++i];
+    else if (arg === "--execute") execute = true;
+    else if (arg === "--check") check = true;
+    else if (arg === "--refresh") check = false; // explicit no-op default for clarity
+    else if (arg === "--json") json = true;
+    else throw new Error(`Unknown workspace option "${arg}".`);
+  }
+
+  if (action === "list") {
+    console.log(JSON.stringify(await apiRequest("GET", "/api/workspaces"), null, 2));
+    return;
+  }
+
+  if (action === "cleanup-stale") {
+    const result = await apiRequest("POST", "/api/workspaces/actions/cleanup-stale", { repoRoot: repo, dryRun: !execute });
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  if (!id) throw new Error("No current workspace detected (AGENT_RELAY_WORKSPACE_JSON unset). Pass --id WORKSPACE_ID — only isolated-workspace agents have one.");
+
+  if (action === "status") {
+    const ws = await apiRequest("GET", `/api/workspaces/${encodeURIComponent(id)}`);
+    if (json) console.log(JSON.stringify(ws, null, 2));
+    else console.log(formatWorkspaceStatus(ws));
+    return;
+  }
+
+  if (action === "diagnostics" || action === "diag") {
+    console.log(JSON.stringify(await apiRequest("GET", `/api/workspaces/${encodeURIComponent(id)}/diagnostics`), null, 2));
+    return;
+  }
+
+  // Refresh (or --check) deps the shared symlinked node_modules has gone stale on
+  // (#51). Emits a host command; poll it to a terminal state so the agent gets a
+  // synchronous result and knows when to re-run typecheck.
+  if (action === "deps") {
+    const from = await detectAgentId();
+    const res = await apiRequest("POST", `/api/workspaces/${encodeURIComponent(id)}/actions`, { action: "deps-refresh", agentId: from, checkOnly: check }) as { command?: { id?: string } };
+    const commandId = res.command?.id;
+    const settled = commandId ? await pollCommand(commandId, 180_000) : undefined;
+    const result = (settled?.result ?? null) as WorkspaceDepsRefreshResult | null;
+    if (json) {
+      console.log(JSON.stringify(settled ?? res, null, 2));
+      return;
+    }
+    if (settled?.status === "failed") {
+      console.error(`Deps ${check ? "check" : "refresh"} failed: ${settled.error ?? "unknown error"}`);
+      process.exitCode = 1;
+      return;
+    }
+    if (!result) {
+      console.log(`Deps ${check ? "check" : "refresh"} dispatched (command ${commandId ?? "?"}) — host did not report back in time. Check \`agent-relay workspace deps --json\`.`);
+      return;
+    }
+    console.log(formatDepsRefresh(result, check));
+    return;
+  }
+
+  const from = await detectAgentId();
+  const actionBody: Record<string, unknown> =
+    action === "ready" ? { action: "request-review", agentId: from }
+    : action === "claim" ? { action: "claim", agentId: from, purpose }
+    : action === "release" ? { action: "release-claim", agentId: from }
+    : { action: "merge", agentId: from, ...(strategy ? { strategy } : {}) };
+  const result = await apiRequest("POST", `/api/workspaces/${encodeURIComponent(id)}/actions`, actionBody);
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(
+    action === "ready" ? `Workspace ${id} marked ready — Relay will rebase onto the latest base, land, and push.`
+    : action === "claim" ? `Workspace ${id} claimed${purpose ? ` (${purpose})` : ""} — auto-merge will yield until released or the claim expires.`
+    : action === "release" ? `Workspace ${id} claim released.`
+    : `Workspace ${id} merge requested (${strategy ?? "auto"}).`,
+  );
+}
+
+// Steward briefing commands (#208): queue of workspaces needing attention, a
+// per-workspace diagnostics inspection, and a check-command suggestion.
+async function handleStewardCommand(args: string[]): Promise<void> {
+  const action = args[0];
+  if (!action || !["queue", "inspect", "checks"].includes(action)) {
+    throw new Error("Usage: agent-relay steward <queue|inspect|checks> [WORKSPACE_ID] [--repo PATH] [--json]");
+  }
+
+  let repo: string | undefined;
+  let json = false;
+  const positional: string[] = [];
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--repo" && i + 1 < args.length) repo = args[++i];
+    else if (arg === "--json") json = true;
+    else if (!arg!.startsWith("--")) positional.push(arg!);
+    else throw new Error(`Unknown steward option "${arg}".`);
+  }
+
+  if (action === "queue") {
+    const all = await apiRequest("GET", "/api/workspaces") as any[];
+    const attention = new Set(["conflict", "review_requested", "merge_planned"]);
+    const queue = all.filter((ws) => attention.has(ws.status) && (!repo || ws.repoRoot === repo));
+    if (json) { console.log(JSON.stringify(queue, null, 2)); return; }
+    if (!queue.length) { console.log("Steward queue empty — no workspaces awaiting review, merge, or conflict resolution."); return; }
+    for (const ws of queue) console.log(`${ws.status.padEnd(16)} ${ws.branch ?? ws.id}  (${ws.repoRoot})`);
+    return;
+  }
+
+  const id = positional[0];
+  if (!id) throw new Error(`Usage: agent-relay steward ${action} WORKSPACE_ID [--json]`);
+
+  if (action === "inspect") {
+    console.log(JSON.stringify(await apiRequest("GET", `/api/workspaces/${encodeURIComponent(id)}/diagnostics`), null, 2));
+    return;
+  }
+
+  // checks: suggest validation commands from the workspace's changed files.
+  const diff = await apiRequest("GET", `/api/workspaces/${encodeURIComponent(id)}/diff?patch=0`) as any;
+  const files: string[] = Array.isArray(diff?.files) ? diff.files.map((f: any) => f.path) : [];
+  const checks = suggestStewardChecks(files);
+  console.log(JSON.stringify({ workspaceId: id, changedFiles: files.length, checks }, null, 2));
+}
+
+// Heuristic check suggestions from changed file paths. Repo-agnostic defaults a
+// steward can refine; cheaper than re-deriving from project docs every run.
+function suggestStewardChecks(files: string[]): Array<{ command: string; reason: string }> {
+  const checks: Array<{ command: string; reason: string }> = [];
+  const has = (re: RegExp) => files.some((f) => re.test(f));
+  if (has(/\.(ts|tsx|mts|cts)$/)) checks.push({ command: "bun run typecheck", reason: "TypeScript files changed" });
+  if (has(/\.test\.|(^|\/)tests?\//)) checks.push({ command: "bun test", reason: "test files changed" });
+  else if (files.length) checks.push({ command: "bun test", reason: "repo default" });
+  if (has(/(^|\/)dashboard\//)) checks.push({ command: "bun run build:dashboard", reason: "dashboard sources changed" });
+  return checks;
+}
+
 async function handleMessageCommand(args: string[], defaults: { claimable?: boolean } = {}): Promise<void> {
   const target = args[0];
   if (!target || target.startsWith("--")) {
@@ -1989,7 +2226,7 @@ async function apiRequest(method: string, path: string, body?: unknown): Promise
   const baseUrl = process.env.AGENT_RELAY_URL || "http://127.0.0.1:4850";
   const headers: Record<string, string> = {};
   const token = process.env.AGENT_RELAY_TOKEN;
-  if (token) headers["X-Agent-Relay-Token"] = token;
+  if (token) headers[RELAY_TOKEN_HEADER] = token;
   if (body !== undefined) headers["Content-Type"] = "application/json";
   const response = await fetch(new URL(path, baseUrl), {
     method,
@@ -2009,7 +2246,7 @@ async function apiRawRequest(method: string, path: string, body: BodyInit, extra
   const baseUrl = process.env.AGENT_RELAY_URL || "http://127.0.0.1:4850";
   const headers: Record<string, string> = { ...extraHeaders };
   const token = process.env.AGENT_RELAY_TOKEN;
-  if (token) headers["X-Agent-Relay-Token"] = token;
+  if (token) headers[RELAY_TOKEN_HEADER] = token;
   const response = await fetch(new URL(path, baseUrl), { method, headers, body });
   const text = await response.text();
   const payload = text ? JSON.parse(text) : null;

package/src/command-events.ts

@@ -0,0 +1,26 @@
+import { emitRelayEvent } from "./events";
+import type { Command } from "./types";
+
+/**
+ * Emit the relay event for a command. Single home — was duplicated as bus.ts's
+ * `emitCommandEvent(command, type)` and lifecycle-manager's private
+ * `emitCommand(command)` (which hardcoded "command.requested").
+ *
+ * The caller passes the exact event type: "command.requested" for a freshly
+ * created command (the relay auto-emits the follow-up "command.dispatched" — see
+ * `events.ts`), or `command.<status>` after an update.
+ *
+ * Deliberately NO `commandEventType(command)` derivation helper: a
+ * pending→"command.requested" mapping would diverge from the literal
+ * `command.<status>` used on the update path and spuriously trigger the
+ * requested→dispatched fan-out for a (valid, externally reachable) update to
+ * status "pending". Pass the type explicitly.
+ */
+export function emitCommandEvent(command: Command, type: string): void {
+  emitRelayEvent({
+    type,
+    source: command.source,
+    subject: command.id,
+    data: { command },
+  });
+}