agent-relay-server 0.16.0 → 0.18.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 { cleanString } from "./validation";
 import { getAgentProfile, getSpawnPolicy } from "./config-store";
-import { resolveProviderSelection, type ProviderEffort } from "agent-relay-sdk/provider-catalog";
+import { buildSpawnCommand, resolveSpawnModelParams } from "./spawn-command";
+import { resolveProviderSelection, type ProviderEffort, VALID_EFFORTS } from "agent-relay-sdk/provider-catalog";
+import { 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,18 +119,6 @@ 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`);
@@ -544,19 +525,15 @@ 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,
       cwd: policy.cwd || orchestrator.baseDir,
@@ -574,7 +551,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 { 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";
 
@@ -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,7 @@ 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 { RELAY_TOKEN_HEADER } from "agent-relay-sdk";
 
 const HELP = `
 agent-relay ${VERSION}
@@ -62,6 +63,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> [--id ID] [--strategy …] [--purpose TEXT] [--repo PATH] [--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 +222,16 @@ 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.
+
 Rules of thumb
   If you are handling relay message #123, reply with:
     agent-relay /reply 123 "<response>"
@@ -347,6 +360,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";
@@ -994,7 +1015,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 +1397,161 @@ 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");
+}
+
+// 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"]);
+  if (!action || !valid.has(action)) {
+    throw new Error("Usage: agent-relay workspace <status|diagnostics|ready|land|claim|release|list|cleanup-stale> [--id ID] [--strategy …] [--purpose TEXT] [--repo PATH] [--execute] [--json]");
+  }
+
+  let id = currentWorkspaceId();
+  let strategy: string | undefined;
+  let purpose: string | undefined;
+  let repo: string | undefined;
+  let execute = 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 === "--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;
+  }
+
+  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 +2165,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 +2185,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 },
+  });
+}

package/src/config-store.ts

@@ -1,5 +1,7 @@
 import { getDb, ValidationError } from "./db";
+import { cleanString } from "./validation";
 import { resolveProviderSelection, type ProviderEffort } from "agent-relay-sdk/provider-catalog";
+import { isRecord, SPAWN_PROVIDERS, VALID_EFFORTS, VALID_WORKSPACE_MODES } from "agent-relay-sdk";
 import type {
   AgentProfile,
   AgentProfileBase,
@@ -12,6 +14,7 @@ import type {
   SpawnPolicy,
   SpawnProvider,
   StewardConfig,
+  WorkspaceConfig,
 } from "./types";
 
 const CONFIG_HISTORY_LIMIT = 50;
@@ -21,18 +24,17 @@ const STEWARD_NAMESPACE = "steward";
 const STEWARD_KEY = "default";
 const INSIGHTS_NAMESPACE = "insights";
 const INSIGHTS_KEY = "default";
-const VALID_PROVIDERS = ["claude", "codex"] as const;
+const WORKSPACE_NAMESPACE = "workspace";
+const WORKSPACE_KEY = "default";
 const VALID_PROFILE_PROVIDERS = ["any", "claude", "codex"] as const;
 const VALID_PROFILE_BASES = ["host", "minimal", "isolated"] as const;
 const VALID_PROFILE_INSTRUCTION_POLICIES = ["allow", "ignore"] as const;
 const VALID_PROFILE_CATEGORY_MODES = ["host", "profile", "repo", "none"] as const;
 const VALID_PROFILE_ASSET_SOURCES = ["relay", "repo", "inline", "provider"] as const;
 const VALID_PROFILE_FILESYSTEM_SCOPES = ["repo", "workspace", "host"] as const;
-const VALID_EFFORTS = ["low", "medium", "high", "xhigh", "max"] as const;
 const VALID_PERMISSION_MODES = ["open", "guarded", "read-only"] as const;
 const VALID_POLICY_MODES = ["always-on", "on-demand"] as const;
 const VALID_MANAGED_STATUSES = ["stopped", "starting", "running", "stopping", "backoff"] as const;
-const VALID_WORKSPACE_MODES = ["isolated", "shared", "inherit"] as const;
 const BUILT_IN_AGENT_PROFILE_NAMES = new Set(["default-relay", "minimal", "isolated-research"]);
 
 const BUILT_IN_AGENT_PROFILES: AgentProfile[] = [
@@ -153,22 +155,6 @@ function rowToManagedAgentState(row: ManagedAgentStateRow): ManagedAgentState {
   };
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-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, opts: { required?: boolean } = {}): string[] {
   if (value === undefined || value === null) {
     if (opts.required) throw new ValidationError(`${field} required`);
@@ -340,7 +326,7 @@ function validateSpawnPolicy(key: string, value: unknown): SpawnPolicy {
     enabled: value.enabled === undefined ? true : cleanBoolean(value.enabled, "enabled"),
     orchestratorId: cleanString(value.orchestratorId, "orchestratorId", { required: true, max: 200 })!,
     cwd: cleanString(value.cwd, "cwd", { required: true, max: 1000 })!,
-    provider: cleanEnum(value.provider, "provider", VALID_PROVIDERS) as SpawnProvider,
+    provider: cleanEnum(value.provider, "provider", SPAWN_PROVIDERS) as SpawnProvider,
     workspaceMode: value.workspaceMode === undefined || value.workspaceMode === null ? "inherit" : cleanEnum(value.workspaceMode, "workspaceMode", VALID_WORKSPACE_MODES),
     rig: cleanString(value.rig, "rig", { max: 120 }),
     model: cleanString(value.model, "model", { max: 120 }),
@@ -408,7 +394,7 @@ function validateStewardConfig(value: unknown): StewardConfig {
   if (!isRecord(value)) throw new ValidationError("steward config value must be an object");
   const config: StewardConfig = {
     enabled: value.enabled === undefined ? false : cleanBoolean(value.enabled, "enabled"),
-    provider: cleanEnum(value.provider, "provider", VALID_PROVIDERS) as SpawnProvider,
+    provider: cleanEnum(value.provider, "provider", SPAWN_PROVIDERS) as SpawnProvider,
     model: cleanString(value.model, "model", { max: 120 }),
     effort: value.effort === undefined || value.effort === null ? undefined : cleanEnum(value.effort, "effort", VALID_EFFORTS) as ProviderEffort,
     permissionMode: (value.permissionMode === undefined || value.permissionMode === null
@@ -472,12 +458,34 @@ function validateInsightsConfig(value: unknown): InsightsConfig {
   };
 }
 
+// Global workspace provisioning config for isolated worktrees (#159 follow-up).
+// Defaults seed the two untracked paths an isolated agent almost always needs:
+// the agent guide and the rig config, both gitignored so a fresh worktree lacks them.
+const WORKSPACE_CONFIG_DEFAULTS: WorkspaceConfig = {
+  symlinkPaths: ["AGENTS.md", ".claude-rig"],
+};
+
+function validateWorkspaceConfig(value: unknown): WorkspaceConfig {
+  if (!isRecord(value)) throw new ValidationError("workspace config value must be an object");
+  const symlinkPaths = cleanStringArray(value.symlinkPaths, "symlinkPaths");
+  // Reject absolute paths and parent-traversal up front: symlink sources must stay
+  // inside the main checkout. The orchestrator re-checks containment at link time,
+  // but failing here gives the operator immediate feedback in the dashboard.
+  for (const entry of symlinkPaths) {
+    if (entry.startsWith("/") || entry.split(/[\\/]/).includes("..")) {
+      throw new ValidationError(`symlinkPaths entry must be a relative path within the repo: ${entry}`);
+    }
+  }
+  return { symlinkPaths };
+}
+
 function normalizeValue(namespace: string, key: string, value: unknown): unknown {
   if (value === undefined) throw new ValidationError("value required");
   if (namespace === SPAWN_POLICY_NAMESPACE) return validateSpawnPolicy(key, value);
   if (namespace === AGENT_PROFILE_NAMESPACE) return validateAgentProfile(key, value);
   if (namespace === STEWARD_NAMESPACE) return validateStewardConfig(value);
   if (namespace === INSIGHTS_NAMESPACE) return validateInsightsConfig(value);
+  if (namespace === WORKSPACE_NAMESPACE) return validateWorkspaceConfig(value);
   if (JSON.stringify(value) === undefined) throw new ValidationError("value must be valid JSON");
   return value;
 }
@@ -614,6 +622,40 @@ export function setInsightsConfig(value: unknown, updatedBy?: string): ConfigEnt
   return setConfig(INSIGHTS_NAMESPACE, INSIGHTS_KEY, value as InsightsConfig, updatedBy);
 }
 
+/** Global workspace config, merged over defaults (always returns a usable value). */
+export function getWorkspaceConfig(): WorkspaceConfig {
+  const entry = getConfig<Partial<WorkspaceConfig>>(WORKSPACE_NAMESPACE, WORKSPACE_KEY);
+  if (!entry) return { ...WORKSPACE_CONFIG_DEFAULTS };
+  return validateWorkspaceConfig({ ...WORKSPACE_CONFIG_DEFAULTS, ...entry.value });
+}
+
+export function getWorkspaceConfigEntry(): ConfigEntry<WorkspaceConfig> {
+  const entry = getConfig<WorkspaceConfig>(WORKSPACE_NAMESPACE, WORKSPACE_KEY);
+  return entry ?? {
+    namespace: WORKSPACE_NAMESPACE,
+    key: WORKSPACE_KEY,
+    value: { ...WORKSPACE_CONFIG_DEFAULTS },
+    version: 0,
+    updatedAt: "default",
+    updatedBy: "system",
+  };
+}
+
+export function setWorkspaceConfig(value: unknown, updatedBy?: string): ConfigEntry<WorkspaceConfig> {
+  return setConfig(WORKSPACE_NAMESPACE, WORKSPACE_KEY, value as WorkspaceConfig, updatedBy);
+}
+
+/**
+ * Spawn-param fragment carrying the global workspace symlink list to the orchestrator.
+ * Spread into every spawn command's params next to `agentProfile` so any isolated
+ * worktree — direct spawn, managed policy, restart, automation — provisions the same
+ * untracked paths. Returns `{}` when nothing is configured (keeps params lean).
+ */
+export function workspaceSpawnParams(): { workspaceSymlinks?: string[] } {
+  const { symlinkPaths } = getWorkspaceConfig();
+  return symlinkPaths.length ? { workspaceSymlinks: symlinkPaths } : {};
+}
+
 function builtInProfileEntry(profile: AgentProfile): ConfigEntry<AgentProfile> {
   return {
     namespace: AGENT_PROFILE_NAMESPACE,
@@ -662,7 +704,7 @@ function listManagedAgentStates(): ManagedAgentState[] {
 
 export function upsertManagedAgentState(input: ManagedAgentStateInput): ManagedAgentState {
   if (!VALID_MANAGED_STATUSES.includes(input.status)) throw new ValidationError("status must be a managed-agent status");
-  if (!VALID_PROVIDERS.includes(input.provider)) throw new ValidationError("provider must be claude or codex");
+  if (!SPAWN_PROVIDERS.includes(input.provider)) throw new ValidationError("provider must be claude or codex");
   const now = input.updatedAt ?? Date.now();
   getDb().query(`
     INSERT INTO managed_agent_state (

package/src/connectors.ts

@@ -3,6 +3,7 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import type { ConnectorAction, ConnectorActionResult, ConnectorManifest, ConnectorSummary } from "./types";
 import { ValidationError } from "./db";
+import { isRecord } from "agent-relay-sdk";
 
 const CONNECTOR_SCHEMA = "agent-relay.connector.v1";
 const VALID_KINDS = new Set(["channel", "event", "provider", "orchestrator"]);
@@ -34,10 +35,6 @@ function readRecordFile(path: string): Record<string, unknown> | undefined {
   return isRecord(parsed) ? parsed : undefined;
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 function validateConnectorId(id: string): void {
   if (!/^[a-z0-9][a-z0-9._-]{0,79}$/.test(id)) {
     throw new ValidationError("connector id must be lowercase alphanumeric plus dot, underscore, or dash");

package/src/contracts.ts

@@ -1,3 +1,5 @@
+import { isRecord, stringValue } from "agent-relay-sdk";
+
 export const CONTRACT_VERSIONS = {
   relayApi: 1,
   orchestratorProtocol: 3,
@@ -95,10 +97,6 @@ function rangeLabel(requirement: ContractRequirement): string {
   return `>=${requirement.min} <${requirement.maxExclusive}`;
 }
 
-function stringValue(value: unknown): string | undefined {
-  return typeof value === "string" && value.trim() ? value.trim() : undefined;
-}
-
 function positiveInteger(value: unknown): number | undefined {
   const parsed = typeof value === "number"
     ? value
@@ -106,7 +104,3 @@ function positiveInteger(value: unknown): number | undefined {
   if (parsed === undefined || !Number.isInteger(parsed) || parsed <= 0) return undefined;
   return parsed;
 }
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}