agent-relay-server 0.11.3 → 0.11.4

package/docs/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Relay API",
-    "version": "0.10.21",
+    "version": "0.11.3",
     "description": "Real-time message bus for inter-agent communication. Agent-first: this spec is designed for machine consumption — agents can self-discover the full API surface via GET /api/spec.",
     "license": {
       "name": "MIT",
@@ -2725,7 +2725,7 @@
         "tags": [
           "Orchestrators"
         ],
-        "description": "Dispatches a host action to the orchestrator over the command bus. `restart`/`shutdown` target a managed agent (omit `agentId` for all). `upgrade` triggers a remote self-upgrade: the relay stamps a desired version and the orchestrator installs it via the bundled `agent-relay upgrade --no-restart` CLI, then restarts itself decoupled (systemd-run) so the bus keepalive survives its own teardown. The upgrade command is intentionally left `running` — the relay settles it (succeeded/failed) by reconciling the version the orchestrator reports on its post-restart re-register, within a deadline. Safety rails: semver-only `targetVersion` (defaults to the relay's own version), npm-registry providers only, and no downgrade unless `force` is set. Requires systemd --user supervision on the orchestrator host.",
+        "description": "Dispatches a host action to the orchestrator over the command bus. `restart`/`shutdown` target a managed agent (omit `agentId` for all). `upgrade` triggers a remote self-upgrade: the relay stamps a desired version and the orchestrator installs the selected runtime packages, then restarts itself decoupled so the bus keepalive survives its own teardown. Runtime-prefix installs use npm directly; non-prefix installs require an available `agent-relay upgrade --no-restart` CLI. The upgrade command is intentionally left `running` — the relay settles it (succeeded/failed) by reconciling the version the orchestrator reports on its post-restart re-register, within a deadline, or immediately when the command fails. Safety rails: semver-only `targetVersion` (defaults to the relay's own version), explicit self-upgrade capability, systemd/launchd supervision, and no downgrade unless `force` is set.",
         "parameters": [
           {
             "name": "id",
@@ -6603,6 +6603,9 @@
                   },
                   "defaultTags": {
                     "type": "string"
+                  },
+                  "chatCaptureMode": {
+                    "type": "string"
                   }
                 }
               }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-server",
-  "version": "0.11.3",
+  "version": "0.11.4",
   "description": "Lightweight HTTP message relay for inter-agent communication across machines",
   "module": "src/index.ts",
   "type": "module",
@@ -32,7 +32,7 @@
     "CONTRIBUTING.md"
   ],
   "dependencies": {
-    "agent-relay-sdk": "0.2.2"
+    "agent-relay-sdk": "0.2.3"
   },
   "scripts": {
     "postinstall": "node scripts/install-bin-shim.cjs",

package/public/index.html

@@ -123527,6 +123527,32 @@ function OrphanPanel() {
 		})]
 	});
 }
+function prLabel(url) {
+	const match = url.match(/\/pull\/(\d+)/);
+	return match ? `PR #${match[1]}` : "View PR";
+}
+function MergeOutcome({ workspace }) {
+	const result = workspace.metadata?.mergeResult;
+	const prUrl = result?.prUrl;
+	const error = result?.error || workspace.metadata?.mergeError;
+	if (!prUrl && !error) return null;
+	return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(import_jsx_runtime.Fragment, { children: [prUrl && /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("a", {
+		href: prUrl,
+		target: "_blank",
+		rel: "noreferrer",
+		title: prUrl,
+		className: "inline-flex items-center gap-0.5 rounded border border-violet-500/30 px-1.5 py-0 text-[10px] text-violet-400 hover:text-violet-300",
+		children: [/* @__PURE__ */ (0, import_jsx_runtime.jsx)(GitMerge, { className: "h-2.5 w-2.5" }), prLabel(prUrl)]
+	}), error && /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(Badge$1, {
+		variant: "outline",
+		className: "max-w-[16rem] border-amber-500/30 text-amber-400 text-[10px]",
+		title: error,
+		children: [/* @__PURE__ */ (0, import_jsx_runtime.jsx)(TriangleAlert, { className: "mr-0.5 h-2.5 w-2.5 shrink-0" }), /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("span", {
+			className: "truncate",
+			children: ["merge: ", error]
+		})]
+	})] });
+}
 function WorkspaceRow({ workspace }) {
 	const now = useNow();
 	const [expanded, setExpanded] = (0, import_react.useState)(false);
@@ -123565,7 +123591,8 @@ function WorkspaceRow({ workspace }) {
 								variant: "outline",
 								className: `text-[10px] ${statusTone(workspace.status)}`,
 								children: STATUS_LABEL[workspace.status] || workspace.status
-							})
+							}),
+							/* @__PURE__ */ (0, import_jsx_runtime.jsx)(MergeOutcome, { workspace })
 						]
 					})]
 				}),
@@ -152711,6 +152738,10 @@ if ("serviceWorker" in navigator) {
     max-width: 12rem;
   }
 
+  .max-w-\[16rem\] {
+    max-width: 16rem;
+  }
+
   .max-w-\[18rem\] {
     max-width: 18rem;
   }
@@ -155661,6 +155692,10 @@ if ("serviceWorker" in navigator) {
       color: var(--color-red-400);
     }
 
+    .hover\:text-violet-300:hover {
+      color: var(--color-violet-300);
+    }
+
     .hover\:text-zinc-100:hover {
       color: var(--color-zinc-100);
     }

package/src/db.ts

@@ -4951,6 +4951,14 @@ function upsertWorkspaceFromManagedAgent(agent: ManagedAgent): WorkspaceRecord |
   const workspace = agent.workspace;
   if (!workspace) return null;
   if (workspace.mode === "isolated" && workspace.id && workspace.repoRoot && workspace.worktreePath) {
+    // A live agent re-registers its workspace on every heartbeat. That must not
+    // clobber progress the workspace has made past the live editing state
+    // (a merge that opened a PR, ready/review/conflict, terminal states) nor
+    // wipe accumulated metadata such as the merge result / PR link. Only the
+    // "active" live state is refreshable from registration; everything else is
+    // preserved and metadata is merged, not replaced.
+    const existing = getWorkspace(workspace.id);
+    const preserveStatus = existing != null && existing.status !== "active";
     return upsertWorkspace({
       id: workspace.id,
       repoRoot: workspace.repoRoot,
@@ -4961,11 +4969,11 @@ function upsertWorkspaceFromManagedAgent(agent: ManagedAgent): WorkspaceRecord |
       baseSha: workspace.baseSha,
       mode: workspace.mode,
       requestedMode: workspace.requestedMode,
-      status: workspace.status ?? "active",
+      status: preserveStatus ? existing!.status : (workspace.status ?? "active"),
       ownerAgentId: agent.agentId || undefined,
       ownerPolicyName: agent.policyName,
       ownerAutomationRunId: agent.automationRunId,
-      metadata: { provider: agent.provider, label: agent.label, sessionName: agent.sessionName, tmuxSession: agent.tmuxSession },
+      metadata: { ...(existing?.metadata ?? {}), provider: agent.provider, label: agent.label, sessionName: agent.sessionName, tmuxSession: agent.tmuxSession },
     });
   }
   // Shared-mode occupancy: one row per agent sharing a git repo, with no

package/src/dev.ts

@@ -154,7 +154,7 @@ export async function executeDevInstallPlan(plan: DevInstallPlan, options: { dry
   const packed = await executeDevPackPlan(plan.packPlan);
   await mkdir(plan.prefix, { recursive: true });
   ensureDevPrefixPackageJson(plan.prefix);
-  const command = ["install", "--prefix", plan.prefix, "--no-audit", "--no-fund", ...packed.tarballs];
+  const command = ["install", "--prefix", plan.prefix, "--no-audit", "--no-fund", "--force", ...packed.tarballs];
   const result = await execFileAsync("npm", command);
   const output = [
     packed.output,
@@ -353,7 +353,7 @@ export function formatDevInstallPlan(plan: DevInstallPlan): string {
     formatDevPackPlan(plan.packPlan),
     "",
     "Install command:",
-    `  npm install --prefix ${plan.prefix} --no-audit --no-fund <packed tarballs...>`,
+    `  npm install --prefix ${plan.prefix} --no-audit --no-fund --force <packed tarballs...>`,
   ].join("\n");
 }
 

package/src/lifecycle-manager.ts

@@ -1,5 +1,4 @@
 import { isAbsolute, relative, resolve } from "node:path";
-import { resolveProviderSelection } from "agent-relay-sdk/provider-catalog";
 import { createCommand } from "./commands-db";
 import { createActivityEvent, deleteWorkspace, getAgent, getDb, getOrchestrator, listOrchestrators, listWorkspaces, resolveQueuedPolicyMessages } from "./db";
 import {
@@ -9,8 +8,8 @@ import {
   upsertManagedAgentState,
 } from "./config-store";
 import { emitRelayEvent } from "./events";
-import { runnerRuntimeTokenEnv } from "./runtime-tokens";
-import type { Command, ManagedAgent, ManagedAgentState, ManagedSessionExitDiagnostics, SpawnPolicy, WorkspaceMode } from "./types";
+import { buildManagedSpawnParams } from "./managed-policy";
+import type { Command, ManagedAgent, ManagedAgentState, ManagedSessionExitDiagnostics, SpawnPolicy } from "./types";
 
 const DEFAULT_TICK_MS = 10_000;
 // A spawn that never reaches "running" (runner crashed, never registered, host
@@ -227,34 +226,8 @@ export class LifecycleManager {
       target: orch.agentId,
       correlationId: spawnRequestId,
       params: {
-        action: "spawn",
-        provider: policy.provider,
-        cwd: policy.cwd,
-        workspaceMode: effectivePolicyWorkspaceMode(policy),
-        ...(policy.rig ? { rig: policy.rig } : {}),
-        ...resolvedModelParams(policy),
-        label: policy.label,
-        tags: policy.tags,
-        capabilities: policy.capabilities,
-        approvalMode: policy.permissionMode,
-        permissionMode: policy.permissionMode,
-        providerArgs: policy.providerArgs,
-        prompt: policy.prompt,
-        headless: true,
-        policyName: policy.name,
-        spawnRequestId,
-        env: runnerRuntimeTokenEnv({
-          orchestratorId: policy.orchestratorId,
-          cwd: policy.cwd,
-          provider: policy.provider,
-          label: policy.label,
-          policyName: policy.name,
-          spawnRequestId,
-          createdBy: "lifecycle-manager",
-        }),
+        ...buildManagedSpawnParams(policy, spawnRequestId, { createdBy: "lifecycle-manager", requestedAt: this.now() }),
         reason,
-        requestedBy: "lifecycle-manager",
-        requestedAt: this.now(),
       },
     });
     this.emitCommand(command);
@@ -302,7 +275,11 @@ export class LifecycleManager {
   }
 
   restartAgent(policy: SpawnPolicy, reason = "reconcile-restart"): Command | null {
+    const orch = getOrchestrator(policy.orchestratorId);
+    if (!orch) return null;
     const state = getManagedAgentState(policy.name);
+    const restartRequestId = `sp_${crypto.randomUUID()}`;
+    const restartSpawn = buildManagedSpawnParams(policy, restartRequestId, { createdBy: "lifecycle-manager", requestedAt: this.now() });
     const restarted = upsertManagedAgentState({
       policyName: policy.name,
       status: "stopping",
@@ -310,14 +287,35 @@ export class LifecycleManager {
       orchestratorId: policy.orchestratorId,
       provider: policy.provider,
       tmuxSession: state?.tmuxSession,
-      spawnRequestId: state?.spawnRequestId,
-      lastSpawnAt: state?.lastSpawnAt,
+      spawnRequestId: restartRequestId,
+      lastSpawnAt: this.now(),
       lastStopAt: this.now(),
       restartCount: (state?.restartCount ?? 0) + 1,
       consecutiveFailures: state?.consecutiveFailures ?? 0,
     });
     this.emitState(restarted, `restart: ${reason}`);
-    return this.stopAgent(policy, true, reason);
+    const command = createCommand({
+      type: "agent.restart",
+      source: "system",
+      target: orch.agentId,
+      correlationId: state?.spawnRequestId,
+      params: {
+        action: "restart",
+        policyName: policy.name,
+        spawnRequestId: state?.spawnRequestId,
+        agentId: state?.agentId,
+        tmuxSession: state?.tmuxSession,
+        graceful: true,
+        timeoutMs: 10_000,
+        reason,
+        orchestratorId: orch.id,
+        restartSpawn,
+        requestedBy: "lifecycle-manager",
+        requestedAt: this.now(),
+      },
+    });
+    this.emitCommand(command);
+    return command;
   }
 
   private reconcilePolicy(policy: SpawnPolicy): void {
@@ -641,24 +639,3 @@ function alwaysReloadTags(tags: string[]): string[] {
     .filter(Boolean);
 }
 
-function effectivePolicyWorkspaceMode(policy: SpawnPolicy): WorkspaceMode {
-  if (policy.workspaceMode && policy.workspaceMode !== "inherit") return policy.workspaceMode;
-  return policy.binding?.type === "channel" ? "shared" : "inherit";
-}
-
-function resolvedModelParams(policy: SpawnPolicy): Record<string, string> {
-  if (!policy.model && !policy.effort) return {};
-  try {
-    const selection = resolveProviderSelection({ provider: policy.provider, model: policy.model, effort: policy.effort });
-    return {
-      ...(selection.modelAlias ? { model: selection.modelAlias } : {}),
-      ...(selection.providerModel ? { providerModel: selection.providerModel } : {}),
-      ...(selection.effort ? { effort: selection.effort } : {}),
-    };
-  } catch {
-    return {
-      ...(policy.model ? { model: policy.model } : {}),
-      ...(policy.effort ? { effort: policy.effort } : {}),
-    };
-  }
-}

package/src/managed-policy.ts

@@ -0,0 +1,80 @@
+import { resolveProviderSelection } from "agent-relay-sdk/provider-catalog";
+import { getAgentProfile } from "./config-store";
+import { runnerRuntimeTokenEnv } from "./runtime-tokens";
+import type { SpawnPolicy, WorkspaceMode } from "./types";
+
+export function managedPolicyProviderArgs(policy: SpawnPolicy): string[] {
+  if (policy.provider === "claude" && policy.mode === "always-on" && policy.prompt?.trim()) {
+    return [...policy.providerArgs, "--append-system-prompt", policy.prompt.trim()];
+  }
+  return policy.providerArgs;
+}
+
+export function managedPolicyLaunchPrompt(policy: SpawnPolicy): string | undefined {
+  if (policy.provider === "claude" && policy.mode === "always-on") return undefined;
+  return policy.prompt;
+}
+
+export function effectiveManagedPolicyWorkspaceMode(policy: SpawnPolicy): WorkspaceMode {
+  if (policy.workspaceMode && policy.workspaceMode !== "inherit") return policy.workspaceMode;
+  return policy.binding?.type === "channel" ? "shared" : "inherit";
+}
+
+function resolvedModelParams(policy: SpawnPolicy): Record<string, string> {
+  if (!policy.model && !policy.effort) return {};
+  try {
+    const selection = resolveProviderSelection({ provider: policy.provider, model: policy.model, effort: policy.effort });
+    return {
+      ...(selection.modelAlias ? { model: selection.modelAlias } : {}),
+      ...(selection.providerModel ? { providerModel: selection.providerModel } : {}),
+      ...(selection.effort ? { effort: selection.effort } : {}),
+    };
+  } catch {
+    return {
+      ...(policy.model ? { model: policy.model } : {}),
+      ...(policy.effort ? { effort: policy.effort } : {}),
+    };
+  }
+}
+
+export interface ManagedSpawnContext {
+  createdBy: string;
+  requestedAt?: number;
+}
+
+export function buildManagedSpawnParams(policy: SpawnPolicy, requestId: string, ctx: ManagedSpawnContext): Record<string, unknown> {
+  const providerArgs = managedPolicyProviderArgs(policy);
+  const prompt = managedPolicyLaunchPrompt(policy);
+  const agentProfile = policy.profile ? getAgentProfile(policy.profile)?.value : undefined;
+  return {
+    action: "spawn",
+    provider: policy.provider,
+    cwd: policy.cwd,
+    workspaceMode: effectiveManagedPolicyWorkspaceMode(policy),
+    ...(policy.rig ? { rig: policy.rig } : {}),
+    ...resolvedModelParams(policy),
+    ...(policy.profile ? { profile: policy.profile } : {}),
+    ...(agentProfile ? { agentProfile } : {}),
+    label: policy.label,
+    tags: policy.tags,
+    capabilities: policy.capabilities,
+    approvalMode: policy.permissionMode,
+    permissionMode: policy.permissionMode,
+    providerArgs,
+    ...(prompt ? { prompt } : {}),
+    headless: true,
+    policyName: policy.name,
+    spawnRequestId: requestId,
+    env: runnerRuntimeTokenEnv({
+      orchestratorId: policy.orchestratorId,
+      cwd: policy.cwd,
+      provider: policy.provider,
+      label: policy.label,
+      policyName: policy.name,
+      spawnRequestId: requestId,
+      createdBy: ctx.createdBy,
+    }),
+    requestedBy: ctx.createdBy,
+    requestedAt: ctx.requestedAt ?? Date.now(),
+  };
+}

package/src/mcp.ts

@@ -520,8 +520,8 @@ function relayAgentStatus(args: Record<string, unknown>): Record<string, unknown
 
 function relaySpawnAgent(auth: McpAuthContext, args: Record<string, unknown>): Record<string, unknown> {
   const provider = enumField(args.provider, "provider", VALID_SPAWN_PROVIDERS) as SpawnProvider;
-  const orchestrator = selectSpawnOrchestrator(provider, optionalString(args.orchestratorId, "orchestratorId", 200));
   const cwd = optionalString(args.cwd, "cwd", 500);
+  const orchestrator = selectSpawnOrchestrator(provider, optionalString(args.orchestratorId, "orchestratorId", 200), cwd);
   const resolvedCwd = cwd || orchestrator.baseDir;
   if (cwd && !pathWithinBase(cwd, orchestrator.baseDir)) {
     throw new ValidationError(`cwd must be within orchestrator base directory: ${orchestrator.baseDir}`);
@@ -704,13 +704,21 @@ function policyStatusPayload(policy: NonNullable<ReturnType<typeof getSpawnPolic
   };
 }
 
-function selectSpawnOrchestrator(provider: SpawnProvider, orchestratorId?: string): NonNullable<ReturnType<typeof getOrchestrator>> {
-  const orchestrator = orchestratorId
-    ? getOrchestrator(orchestratorId)
-    : listOrchestrators().find((item) => item.status === "online" && item.providers.includes(provider));
-  if (!orchestrator) throw new McpNotFoundError(orchestratorId ? `orchestrator ${orchestratorId} not found` : `no orchestrator available for provider: ${provider}`);
-  if (orchestrator.status !== "online") throw new ValidationError("orchestrator is offline");
-  if (!orchestrator.providers.includes(provider)) throw new ValidationError(`orchestrator does not have provider available: ${provider}`);
+function selectSpawnOrchestrator(provider: SpawnProvider, orchestratorId?: string, cwd?: string): NonNullable<ReturnType<typeof getOrchestrator>> {
+  if (orchestratorId) {
+    const orchestrator = getOrchestrator(orchestratorId);
+    if (!orchestrator) throw new McpNotFoundError(`orchestrator ${orchestratorId} not found`);
+    if (orchestrator.status !== "online") throw new ValidationError("orchestrator is offline");
+    if (!orchestrator.providers.includes(provider)) throw new ValidationError(`orchestrator does not have provider available: ${provider}`);
+    return orchestrator;
+  }
+  const candidates = listOrchestrators().filter((item) => item.status === "online" && item.providers.includes(provider));
+  if (cwd) {
+    const match = candidates.find((item) => pathWithinBase(cwd, item.baseDir));
+    if (match) return match;
+  }
+  const orchestrator = candidates[0];
+  if (!orchestrator) throw new McpNotFoundError(`no orchestrator available for provider: ${provider}`);
   return orchestrator;
 }
 

package/src/routes.ts

@@ -143,6 +143,7 @@ import { defaultProviderConfig, loadProviderConfig, providerConfigPublic, writeP
 import type { ProviderConfig } from "../runner/src/adapter";
 import { resolveProviderSelection, type ProviderEffort } from "agent-relay-sdk/provider-catalog";
 import { effectiveProviderCatalogList } from "./provider-catalog-store";
+import { buildManagedSpawnParams, effectiveManagedPolicyWorkspaceMode } from "./managed-policy";
 import {
   getComponentAuth,
   getIntegrationAuth,
@@ -2232,16 +2233,35 @@ function restartSpawnParamsForAgent(
   const label = metaString(agent.meta, "label") ?? agent.label;
   const approvalMode = metaString(agent.meta, "approvalMode") as SpawnApprovalMode | undefined;
   const model = metaString(agent.meta, "model");
-  const effort = metaString(agent.meta, "effort");
-  const providerModel = metaString(agent.meta, "providerModel");
+  const effort = metaString(agent.meta, "effort") as ProviderEffort | undefined;
   const providerArgs = metaStringArray(agent.meta, "providerArgs");
+  const profileName = metaString(agent.meta, "profile");
+  const agentProfile = profileName ? getAgentProfile(profileName)?.value : undefined;
+  const workspaceMode = metaString(agent.meta, "workspaceMode") ?? "inherit";
+  let resolvedModel: Record<string, string> = {};
+  if (model || effort) {
+    try {
+      const selection = resolveProviderSelection({ provider, model, effort });
+      resolvedModel = {
+        ...(selection.modelAlias ? { model: selection.modelAlias } : {}),
+        ...(selection.providerModel ? { providerModel: selection.providerModel } : {}),
+        ...(selection.effort ? { effort: selection.effort } : {}),
+      };
+    } catch {
+      resolvedModel = {
+        ...(model ? { model } : {}),
+        ...(effort ? { effort } : {}),
+      };
+    }
+  }
   return {
     action: "spawn",
     provider,
-    ...(model ? { model } : {}),
-    ...(providerModel ? { providerModel } : {}),
-    ...(effort ? { effort } : {}),
+    ...resolvedModel,
     cwd,
+    workspaceMode,
+    ...(profileName ? { profile: profileName } : {}),
+    ...(agentProfile ? { agentProfile } : {}),
     ...(label ? { label } : {}),
     agentId: agent.id,
     tags: agent.tags,
@@ -2250,6 +2270,7 @@ function restartSpawnParamsForAgent(
     permissionMode: approvalMode ?? "guarded",
     ...(providerArgs.length ? { providerArgs } : {}),
     ...(policyName ? { policyName } : {}),
+    headless: true,
     spawnRequestId: requestId,
     env: runnerRuntimeTokenEnv({
       orchestratorId: orchestrator.id,
@@ -2269,6 +2290,15 @@ function spawnRequestIdForRestart(): string {
   return `sp_${crypto.randomUUID()}`;
 }
 
+function compactMemoryParams(agent: AgentCard): Record<string, unknown> {
+  const alwaysReload = agent.tags
+    .filter((tag) => tag.startsWith("memory-reload:"))
+    .map((tag) => tag.slice("memory-reload:".length).trim())
+    .filter(Boolean);
+  if (!alwaysReload.length) return {};
+  return { memory: { alwaysReload } };
+}
+
 const postAgentAction: Handler = async (req, params) => {
   const parsed = await parseBody<unknown>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);
@@ -2304,6 +2334,7 @@ const postAgentAction: Handler = async (req, params) => {
         ...(metaPolicyName ? { policyName: metaPolicyName } : {}),
         ...(metaSpawnRequestId ? { spawnRequestId: metaSpawnRequestId } : {}),
         ...(action === "restart" ? { restartSpawn: restartSpawnParamsForAgent(agent, orchestrator, metaPolicyName, metaSpawnRequestId) } : {}),
+        ...(action === "compact" ? compactMemoryParams(agent) : {}),
         requestedBy: "dashboard",
         requestedAt: Date.now(),
       },
@@ -3509,6 +3540,21 @@ function compareSemverCore(a: string, b: string): number {
   return 0;
 }
 
+function orchestratorSelfUpgradeError(orch: ReturnType<typeof getOrchestrator>): string | undefined {
+  if (!orch) return "orchestrator not found";
+  if (orch.status !== "online") return "orchestrator is offline";
+  if (!orch.capabilities?.relayCommandBus) {
+    return `orchestrator ${orch.id} does not support relay command bus upgrades; upgrade it manually first`;
+  }
+  if (!orch.capabilities?.selfUpgrade) {
+    return `orchestrator ${orch.id}${orch.version ? ` v${orch.version}` : ""} does not advertise self-upgrade support; upgrade it manually once to ${VERSION} or newer`;
+  }
+  if ((orch.supervisor !== "systemd" && orch.supervisor !== "launchd") || !orch.selfUnit) {
+    return `orchestrator ${orch.id} cannot self-upgrade under supervisor ${orch.supervisor ?? "unknown"}; upgrade it manually`;
+  }
+  return undefined;
+}
+
 /**
  * Settle an in-flight orchestrator upgrade by comparing the version the
  * orchestrator now reports against the desired version (decision 2a). Called on
@@ -3517,11 +3563,18 @@ function compareSemverCore(a: string, b: string): number {
 function reconcileOrchestratorUpgrade(orch: ReturnType<typeof getOrchestrator>): void {
   if (!orch) return;
   const up = orch.upgrade;
-  if (!up || up.status !== "pending") return;
+  if (!up) return;
   const reported = orch.version;
-  if (reported && reported === up.desiredVersion) {
+  if (reported && reported === up.desiredVersion && up.status === "succeeded" && up.error) {
+    const { error: _previousError, ...successState } = up;
+    setOrchestratorUpgradeState(orch.id, successState);
+    emitOrchestratorStatus(orch.id);
+    return;
+  }
+  if (reported && reported === up.desiredVersion && (up.status === "pending" || up.status === "failed")) {
     if (up.commandId) updateCommand(up.commandId, { status: "succeeded", result: { version: reported, ...(up.fromVersion ? { fromVersion: up.fromVersion } : {}) } });
-    setOrchestratorUpgradeState(orch.id, { ...up, status: "succeeded", settledAt: Date.now() });
+    const { error: _previousError, ...successState } = up;
+    setOrchestratorUpgradeState(orch.id, { ...successState, status: "succeeded", settledAt: Date.now() });
     auditEvent({
       clientId: `server-orchestrator-upgraded-${orch.id}-${Date.now()}`,
       kind: "state",
@@ -3533,7 +3586,7 @@ function reconcileOrchestratorUpgrade(orch: ReturnType<typeof getOrchestrator>):
       metadata: { orchestratorId: orch.id, version: reported, commandId: up.commandId },
     });
     emitOrchestratorStatus(orch.id);
-  } else if (Date.now() - up.requestedAt > ORCH_UPGRADE_DEADLINE_MS) {
+  } else if (up.status === "pending" && Date.now() - up.requestedAt > ORCH_UPGRADE_DEADLINE_MS) {
     const errMsg = `upgrade timed out; orchestrator still reports ${reported ?? "unknown"} (wanted ${up.desiredVersion})`;
     if (up.commandId) updateCommand(up.commandId, { status: "failed", error: errMsg });
     setOrchestratorUpgradeState(orch.id, { ...up, status: "failed", settledAt: Date.now(), error: errMsg });
@@ -3551,6 +3604,28 @@ function reconcileOrchestratorUpgrade(orch: ReturnType<typeof getOrchestrator>):
   }
 }
 
+function settleFailedOrchestratorUpgrade(command: Command): void {
+  if (command.type !== "orchestrator.upgrade" || command.status !== "failed") return;
+  const orchestratorId = typeof command.params?.orchestratorId === "string" ? command.params.orchestratorId : undefined;
+  if (!orchestratorId) return;
+  const orch = getOrchestrator(orchestratorId);
+  const up = orch?.upgrade;
+  if (!orch || !up || up.status !== "pending" || up.commandId !== command.id) return;
+  const errMsg = command.error ?? "orchestrator upgrade failed";
+  setOrchestratorUpgradeState(orch.id, { ...up, status: "failed", settledAt: Date.now(), error: errMsg });
+  auditEvent({
+    clientId: `server-orchestrator-upgrade-command-failed-${orch.id}-${command.id}`,
+    kind: "state",
+    title: "Orchestrator upgrade failed",
+    body: errMsg,
+    meta: orch.id,
+    icon: "ti-alert-triangle",
+    view: "orchestrators",
+    metadata: { orchestratorId: orch.id, commandId: command.id },
+  });
+  emitOrchestratorStatus(orch.id);
+}
+
 const postOrchestratorAction: Handler = async (req, params) => {
   const parsed = await parseBody<unknown>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);
@@ -3571,6 +3646,8 @@ const postOrchestratorAction: Handler = async (req, params) => {
       const providers = (cleanStringArray(parsed.body.providers, "providers") ?? ["orchestrator"])
         .filter((p) => (VALID_ORCH_UPGRADE_PROVIDERS as readonly string[]).includes(p));
       if (!providers.length) return error(`providers must be any of: ${VALID_ORCH_UPGRADE_PROVIDERS.join(", ")}`);
+      const selfUpgradeError = orchestratorSelfUpgradeError(orch);
+      if (selfUpgradeError) return error(selfUpgradeError, 409);
       if (!force && orch.version && compareSemverCore(targetVersion, orch.version) < 0) {
         return error(`refusing downgrade ${orch.version} → ${targetVersion}; pass force to override`, 409);
       }
@@ -4284,6 +4361,7 @@ const patchCommand: Handler = async (req, params) => {
         }
       }
     }
+    settleFailedOrchestratorUpgrade(command);
     emitCommand(command);
     auditCommandOutcome(command);
     return json(command);
@@ -4429,60 +4507,9 @@ function policyStatusPayload(policy: SpawnPolicy) {
 }
 
 function managedSpawnParams(policy: SpawnPolicy, requestId: string): Record<string, unknown> {
-  const selection = resolveProviderSelection({ provider: policy.provider, model: policy.model, effort: policy.effort });
-  const providerArgs = managedPolicyProviderArgs(policy);
-  const prompt = managedPolicyLaunchPrompt(policy);
-  const agentProfile = policy.profile ? getAgentProfile(policy.profile)?.value : undefined;
-  return {
-    action: "spawn",
-    provider: policy.provider,
-    model: selection.modelAlias,
-    providerModel: selection.providerModel,
-    effort: selection.effort,
-    profile: policy.profile,
-    agentProfile,
-    cwd: policy.cwd,
-    workspaceMode: effectiveManagedPolicyWorkspaceMode(policy),
-    label: policy.label,
-    tags: policy.tags,
-    capabilities: policy.capabilities,
-    approvalMode: policy.permissionMode,
-    permissionMode: policy.permissionMode,
-    providerArgs,
-    ...(prompt ? { prompt } : {}),
-    headless: true,
-    policyName: policy.name,
-    spawnRequestId: requestId,
-    env: runnerRuntimeTokenEnv({
-      orchestratorId: policy.orchestratorId,
-      cwd: policy.cwd,
-      provider: policy.provider,
-      label: policy.label,
-      policyName: policy.name,
-      spawnRequestId: requestId,
-      createdBy: "managed-agent",
-    }),
-    requestedBy: "managed-agent",
-    requestedAt: Date.now(),
-  };
+  return buildManagedSpawnParams(policy, requestId, { createdBy: "managed-agent" });
 }
 
-function effectiveManagedPolicyWorkspaceMode(policy: SpawnPolicy): WorkspaceMode {
-  if (policy.workspaceMode && policy.workspaceMode !== "inherit") return policy.workspaceMode;
-  return policy.binding?.type === "channel" ? "shared" : "inherit";
-}
-
-function managedPolicyProviderArgs(policy: SpawnPolicy): string[] {
-  if (policy.provider === "claude" && policy.mode === "always-on" && policy.prompt?.trim()) {
-    return [...policy.providerArgs, "--append-system-prompt", policy.prompt.trim()];
-  }
-  return policy.providerArgs;
-}
-
-function managedPolicyLaunchPrompt(policy: SpawnPolicy): string | undefined {
-  if (policy.provider === "claude" && policy.mode === "always-on") return undefined;
-  return policy.prompt;
-}
 
 function requirePolicyAndOrchestrator(name: string): { policy: SpawnPolicy; orch: NonNullable<ReturnType<typeof getOrchestrator>> } | Response {
   const entry = getSpawnPolicy(name);