agent-relay-server 0.11.3 → 0.11.5

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.5",
   "description": "Lightweight HTTP message relay for inter-agent communication across machines",
   "module": "src/index.ts",
   "type": "module",
@@ -32,9 +32,10 @@
     "CONTRIBUTING.md"
   ],
   "dependencies": {
-    "agent-relay-sdk": "0.2.2"
+    "agent-relay-sdk": "0.2.4"
   },
   "scripts": {
+    "prepack": "cd dashboard && npx vite build >&2",
     "postinstall": "node scripts/install-bin-shim.cjs",
     "start": "bun run src/index.ts",
     "dev": "bun --watch run src/index.ts",

package/public/index.html

@@ -123101,7 +123101,9 @@ function WorkspaceActions({ workspace, expanded, onToggleDetails }) {
 	const terminal = workspace.status === "cleaned" || workspace.status === "merged" || workspace.status === "abandoned";
 	const disabled = terminal || workspace.status === "cleanup_requested";
 	const openPath = workspace.worktreePath || workspace.sourceCwd || workspace.repoRoot;
-	const mergeable = workspace.mode === "isolated" && Boolean(workspace.worktreePath) && MERGEABLE_STATUSES.has(workspace.status);
+	const gitState = useRelayStore((s) => s.workspaceGitState[workspace.id]);
+	const landed = !!gitState && gitState.available !== false && gitState.landed === true;
+	const mergeable = workspace.mode === "isolated" && Boolean(workspace.worktreePath) && MERGEABLE_STATUSES.has(workspace.status) && !landed;
 	async function copyPath() {
 		await navigator.clipboard?.writeText(openPath);
 	}
@@ -123162,7 +123164,7 @@ function WorkspaceActions({ workspace, expanded, onToggleDetails }) {
 			/* @__PURE__ */ (0, import_jsx_runtime.jsx)(Button, {
 				size: "icon-sm",
 				variant: "default",
-				title: "Merge & land work",
+				title: landed ? "Already merged into base — nothing to land" : "Merge & land work",
 				disabled: !mergeable,
 				onClick: () => void merge(),
 				children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(GitMerge, { className: "h-3.5 w-3.5" })
@@ -123185,10 +123187,10 @@ function WorkspaceActions({ workspace, expanded, onToggleDetails }) {
 		]
 	});
 }
-function MergePreviewHint({ workspace, ahead }) {
+function MergePreviewHint({ workspace, unmerged }) {
 	const preview = useRelayStore((s) => s.workspaceMergePreview[workspace.id]);
 	const fetchWorkspaceMergePreview = useRelayStore((s) => s.fetchWorkspaceMergePreview);
-	const eligible = ahead > 0 && MERGEABLE_STATUSES.has(workspace.status);
+	const eligible = unmerged > 0 && MERGEABLE_STATUSES.has(workspace.status);
 	(0, import_react.useEffect)(() => {
 		if (eligible && preview === void 0) fetchWorkspaceMergePreview(workspace.id);
 	}, [
@@ -123251,9 +123253,11 @@ function GitState({ workspace }) {
 		children: [/* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { children: "git error" }), refresh]
 	});
 	const ahead = gitState.ahead ?? 0;
+	const landed = gitState.landed === true;
+	const unmerged = landed ? 0 : gitState.unmergedAhead ?? ahead;
 	const behind = gitState.behind ?? 0;
 	const dirty = gitState.dirtyCount ?? 0;
-	const clean = ahead === 0 && dirty === 0;
+	const clean = unmerged === 0 && dirty === 0 && !landed;
 	const commit = gitState.lastCommit;
 	return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", {
 		className: "space-y-0.5",
@@ -123263,10 +123267,14 @@ function GitState({ workspace }) {
 				className: "text-muted-foreground",
 				children: "no unmerged work"
 			}) : /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(import_jsx_runtime.Fragment, { children: [
-				/* @__PURE__ */ (0, import_jsx_runtime.jsxs)("span", {
-					className: ahead > 0 ? "flex items-center text-emerald-400" : "flex items-center text-muted-foreground",
-					title: `${ahead} commit(s) ahead of base`,
-					children: [/* @__PURE__ */ (0, import_jsx_runtime.jsx)(ArrowUp, { className: "h-3 w-3" }), ahead]
+				landed ? /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("span", {
+					className: "flex items-center gap-0.5 text-emerald-400",
+					title: `Work already landed in ${gitState.baseRef || "base"} via squash/cherry-pick — safe to clean up`,
+					children: [/* @__PURE__ */ (0, import_jsx_runtime.jsx)(Check, { className: "h-3 w-3" }), "landed"]
+				}) : /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("span", {
+					className: unmerged > 0 ? "flex items-center text-emerald-400" : "flex items-center text-muted-foreground",
+					title: ahead !== unmerged ? `${unmerged} unmerged commit(s) (${ahead} ahead of base)` : `${unmerged} commit(s) ahead of base`,
+					children: [/* @__PURE__ */ (0, import_jsx_runtime.jsx)(ArrowUp, { className: "h-3 w-3" }), unmerged]
 				}),
 				/* @__PURE__ */ (0, import_jsx_runtime.jsxs)("span", {
 					className: behind > 0 ? "flex items-center text-amber-400" : "flex items-center text-muted-foreground",
@@ -123278,9 +123286,9 @@ function GitState({ workspace }) {
 					title: `${dirty} uncommitted change(s)`,
 					children: [/* @__PURE__ */ (0, import_jsx_runtime.jsx)(FilePen, { className: "h-3 w-3" }), dirty]
 				}),
-				/* @__PURE__ */ (0, import_jsx_runtime.jsx)(MergePreviewHint, {
+				!landed && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(MergePreviewHint, {
 					workspace,
-					ahead
+					unmerged
 				})
 			] }), refresh]
 		}), commit && /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", {
@@ -123527,6 +123535,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 +123599,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 +152746,10 @@ if ("serviceWorker" in navigator) {
     max-width: 12rem;
   }
 
+  .max-w-\[16rem\] {
+    max-width: 16rem;
+  }
+
   .max-w-\[18rem\] {
     max-width: 18rem;
   }
@@ -155661,6 +155700,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
@@ -5057,6 +5065,28 @@ export function deleteWorkspace(id: string): boolean {
   return db.prepare("DELETE FROM workspaces WHERE id = ?").run(id).changes > 0;
 }
 
+// Shared-mode rows are pure occupancy markers (no worktree on disk) that only
+// mean something while their owner is online. Deletion is normally driven by
+// the reaper's onAgentDisappeared hook, but agents also leave via clean
+// SessionEnd (setStatus offline) and via pruneOfflineAgents (raw agent delete),
+// neither of which touches workspaces — so orphaned shared rows accumulate and
+// bloat the workspace panel. This sweep is the catch-all: drop any non-cleaned
+// shared row whose owner is missing or offline, regardless of how it leaked.
+export function pruneOrphanedSharedWorkspaces(): string[] {
+  return db.transaction(() => {
+    const orphanCondition = `
+      mode = 'shared' AND status != 'cleaned' AND (
+        owner_agent_id IS NULL
+        OR owner_agent_id NOT IN (SELECT id FROM agents)
+        OR owner_agent_id IN (SELECT id FROM agents WHERE status = 'offline')
+      )`;
+    const rows = db.prepare(`SELECT id FROM workspaces WHERE ${orphanCondition}`).all() as Array<{ id: string }>;
+    if (!rows.length) return [];
+    db.prepare(`DELETE FROM workspaces WHERE ${orphanCondition}`).run();
+    return rows.map((r) => r.id);
+  })();
+}
+
 export function updateWorkspaceStatus(id: string, status: WorkspaceStatus, metadata: Record<string, unknown> = {}): WorkspaceRecord | null {
   const existing = getWorkspace(id);
   if (!existing) return null;

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/maintenance.ts

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import { getArtifactStorage } from "./artifact-storage";
 import { expireStaleBusAgents } from "./bus";
 import { pruneOutbox } from "./bus-outbox";
-import { expireCommands } from "./commands-db";
+import { createCommand, expireCommands } from "./commands-db";
 import { DAY_MS, OFFLINE_PRUNE_MS, REAP_INTERVAL_MS, STALE_TTL_MS } from "./config";
 import { isAbsolute, relative, resolve } from "node:path";
 import {
@@ -14,6 +14,8 @@ import {
   listWorkspaces,
   pruneOfflineAgents,
   pruneOldMessages,
+  deleteWorkspace,
+  pruneOrphanedSharedWorkspaces,
   reapStaleAgents,
   reapStaleOrchestrators,
   releaseExpiredClaims,
@@ -44,9 +46,13 @@ const SCHEDULER_TICK_MS = 10_000;
 const OUTBOX_RETENTION_MS = Number(process.env.AGENT_RELAY_OUTBOX_RETENTION_MS) || 60 * 60 * 1000;
 const TOKEN_RECORD_RETENTION_SECONDS = Number(process.env.AGENT_RELAY_TOKEN_RECORD_RETENTION_SECONDS) || 7 * 24 * 60 * 60;
 const CONFLICT_SCAN_INTERVAL_MS = Number(process.env.AGENT_RELAY_CONFLICT_SCAN_INTERVAL_MS) || 2 * 60 * 1000;
+const WORKSPACE_RETENTION_MS = Number(process.env.AGENT_RELAY_WORKSPACE_RETENTION_MS) || DAY_MS;
+const WORKSPACE_REVIEW_TTL_MS = Number(process.env.AGENT_RELAY_WORKSPACE_REVIEW_TTL_MS) || 3 * DAY_MS;
+const WORKSPACE_GC_INTERVAL_MS = Number(process.env.AGENT_RELAY_WORKSPACE_GC_INTERVAL_MS) || 60 * 60 * 1000;
 // Live statuses worth scanning. Terminal (cleaned/merged/abandoned) and
 // in-flight (cleanup_requested) states are skipped.
 const CONFLICT_SCAN_STATUSES = new Set<WorkspaceStatus>(["active", "ready", "review_requested", "merge_planned", "conflict"]);
+const TERMINAL_WORKSPACE_STATUSES = new Set<WorkspaceStatus>(["cleaned", "merged", "abandoned"]);
 
 interface MaintenanceJobDefinition {
   id: string;
@@ -279,6 +285,17 @@ const definitions: MaintenanceJobDefinition[] = [
       return { prunedTokenJtis };
     },
   },
+  {
+    id: "workspace-orphan-sweep",
+    title: "Workspace orphan sweep",
+    description: "Delete shared-mode workspace occupancy rows whose owner agent is offline or gone.",
+    intervalMs: REAP_INTERVAL_MS,
+    runOnStart: true,
+    handler() {
+      const prunedSharedWorkspaceIds = pruneOrphanedSharedWorkspaces();
+      return { prunedSharedWorkspaceIds };
+    },
+  },
   {
     id: "workspace-conflict-scan",
     title: "Workspace conflict scan",
@@ -288,6 +305,15 @@ const definitions: MaintenanceJobDefinition[] = [
     timeoutMs: 60 * 1000,
     handler: scanWorkspaceConflicts,
   },
+  {
+    id: "workspace-gc",
+    title: "Workspace GC",
+    description: "Prune terminal workspace rows past retention, auto-abandon stale review_requested worktrees, and trigger git worktree prune on orchestrators.",
+    intervalMs: WORKSPACE_GC_INTERVAL_MS,
+    runOnStart: false,
+    timeoutMs: 60 * 1000,
+    handler: workspaceGC,
+  },
 ];
 
 function workspacePathWithinBase(path: string | undefined, baseDir: string | undefined): boolean {
@@ -387,6 +413,79 @@ async function scanWorkspaceConflicts(): Promise<Record<string, unknown>> {
   return { scanned: candidates.length, flagged, cleared, notifiedStewards };
 }
 
+async function workspaceGC(): Promise<Record<string, unknown>> {
+  const now = Date.now();
+  const cutoff = now - WORKSPACE_RETENTION_MS;
+  const reviewCutoff = now - WORKSPACE_REVIEW_TTL_MS;
+
+  // 1. Prune terminal rows past retention
+  const all = listWorkspaces();
+  const terminalIds: string[] = [];
+  for (const ws of all) {
+    if (TERMINAL_WORKSPACE_STATUSES.has(ws.status) && ws.updatedAt < cutoff) {
+      deleteWorkspace(ws.id);
+      terminalIds.push(ws.id);
+    }
+  }
+
+  // 2. Auto-abandon stale review_requested worktrees
+  const abandonedIds: string[] = [];
+  const notifiedStewards: string[] = [];
+  for (const ws of all) {
+    if (ws.status === "review_requested" && ws.updatedAt < reviewCutoff) {
+      updateWorkspaceStatus(ws.id, "abandoned", { autoAbandoned: true, abandonedReason: "review_requested TTL exceeded", abandonedAt: now });
+      abandonedIds.push(ws.id);
+      if (ws.stewardAgentId) {
+        try {
+          const msg = sendMessage({
+            from: "system",
+            to: ws.stewardAgentId,
+            kind: "system",
+            subject: "Workspace auto-abandoned",
+            body: `Workspace \`${ws.branch ?? ws.id}\` in ${ws.repoRoot} was auto-abandoned after ${Math.round(WORKSPACE_REVIEW_TTL_MS / DAY_MS)}d without steward action. Run workspace cleanup to reclaim the worktree.`,
+            payload: { kind: "workspace.auto-abandoned", workspaceId: ws.id, repoRoot: ws.repoRoot, branch: ws.branch },
+          });
+          emitNewMessage(msg);
+          notifiedStewards.push(ws.stewardAgentId);
+        } catch {
+          // Steward gone — activity event is enough.
+        }
+      }
+      createActivityEvent({
+        clientId: `workspace-gc-abandon-${ws.id}-${now}`,
+        kind: "state",
+        title: "Workspace auto-abandoned",
+        body: `${ws.branch ?? ws.id} in ${ws.repoRoot} — review_requested for ${Math.round((now - ws.updatedAt) / DAY_MS)}d`,
+        meta: ws.branch ?? ws.id,
+        icon: "ti-clock-x",
+        view: "orchestrators",
+        metadata: { source: "server", maintenanceJobId: "workspace-gc", workspaceId: ws.id },
+      });
+    }
+  }
+
+  // 3. Trigger git worktree prune on orchestrators that own isolated workspaces
+  const orchestrators = listOrchestrators().filter((orch) => orch.status === "online" && orch.agentId);
+  const reposWithWorkspaces = new Set(
+    all.filter((ws) => ws.mode === "isolated" && Boolean(ws.worktreePath)).map((ws) => ws.repoRoot),
+  );
+  const pruneCommands: string[] = [];
+  for (const repoRoot of reposWithWorkspaces) {
+    const orch = orchestrators.find((candidate) => workspacePathWithinBase(repoRoot, candidate.baseDir));
+    if (!orch?.agentId) continue;
+    const command = createCommand({
+      type: "workspace.prune",
+      source: "system",
+      target: orch.agentId,
+      params: { repoRoot, requestedBy: "workspace-gc", requestedAt: now },
+    });
+    emitCommand(command);
+    pruneCommands.push(command.id);
+  }
+
+  return { prunedTerminal: terminalIds, autoAbandoned: abandonedIds, notifiedStewards, pruneCommands };
+}
+
 let timer: Timer | null = null;
 
 export function startMaintenanceScheduler(): void {

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);