agent-relay-server 0.17.0 → 0.19.0

package/src/security.ts

@@ -1,8 +1,9 @@
 import { AUTH_TOKEN, CORS_ORIGINS, getIntegrationTokens, type IntegrationTokenConfig } from "./config";
 import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { getDb } from "./db";
+import { isPathWithinBase } from "./utils";
 import type { ComponentToken, TokenConstraints } from "./types";
 
 const LOOPBACK_HOSTS = new Set(["127.0.0.1", "::1", "localhost"]);
@@ -427,15 +428,10 @@ function prefixAllows(allowed: string[] | undefined, value: string): boolean {
 
 function cwdAllows(constraints: TokenConstraints, cwd: string): boolean {
   if (constraints.cwd && resolve(cwd) !== resolve(constraints.cwd)) return false;
-  if (constraints.cwdPrefixes?.length && !constraints.cwdPrefixes.some((prefix) => pathWithin(resolve(cwd), resolve(prefix)))) return false;
+  if (constraints.cwdPrefixes?.length && !constraints.cwdPrefixes.some((prefix) => isPathWithinBase(cwd, prefix))) return false;
   return true;
 }
 
-function pathWithin(path: string, baseDir: string): boolean {
-  const rel = relative(baseDir, path);
-  return rel === "" || (!!rel && !rel.startsWith("..") && !isAbsolute(rel));
-}
-
 function isTokenConstraints(value: unknown): value is TokenConstraints {
   if (!value || typeof value !== "object" || Array.isArray(value)) return false;
   const record = value as Record<string, unknown>;

package/src/setup.ts

@@ -1,4 +1,5 @@
 import { randomBytes } from "node:crypto";
+import { shellQuote } from "agent-relay-sdk/shell-utils";
 import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import { constants } from "node:fs";
 import { homedir } from "node:os";
@@ -191,10 +192,6 @@ function normalizePort(port: number | undefined): number {
   return value;
 }
 
-function shellQuote(value: string): string {
-  return `'${value.replace(/'/g, "'\\''")}'`;
-}
-
 function redactEnv(content: string): string {
   return content.replace(/^(AGENT_RELAY_TOKEN=).+$/m, "$1'<generated-token>'");
 }

package/src/spawn-command.ts

@@ -0,0 +1,151 @@
+import { randomUUID } from "node:crypto";
+import type { SpawnProvider } from "agent-relay-sdk";
+import { errMessage } from "agent-relay-sdk";
+import { resolveProviderSelection, type ProviderEffort } from "agent-relay-sdk/provider-catalog";
+import { workspaceSpawnParams } from "./config-store";
+import { ValidationError } from "./db";
+
+/** Resolved provider/model/effort triple — the output shape of every model-resolution wrapper. */
+export interface SpawnModelParams {
+  model?: string;
+  providerModel?: string;
+  effort?: string;
+}
+
+/** `sp_`-prefixed correlation id for a spawn request. Single home — was inlined in 5 places. */
+export function generateSpawnRequestId(): string {
+  return `sp_${randomUUID()}`;
+}
+
+export interface ResolveSpawnModelParamsOptions {
+  /**
+   * What to do when provider-catalog resolution throws (e.g. unknown model, or
+   * effort without a model):
+   * - `"throw"` (default) — re-throw as a `ValidationError` (dashboard/mcp/automation paths).
+   * - `"passthrough"` — swallow and return the raw `{model, effort}` (managed-policy/restart paths).
+   */
+  onError?: "throw" | "passthrough";
+  /**
+   * When `true`, empty input (no model, no effort) returns `{}` instead of resolving
+   * the provider's *default* model. The managed-policy and restart paths use this so a
+   * spawn with no explicit model carries no model override; the dashboard/mcp/automation
+   * paths leave it `false` so the catalog default is injected (their original behavior).
+   */
+  skipDefaultWhenEmpty?: boolean;
+}
+
+/**
+ * Resolve `{model, providerModel, effort}` for a spawn payload. Single home for
+ * the 5 selection wrappers that each called `resolveProviderSelection` then mapped
+ * the result — with inconsistent error handling (some threw, some passed through)
+ * and inconsistent empty-input handling (some injected the default model, some didn't).
+ */
+export function resolveSpawnModelParams(
+  provider: SpawnProvider | string,
+  model: string | undefined,
+  effort: string | undefined,
+  opts: ResolveSpawnModelParamsOptions = {},
+): SpawnModelParams {
+  if (!model && !effort && opts.skipDefaultWhenEmpty) return {};
+  try {
+    const selection = resolveProviderSelection({ provider: provider as SpawnProvider, model, effort: effort as ProviderEffort | undefined });
+    return {
+      ...(selection.modelAlias ? { model: selection.modelAlias } : {}),
+      ...(selection.providerModel ? { providerModel: selection.providerModel } : {}),
+      ...(selection.effort ? { effort: selection.effort } : {}),
+    };
+  } catch (error) {
+    if (opts.onError === "passthrough") {
+      return {
+        ...(model ? { model } : {}),
+        ...(effort ? { effort } : {}),
+      };
+    }
+    throw new ValidationError(errMessage(error));
+  }
+}
+
+/**
+ * Every field that can appear in a spawn command-bus payload.
+ * Optional fields are omitted from the result when undefined.
+ */
+export interface BuildSpawnCommandOptions {
+  provider: SpawnProvider | string;
+  cwd: string;
+  /** Correlation id; omitted from the payload when absent (e.g. automation spawns use automationRunId instead). */
+  spawnRequestId?: string;
+  env: Record<string, string>;
+  requestedBy: string;
+  requestedAt?: number;
+
+  /** Resolved {model, providerModel, effort}; spread verbatim. */
+  modelParams?: SpawnModelParams;
+
+  workspaceMode?: string;
+  label?: string;
+  tags?: string[];
+  capabilities?: string[];
+  approvalMode?: string;
+  permissionMode?: string;
+  providerArgs?: string[];
+  prompt?: string;
+  systemPromptAppend?: string;
+  profile?: string;
+  agentProfile?: unknown;
+  headless?: boolean;
+  policyName?: string;
+  rig?: string;
+  agentId?: string;
+  automationId?: string;
+  automationRunId?: string;
+  orchestratorId?: string;
+  requestedVia?: string;
+
+  /** Extra params merged last (e.g. Claude-resume fields). */
+  extra?: Record<string, unknown>;
+}
+
+/**
+ * Single home for the spawn command-bus payload. Previously hand-assembled in 6
+ * places (routes ×3, mcp, managed-policy, automations) which silently drifted —
+ * e.g. workspace-symlink params (`workspaceSpawnParams()`) were missing from the
+ * mcp and dashboard-quick-spawn paths. Building it here means a new spawn field is
+ * added once and every caller gets it. `workspaceSpawnParams()` is included for
+ * all callers (it only emits in isolated workspace mode; ignored otherwise).
+ */
+export function buildSpawnCommand(opts: BuildSpawnCommandOptions): Record<string, unknown> {
+  const def = <T>(value: T | undefined, key: string): Record<string, T> =>
+    value === undefined ? {} : { [key]: value };
+
+  return {
+    action: "spawn",
+    provider: opts.provider,
+    ...(opts.modelParams ?? {}),
+    cwd: opts.cwd,
+    ...def(opts.workspaceMode, "workspaceMode"),
+    ...def(opts.profile, "profile"),
+    ...def(opts.agentProfile, "agentProfile"),
+    ...workspaceSpawnParams(),
+    ...def(opts.rig, "rig"),
+    ...def(opts.label, "label"),
+    ...def(opts.agentId, "agentId"),
+    ...def(opts.tags, "tags"),
+    ...def(opts.capabilities, "capabilities"),
+    ...def(opts.approvalMode, "approvalMode"),
+    ...def(opts.permissionMode, "permissionMode"),
+    ...def(opts.providerArgs, "providerArgs"),
+    ...def(opts.prompt, "prompt"),
+    ...def(opts.systemPromptAppend, "systemPromptAppend"),
+    ...def(opts.headless, "headless"),
+    ...def(opts.policyName, "policyName"),
+    ...def(opts.automationId, "automationId"),
+    ...def(opts.automationRunId, "automationRunId"),
+    ...def(opts.orchestratorId, "orchestratorId"),
+    ...def(opts.requestedVia, "requestedVia"),
+    ...def(opts.spawnRequestId, "spawnRequestId"),
+    env: opts.env,
+    requestedBy: opts.requestedBy,
+    requestedAt: opts.requestedAt ?? Date.now(),
+    ...(opts.extra ?? {}),
+  };
+}

package/src/sse.ts

@@ -1,6 +1,7 @@
 import { getAgent, getOrchestrator } from "./db";
 import { emitRelayEvent, subscribeRelayEvents, type RelayEvent } from "./events";
 import type { ActivityEvent, AgentCard, Message, RelayNotification, Task } from "./types";
+import { isRecord } from "agent-relay-sdk";
 
 interface Connection {
   id: string;
@@ -231,10 +232,6 @@ function notificationTitleForAgent(agentId: string): string {
   return agent?.label || agent?.name || agentId;
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 function payloadMessageText(msg: Message): string {
   const message = msg.payload?.message;
   if (isRecord(message) && typeof message.text === "string" && message.text.trim()) return message.text.trim();

package/src/steward.ts

@@ -1,16 +1,10 @@
 import { createHash } from "node:crypto";
-import { basename, isAbsolute, relative, resolve } from "node:path";
+import { basename, resolve } from "node:path";
 import { getSpawnPolicy, getStewardConfig, setConfig } from "./config-store";
 import { listOrchestrators } from "./db";
 import { getLifecycleManager } from "./lifecycle-manager";
 import type { Orchestrator, SpawnPolicy, StewardConfig } from "./types";
-
-// Real path containment (same rule as routes/mcp/lifecycle): never string startsWith.
-function pathWithinBase(path: string | undefined, baseDir: string | undefined): boolean {
-  if (!path || !baseDir) return false;
-  const rel = relative(resolve(baseDir), resolve(path));
-  return rel === "" || (!!rel && !rel.startsWith("..") && !isAbsolute(rel));
-}
+import { isPathWithinBase } from "./utils";
 
 /** Stable, readable, collision-resistant policy name for a repo's steward. */
 export function repoStewardPolicyName(repoRoot: string): string {
@@ -21,26 +15,28 @@ export function repoStewardPolicyName(repoRoot: string): string {
 
 /**
  * The steward's system prompt — provider-agnostic (works for any provider/model).
- * It tells the agent the workflow: take the worktrees it can't auto-land, rebase,
- * resolve, run the repo's checks, and land green ones via the relay merge API;
- * escalate only what genuinely needs a human.
+ * It tells the agent the workflow via the `agent-relay workspace`/`steward` CLI
+ * toolkit (#208): see the queue, CLAIM a workspace so auto-merge yields, inspect
+ * its diagnostics, rebase/resolve/check, land green ones, release on escalation.
  */
 export function buildStewardPrompt(repoRoot: string): string {
   return [
     `You are the autonomous repository steward for ${repoRoot}.`,
     "",
-    "Multiple agents work this repo in isolated git worktrees. The relay auto-merges branches that fast-forward cleanly; it hands YOU the ones it can't — merge conflicts, or a branch whose base moved on (behind > 0). Your job is to land that work with no human in the loop whenever you safely can.",
+    "Multiple agents work this repo in isolated git worktrees. The relay auto-merges any branch that rebases cleanly — including ones whose base moved on; it hands YOU only what it can't land deterministically: real merge conflicts, or an unknown/ambiguous merge state. Your job is to land that work with no human in the loop whenever you safely can.",
     "",
-    "When woken, gather what needs attention: read the message(s) you were sent (each names a `workspaceId`, `worktreePath`, `branch`, `baseRef`, `status`), and also query `GET /api/workspaces?status=conflict` and `GET /api/workspaces?status=review_requested` for this repo. Handle one workspace at a time — the relay's per-repo merge lease serializes you with any other merger.",
+    "Use the `agent-relay` CLI for EVERY relay interaction — it wraps the relay API and is the supported toolkit, and it already attaches your session token with the right scopes. Do NOT hand-curl the HTTP API (`/api/workspaces`, …): the CLI exists so you never have to. If you ever truly must call the API directly, authenticate with the `X-Agent-Relay-Token: <your session token>` header — NOT `Authorization: Bearer $AGENT_RELAY_TOKEN`; the admin env token is not present in your environment, so Bearer will 401.",
+    "Handle ONE workspace at a time — the relay's per-repo merge lease serializes you with any other merger.",
     "",
-    "For each workspace:",
-    "1. `cd` into its `worktreePath`.",
-    "2. Rebase the branch onto its `baseRef` (`git rebase <baseRef>`).",
-    "3. Resolve any conflicts faithfully — preserve the intent of EVERY side; never silently drop a change. If a conflict needs product judgment you can't make confidently, stop and escalate.",
-    "4. Run the repo's checks/tests (look for the project's documented commands). Fix trivial breakage you caused while rebasing; do not paper over real failures.",
-    "5. If green, land it: `POST /api/workspaces/<id>/actions` with `{\"action\":\"merge\",\"strategy\":\"rebase-ff\"}`. The relay acquires the lease and dispatches the merge.",
+    "1. See the queue: `agent-relay steward queue` (workspaces in conflict / review_requested / merge_planned for this repo). The wake message(s) also name a `workspaceId`.",
+    "2. CLAIM it FIRST: `agent-relay workspace claim --id <id> --purpose steward`. This stops the deterministic auto-merge from racing you while you validate. The claim auto-expires, so a crash never blocks the repo.",
+    "3. Understand it: `agent-relay steward inspect <id>` — a diagnostics briefing (owner liveness, live git state, ahead/behind, recorded-vs-live branch mismatch, and a recommended action). `agent-relay steward checks <id>` suggests check commands from the changed files.",
+    "4. `cd` into the workspace's `worktreePath` and rebase the branch onto its `baseRef` (`git rebase <baseRef>`). Resolve conflicts faithfully — preserve the intent of EVERY side; never silently drop a change. If a conflict needs product judgment you can't make confidently, stop and escalate.",
+    "5. Run the repo's checks/tests (the suggested ones, plus the project's documented commands). Fix trivial breakage you caused while rebasing; do not paper over real failures.",
+    "6. If green, land it: `agent-relay workspace land --id <id> --strategy rebase-ff`. The relay rebases onto the latest base, fast-forwards, and pushes to origin under the lease. The land consumes your claim.",
+    "7. If you must stop without landing, RELEASE the claim so automation can resume: `agent-relay workspace release --id <id>`, then send a clear, specific summary to the fallback/human target.",
     "",
-    "Escalate (do NOT merge) when: checks fail and you can't fix them, the conflict resolution is genuinely ambiguous, or anything looks risky. Send a clear, specific summary to the configured fallback/human target and leave the workspace as-is. Never force-merge a red branch, never `git push --force` to a shared base, never discard committed work.",
+    "Escalate (do NOT merge) when: checks fail and you can't fix them, the conflict resolution is genuinely ambiguous, or anything looks risky. Never force-merge a red branch, never `git push --force` to a shared base, never discard committed work.",
     "",
     "Be terminal-efficient and decisive. When the queue is empty, you're done — you'll be woken again when there's more.",
   ].join("\n");
@@ -103,7 +99,7 @@ function stewardPolicyDiffers(existing: SpawnPolicy, desired: SpawnPolicy): bool
 export function ensureRepoSteward(repoRoot: string): string | null {
   const config = getStewardConfig();
   if (!config.enabled) return null;
-  const owner = listOrchestrators().find((orch) => pathWithinBase(repoRoot, orch.baseDir));
+  const owner = listOrchestrators().find((orch) => isPathWithinBase(repoRoot, orch.baseDir));
   if (!owner) return null;
 
   const name = repoStewardPolicyName(repoRoot);

package/src/upgrade.ts

@@ -4,6 +4,8 @@ import { join, resolve } from "node:path";
 import { VERSION } from "./config";
 import type { RuntimeContracts, RuntimePackageMetadata } from "./contracts";
 import { defaultRuntimePrefix, runtimeBinPath } from "./runtime-prefix";
+import { errMessage, RELAY_TOKEN_HEADER } from "agent-relay-sdk";
+import { shellEscape as shellQuote } from "agent-relay-sdk/shell-utils";
 
 export type UpgradeProvider = "auto" | "all" | "codex" | "claude" | "orchestrator";
 
@@ -244,9 +246,38 @@ export function createUpgradePlan(snapshot: UpgradeSnapshot, options: UpgradeOpt
   };
 }
 
-export async function executeUpgradePlan(plan: UpgradePlan, options: { dryRun?: boolean; runner?: Runner } = {}): Promise<string> {
+export type ExecuteUpgradeOptions = {
+  dryRun?: boolean;
+  runner?: Runner;
+  /** Re-register grace window for post-restart version checks (default 30s). */
+  verifyTimeoutMs?: number;
+  /** Poll interval while waiting for re-register (default 1s). */
+  verifyIntervalMs?: number;
+  sleep?: (ms: number) => Promise<void>;
+  probeServerVersion?: () => Promise<string | undefined>;
+  probeOrchestrators?: () => Promise<UpgradeSnapshot["runningOrchestrators"]>;
+};
+
+export async function executeUpgradePlan(plan: UpgradePlan, options: ExecuteUpgradeOptions = {}): Promise<string> {
   if (options.dryRun) return formatUpgradePlan(plan, { dryRun: true });
   const runner = options.runner ?? runCommand;
+  const sleep = options.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+  const probeServerVersion = options.probeServerVersion ?? runningServerVersion;
+  const probeOrchestrators = options.probeOrchestrators ?? runningOrchestrators;
+  const verifyTimeoutMs = options.verifyTimeoutMs ?? 30000;
+  const verifyIntervalMs = options.verifyIntervalMs ?? 1000;
+  // Restarted services drop their old registration and re-register asynchronously.
+  // Poll until the reported version reaches the target (or the grace window expires)
+  // so a slow re-register is not mistaken for a failed upgrade (vent #49).
+  const pollUntil = async <T>(probe: () => Promise<T>, done: (value: T) => boolean): Promise<T> => {
+    const deadline = Date.now() + verifyTimeoutMs;
+    let value = await probe();
+    while (!done(value) && Date.now() < deadline) {
+      await sleep(verifyIntervalMs);
+      value = await probe();
+    }
+    return value;
+  };
   const lines = [`Upgrading Agent Relay to ${plan.targetVersion}`];
   for (const action of plan.actions) {
     lines.push(`\n${action.label}`);
@@ -259,16 +290,17 @@ export async function executeUpgradePlan(plan: UpgradePlan, options: { dryRun?:
     }
   }
   if (plan.actions.some((action) => action.command.join(" ") === "systemctl --user restart agent-relay.service")) {
-    await new Promise((resolve) => setTimeout(resolve, 1000));
-    const serverVersion = await runningServerVersion();
+    const serverVersion = await pollUntil(probeServerVersion, (version) => version === plan.targetVersion);
     if (serverVersion && serverVersion !== plan.targetVersion) {
       throw new Error(`agent-relay.service restarted but /api/stats reports ${serverVersion}, expected ${plan.targetVersion}`);
     }
     if (serverVersion) lines.push(`Running server: ${serverVersion}`);
   }
   if (plan.actions.some((action) => action.command.join(" ") === "systemctl --user restart agent-relay-orchestrator.service")) {
-    await new Promise((resolve) => setTimeout(resolve, 1000));
-    const orchestrators = await runningOrchestrators() ?? [];
+    const orchestrators = await pollUntil(
+      async () => (await probeOrchestrators()) ?? [],
+      (list) => list.length > 0 && list.every((orch) => !orch.version || orch.version === plan.targetVersion),
+    );
     const mismatched = orchestrators.filter((orch) => orch.version && orch.version !== plan.targetVersion);
     if (mismatched.length > 0) {
       throw new Error(`agent-relay-orchestrator.service restarted but ${mismatched.map((orch) => `${orch.id} reports ${orch.version}`).join(", ")}, expected ${plan.targetVersion}`);
@@ -395,7 +427,7 @@ async function npmViewVersion(spec: string): Promise<string | undefined> {
 async function runningServerVersion(): Promise<string | undefined> {
   try {
     const headers: Record<string, string> = {};
-    if (process.env.AGENT_RELAY_TOKEN) headers["X-Agent-Relay-Token"] = process.env.AGENT_RELAY_TOKEN;
+    if (process.env.AGENT_RELAY_TOKEN) headers[RELAY_TOKEN_HEADER] = process.env.AGENT_RELAY_TOKEN;
     const relayUrl = (process.env.AGENT_RELAY_URL || "http://127.0.0.1:4850").replace(/\/+$/, "");
     const response = await fetch(`${relayUrl}/api/stats`, { headers });
     if (!response.ok) return undefined;
@@ -409,7 +441,7 @@ async function runningServerVersion(): Promise<string | undefined> {
 async function runningOrchestrators(): Promise<UpgradeSnapshot["runningOrchestrators"]> {
   try {
     const headers: Record<string, string> = {};
-    if (process.env.AGENT_RELAY_TOKEN) headers["X-Agent-Relay-Token"] = process.env.AGENT_RELAY_TOKEN;
+    if (process.env.AGENT_RELAY_TOKEN) headers[RELAY_TOKEN_HEADER] = process.env.AGENT_RELAY_TOKEN;
     const relayUrl = (process.env.AGENT_RELAY_URL || "http://127.0.0.1:4850").replace(/\/+$/, "");
     const response = await fetch(`${relayUrl}/api/orchestrators`, { headers });
     if (!response.ok) return [];
@@ -493,7 +525,7 @@ function runCommand(command: string[]): CommandResult {
     return {
       exitCode: 127,
       stdout: "",
-      stderr: error instanceof Error ? error.message : String(error),
+      stderr: errMessage(error),
     };
   }
 }
@@ -535,8 +567,3 @@ function formatContracts(contracts: RuntimeContracts | undefined): string {
     .map(([name, version]) => `${name}=${version}`)
     .join(" ");
 }
-
-function shellQuote(value: string): string {
-  if (/^[a-zA-Z0-9_@%+=:,./-]+$/.test(value)) return value;
-  return `'${value.replaceAll("'", "'\\''")}'`;
-}

package/src/utils.ts

@@ -0,0 +1,38 @@
+import { isAbsolute, relative, resolve } from "node:path";
+
+/**
+ * Path containment check — is `path` inside (or equal to) `baseDir`?
+ *
+ * Both inputs are `resolve()`d first for defensive clarity. (Note: `path.relative`
+ * already `resolve()`s both args against cwd internally, so this is belt-and-
+ * suspenders, not a behavior change — verified: the `security.ts` copy that
+ * omitted the explicit `resolve()` produced identical results. The audit's
+ * "bug #4" was a false alarm.) Returns `false` when either input is missing.
+ *
+ * Was hand-copied in 6 server modules (security, workspace-merge, mcp,
+ * lifecycle-manager, steward, routes) under three different names. Import this;
+ * never re-declare it.
+ */
+export function isPathWithinBase(path: string | undefined, baseDir: string | undefined): boolean {
+  if (!path || !baseDir) return false;
+  const rel = relative(resolve(baseDir), resolve(path));
+  return rel === "" || (!!rel && !rel.startsWith("..") && !isAbsolute(rel));
+}
+
+/**
+ * Parse JSON, returning `fallback` on any failure (non-string input, empty
+ * string, or malformed JSON). Never throws.
+ *
+ * Folds the four fallback-style `parseJson` copies (db, memory-sqlite-broker,
+ * provider-catalog-store, automations). The throwing / Buffer / null-returning
+ * variants (memory-*-broker operation-context, control-server, insights-db) are
+ * deliberately separate — different contracts.
+ */
+export function parseJson<T>(raw: unknown, fallback: T): T {
+  if (typeof raw !== "string" || !raw) return fallback;
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    return fallback;
+  }
+}

package/src/validation.ts

@@ -0,0 +1,80 @@
+import { ValidationError } from "./db";
+
+/**
+ * Trim + validate an optional string input. Throws `ValidationError` when the
+ * value is present but not a string, exceeds `max`, or is required-but-empty.
+ * Returns `undefined` for absent/blank non-required values.
+ *
+ * Single home — was byte-identical in config-store, automations, and routes.
+ */
+export 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;
+}
+
+/**
+ * Validate a REQUIRED enum value: throws `ValidationError` if missing or not one
+ * of `valid`. Use when the field must be present. (config-store + automations
+ * no-fallback semantics.) For optional/defaulted enums use {@link optionalEnum}.
+ */
+export function cleanEnum<T extends readonly string[]>(value: unknown, field: string, valid: T): T[number] {
+  if (typeof value !== "string" || !valid.includes(value)) {
+    throw new ValidationError(`${field} must be one of: ${valid.join(", ")}`);
+  }
+  return value as T[number];
+}
+
+/**
+ * Validate an OPTIONAL enum value. Absent (`undefined`/`null`) → returns
+ * `fallback` (which may itself be undefined). A present-but-invalid value still
+ * throws. (routes + automations with-fallback semantics.) The overloads keep the
+ * return type non-undefined when a concrete `fallback` is supplied.
+ */
+export function optionalEnum<T extends readonly string[]>(value: unknown, field: string, valid: T, fallback: T[number]): T[number];
+export function optionalEnum<T extends readonly string[]>(value: unknown, field: string, valid: T, fallback?: T[number]): T[number] | undefined;
+export function optionalEnum<T extends readonly string[]>(value: unknown, field: string, valid: T, fallback?: T[number]): T[number] | undefined {
+  if (value === undefined || value === null) return fallback;
+  if (typeof value !== "string" || !valid.includes(value)) {
+    throw new ValidationError(`${field} must be one of: ${valid.join(", ")}`);
+  }
+  return value as T[number];
+}
+
+/**
+ * Validate an array of strings: trims + dedups each item, drops blanks. Throws
+ * if a present value isn't an array, an item exceeds `itemMax`, or the count
+ * exceeds `maxItems`. Absent → `undefined` (or throws when `required`).
+ *
+ * Callers pass their own per-context limits (`itemMax`/`maxItems`). Sites that
+ * previously returned `[]` for absent input append `?? []`. Single home — folded
+ * the config-store/automations/routes copies that differed only in those limits.
+ */
+export function cleanStringArray(
+  value: unknown,
+  field: string,
+  opts: { required?: boolean; itemMax?: number; maxItems?: number } = {},
+): string[] | undefined {
+  if (value === undefined || value === null) {
+    if (opts.required) throw new ValidationError(`${field} required`);
+    return undefined;
+  }
+  if (!Array.isArray(value)) throw new ValidationError(`${field} must be an array of strings`);
+  const cleaned = value.map((item) => cleanString(item, `${field} item`, { max: opts.itemMax })).filter(Boolean) as string[];
+  if (opts.maxItems && cleaned.length > opts.maxItems) {
+    throw new ValidationError(`${field} can contain at most ${opts.maxItems} values`);
+  }
+  return [...new Set(cleaned)];
+}

package/src/workspace-claim.ts

@@ -0,0 +1,29 @@
+import type { WorkspaceRecord } from "./types";
+
+// A steward claims a workspace before validating/landing so the deterministic
+// auto-merge (Layer 0) doesn't race it (#208 / steward report §1). The claim is a
+// TTL'd lease stored in row metadata, so a dead steward can't block the workspace
+// forever — it expires and auto-merge resumes. Renew by re-claiming.
+export const STEWARD_CLAIM_TTL_MS = Number(process.env.AGENT_RELAY_WORKSPACE_CLAIM_TTL_MS) || 15 * 60_000;
+
+export interface WorkspaceClaim {
+  by?: string;
+  purpose?: string;
+  claimedAt?: number;
+  expiresAt?: number;
+}
+
+/** The active (unexpired) claim on a workspace, or null. Reads row metadata. */
+export function workspaceActiveClaim(ws: Pick<WorkspaceRecord, "metadata">, now: number = Date.now()): WorkspaceClaim | null {
+  const meta = ws.metadata as Record<string, unknown> | undefined;
+  const claim = meta && typeof meta === "object" ? (meta.stewardClaim as WorkspaceClaim | undefined) : undefined;
+  if (!claim || typeof claim !== "object") return null;
+  const expiresAt = typeof claim.expiresAt === "number" ? claim.expiresAt : 0;
+  return expiresAt > now ? claim : null;
+}
+
+/** Metadata patch that records a fresh claim (or clears one when releasing). */
+export function claimMetadataPatch(release: boolean, by?: string, purpose?: string, now: number = Date.now()): Record<string, unknown> {
+  if (release) return { stewardClaim: null };
+  return { stewardClaim: { by, purpose, claimedAt: now, expiresAt: now + STEWARD_CLAIM_TTL_MS } };
+}

package/src/workspace-merge.ts

@@ -1,21 +1,25 @@
-import { isAbsolute, relative, resolve } from "node:path";
 import { createCommand } from "./commands-db";
 import {
   acquireMergeLease,
+  getAgent,
   listOrchestrators,
   releaseMergeLease,
   setMergeLeaseCommand,
   updateWorkspaceStatus,
 } from "./db";
 import type { Command, WorkspaceMergeStrategy, WorkspaceRecord } from "./types";
+import { isPathWithinBase } from "./utils";
 
 export interface RequestWorkspaceMergeOptions {
   /** Who asked for the merge (lease holder + audit). e.g. an agent id, "dashboard", "auto-merge". */
   requestedBy: string;
   /** Merge strategy; "auto" lets the host pick pr-vs-rebase-ff. Defaults to "auto". */
   strategy?: WorkspaceMergeStrategy;
-  /** Delete the agent branch after a successful land. Defaults to true. */
+  /** Delete the agent branch after a successful land. Defaults to true, but is
+   * forced false when the workspace owner is still alive (see #204). */
   deleteBranch?: boolean;
+  /** Push the landed base to origin. Defaults to true (host skips when no upstream). */
+  push?: boolean;
   prTitle?: string;
   prBody?: string;
   /** Extra metadata merged onto the workspace row when moving to merge_planned. */
@@ -26,11 +30,12 @@ export type RequestWorkspaceMergeResult =
   | { ok: true; command: Command; workspace: WorkspaceRecord }
   | { ok: false; status: number; error: string };
 
-// Real path containment (same rule as routes/mcp): never string startsWith.
-function pathWithinBase(path: string | undefined, baseDir: string | undefined): boolean {
-  if (!path || !baseDir) return false;
-  const rel = relative(resolve(baseDir), resolve(path));
-  return rel === "" || (!!rel && !rel.startsWith("..") && !isAbsolute(rel));
+// The owner is "alive" while its relay agent exists and isn't offline (online or
+// a borderline-stale disconnect both count — don't nuke a worktree on a blip).
+function isOwnerAlive(ownerAgentId: string | undefined): boolean {
+  if (!ownerAgentId) return false;
+  const agent = getAgent(ownerAgentId);
+  return Boolean(agent) && agent!.status !== "offline";
 }
 
 /**
@@ -60,12 +65,18 @@ export function requestWorkspaceMerge(workspace: WorkspaceRecord, opts: RequestW
   try {
     // Merge needs a live host: rebasing against a stale base later is unsafe.
     const onlineOwner = listOrchestrators().find(
-      (candidate) => candidate.status === "online" && pathWithinBase(workspace.sourceCwd, candidate.baseDir),
+      (candidate) => candidate.status === "online" && isPathWithinBase(workspace.sourceCwd, candidate.baseDir),
     );
     if (!onlineOwner) {
       releaseMergeLease({ repoRoot: workspace.repoRoot, workspaceId: workspace.id });
       return { ok: false, status: 409, error: "no online orchestrator available for workspace merge" };
     }
+    // Never tear down a worktree whose owner is still alive (#204): an online/stale
+    // owner keeps its worktree + branch and continues working after the land (the
+    // host returns it to `active`). Only an offline/absent owner gets the worktree
+    // reclaimed. This overrides the caller's deleteBranch when the owner is alive.
+    const ownerAlive = isOwnerAlive(workspace.ownerAgentId);
+    const deleteBranch = ownerAlive ? false : (opts.deleteBranch !== false);
     const updated = updateWorkspaceStatus(workspace.id, "merge_planned", {
       ...(opts.metadata ?? {}),
       lastWorkspaceAction: "merge",
@@ -89,7 +100,8 @@ export function requestWorkspaceMerge(workspace: WorkspaceRecord, opts: RequestW
         baseRef: workspace.baseRef,
         baseSha: workspace.baseSha,
         strategy: opts.strategy ?? "auto",
-        deleteBranch: opts.deleteBranch !== false,
+        deleteBranch,
+        push: opts.push !== false,
         prTitle: opts.prTitle,
         prBody: opts.prBody,
         requestedBy: opts.requestedBy,