agent-relay-server 0.119.6 → 0.119.7

package/runner/plugins/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-relay-runner",
   "description": "Thin Agent Relay runner bridge for Claude Code",
-  "version": "0.119.6",
+  "version": "0.119.7",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/src/commands-db.ts

@@ -26,19 +26,25 @@ interface CommandFilters {
   limit?: number;
 }
 
-const ACTIVE_STATUSES: CommandStatus[] = ["pending", "accepted", "running"];
+const CLAIMED_ACTIVE_STATUSES: CommandStatus[] = ["accepted", "running"];
+const SPAWN_IN_FLIGHT_STATUSES: CommandStatus[] = ["pending", "accepted", "running"];
 const TERMINAL_STATUSES: CommandStatus[] = ["succeeded", "failed", "canceled", "timed_out"];
 
-// #930 — an `agent.spawn` command carries a hard TTL from CREATION (see
-// defaultExpiresAt). The #880 concurrency cap introduces REAL queuing, so a
-// legitimately-queued spawn can sit `accepted`/`running` in the orchestrator past
-// that create-time TTL and be swept to `timed_out` while the orchestrator still
-// intends to run it. Refresh the TTL from dispatch-intent (claim → accepted, or
-// slot-acquire → running) so the window measures from when the host committed to
-// the spawn, not from enqueue. Scoped to `agent.spawn`; every other command type
-// keeps create-time TTL semantics.
+// #930/#953 — command TTLs are execution leases, not delivery deadlines. The #880
+// spawn cap and long inline orchestrator commands both introduce legitimate
+// queuing before dispatch, so pending commands must not be swept before the host
+// can claim them. Refresh expiring command types at dispatch-intent (claim →
+// accepted, or slot-acquire → running) so the window measures from when the host
+// committed to doing the work, not from enqueue.
 const SPAWN_TTL_MS = 180_000;
-const SPAWN_DISPATCH_STATUSES: CommandStatus[] = ["accepted", "running"];
+const LIFECYCLE_TTL_MS = 30_000;
+const DISPATCH_STATUSES: CommandStatus[] = ["accepted", "running"];
+
+function commandTtlMs(type: string): number | undefined {
+  if (type === "agent.spawn") return SPAWN_TTL_MS;
+  if (type === "agent.shutdown" || type === "agent.restart" || type === "agent.reconnect" || type === "agent.kill" || type === "agent.compact" || type === "agent.clearContext" || type === "agent.injectContext") return LIFECYCLE_TTL_MS;
+  return undefined;
+}
 
 function isTerminalStatus(status: CommandStatus): boolean {
   return TERMINAL_STATUSES.includes(status);
@@ -123,6 +129,51 @@ export function listCommands(filters: CommandFilters = {}): Command[] {
   return rows.map(rowToCommand);
 }
 
+export function findSpawnCommandByRequestId(spawnRequestId: string, statuses?: CommandStatus[]): Command | null {
+  const cleaned = spawnRequestId.trim();
+  if (!cleaned) return null;
+  const statusClause = statuses?.length
+    ? `AND status IN (${statuses.map(() => "?").join(",")})`
+    : "";
+  const rows = getDb()
+    .query(`
+      SELECT * FROM commands
+      WHERE type = 'agent.spawn'
+        ${statusClause}
+        AND (correlation_id = ? OR json_extract(params, '$.spawnRequestId') = ?)
+      ORDER BY created_at DESC
+      LIMIT 1
+    `)
+    .all(...(statuses ?? []), cleaned, cleaned) as CommandRow[];
+  return rows[0] ? rowToCommand(rows[0]) : null;
+}
+
+export function countInFlightSpawnCommands(parentId: string): number {
+  const row = getDb()
+    .query(
+      `SELECT count(*) AS n
+       FROM commands
+       WHERE type = 'agent.spawn'
+         AND status IN (${SPAWN_IN_FLIGHT_STATUSES.map(() => "?").join(",")})
+         AND json_extract(params, '$.spawnedBy') = ?`,
+    )
+    .get(...SPAWN_IN_FLIGHT_STATUSES, parentId) as { n: number };
+  return row.n;
+}
+
+export function createSpawnCommandWithinQuota(
+  input: CreateCommandInput,
+  quota: { parentId: string; maxSpawnedAgents: number; liveChildren: () => number },
+): { command: Command | null; occupiedSlots: number } {
+  return getDb().transaction(() => {
+    const live = quota.liveChildren();
+    const inFlight = countInFlightSpawnCommands(quota.parentId);
+    const occupied = live + inFlight;
+    if (occupied >= quota.maxSpawnedAgents) return { command: null, occupiedSlots: occupied };
+    return { command: createCommand(input), occupiedSlots: occupied + 1 };
+  })();
+}
+
 export function updateCommand(id: string, input: UpdateCommandInput): Command | null {
   const existing = getCommand(id);
   if (!existing) return null;
@@ -145,12 +196,14 @@ export function updateCommand(id: string, input: UpdateCommandInput): Command |
     return existing;
   }
   const now = Date.now();
-  // #930 — refresh the spawn TTL from dispatch-intent when the command is claimed or
-  // dispatched (see SPAWN_DISPATCH_STATUSES). Other command types keep their existing
-  // expiry untouched.
+  // #930/#953 — refresh the lease from dispatch-intent when an expiring command is
+  // claimed or starts running. Pending commands are not swept before delivery, so a
+  // busy orchestrator must not inherit an already-expired lease when it finally gets
+  // back to the command loop.
+  const ttlMs = input.status && DISPATCH_STATUSES.includes(input.status) ? commandTtlMs(existing.type) : undefined;
   const nextExpiresAt =
-    existing.type === "agent.spawn" && input.status && SPAWN_DISPATCH_STATUSES.includes(input.status)
-      ? now + SPAWN_TTL_MS
+    ttlMs !== undefined
+      ? now + ttlMs
       : existing.expiresAt ?? null;
   getDb().query(`
     UPDATE commands
@@ -179,16 +232,15 @@ export function deleteCommand(id: string): boolean {
 
 export function expireCommands(now: number = Date.now()): Command[] {
   const rows = getDb()
-    .query(`SELECT * FROM commands WHERE expires_at IS NOT NULL AND expires_at <= ? AND status IN (${ACTIVE_STATUSES.map(() => "?").join(",")})`)
-    .all(now, ...ACTIVE_STATUSES) as CommandRow[];
+    .query(`SELECT * FROM commands WHERE expires_at IS NOT NULL AND expires_at <= ? AND status IN (${CLAIMED_ACTIVE_STATUSES.map(() => "?").join(",")})`)
+    .all(now, ...CLAIMED_ACTIVE_STATUSES) as CommandRow[];
   for (const row of rows) updateCommand(row.id, { status: "timed_out", error: "command timed out" });
   return rows.map((row) => getCommand(row.id)).filter((command): command is Command => Boolean(command));
 }
 
 function defaultExpiresAt(type: string, now: number): number | undefined {
-  if (type === "agent.spawn") return now + SPAWN_TTL_MS;
-  if (type === "agent.shutdown" || type === "agent.restart" || type === "agent.reconnect" || type === "agent.kill" || type === "agent.compact" || type === "agent.clearContext" || type === "agent.injectContext") return now + 30_000;
-  return undefined;
+  const ttlMs = commandTtlMs(type);
+  return ttlMs === undefined ? undefined : now + ttlMs;
 }
 
 function recordShutdownTerminalEventOnSuccess(previousStatus: CommandStatus, command: Command): void {

package/src/db/workspaces.ts

@@ -16,6 +16,7 @@ import { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS, POOL_CLAIM_LEASE_MS, WORKSPACE_ME
 import { matchAgents } from "../agent-ref";
 import { getDb } from "./connection.ts";
 import { resolveProjectsForCwds } from "./projects.ts";
+import { workspaceActiveClaim } from "../workspace-claim";
 import type {
   AgentCard,
   ActivityEvent,
@@ -511,6 +512,46 @@ export function patchWorkspaceMetadata(id: string, patch: Record<string, unknown
   return getWorkspace(id);
 }
 
+type WorkspaceClaimResult =
+  | { ok: true; workspace: WorkspaceRecord }
+  | { ok: false; reason: "not-found" | "claimed-by-other"; workspace?: WorkspaceRecord };
+
+export function claimWorkspaceMetadata(
+  id: string,
+  claimant: string,
+  patch: Record<string, unknown>,
+  now: number = Date.now(),
+): WorkspaceClaimResult {
+  const run = getDb().transaction((): WorkspaceClaimResult => {
+    const existing = getWorkspace(id);
+    if (!existing) return { ok: false, reason: "not-found" as const };
+    const active = workspaceActiveClaim(existing, now);
+    if (active?.by && active.by !== claimant) return { ok: false, reason: "claimed-by-other" as const, workspace: existing };
+    const next = { ...existing.metadata, ...patch };
+    getDb().query("UPDATE workspaces SET metadata = ? WHERE id = ?").run(JSON.stringify(next), id);
+    return { ok: true as const, workspace: getWorkspace(id)! };
+  });
+  return run();
+}
+
+export function releaseWorkspaceClaimMetadata(
+  id: string,
+  claimant: string,
+  patch: Record<string, unknown>,
+  now: number = Date.now(),
+): WorkspaceClaimResult {
+  const run = getDb().transaction((): WorkspaceClaimResult => {
+    const existing = getWorkspace(id);
+    if (!existing) return { ok: false, reason: "not-found" as const };
+    const active = workspaceActiveClaim(existing, now);
+    if (active?.by && active.by !== claimant) return { ok: false, reason: "claimed-by-other" as const, workspace: existing };
+    const next = { ...existing.metadata, ...patch };
+    getDb().query("UPDATE workspaces SET metadata = ? WHERE id = ?").run(JSON.stringify(next), id);
+    return { ok: true as const, workspace: getWorkspace(id)! };
+  });
+  return run();
+}
+
 // Re-elect stewards for every repo where an agent owns a live workspace. Called
 // when an agent (re)registers so a dormant repo regains a steward on rejoin
 // without a full unscoped sweep.

package/src/routes/workspaces.ts

@@ -380,8 +380,7 @@ export const postWorkspaceCleanupStale: Handler = async (req) => {
   // a destructive-action footgun. Now an explicit id narrows the candidate set.
   const workspaceId = cleanString(body.workspaceId, "workspaceId", { max: 160 });
   const dryRun = body.dryRun !== false; // safe by default
-  const landedOnly = body.landedOnly !== false;
-  const offlineOwnerOnly = body.offlineOwnerOnly !== false;
+  const landedOnly = true;
 
   const candidates = listWorkspaces().filter((ws) =>
     ws.mode === "isolated" && Boolean(ws.worktreePath) && !TERMINAL_WORKSPACE_STATUSES.has(ws.status)
@@ -395,7 +394,6 @@ export const postWorkspaceCleanupStale: Handler = async (req) => {
     const owner = ws.ownerAgentId ? getAgent(ws.ownerAgentId) : null;
     const ownerOnline = isOwnerAlive(ws.ownerAgentId);
     if (ownerOnline) continue;                         // never clean a live owner's worktree
-    if (offlineOwnerOnly && !ws.ownerAgentId) { /* no owner recorded — still eligible */ }
     if (workspaceActiveClaim(ws)) continue;            // respect steward claims
     const fetched = await fetchWorkspaceGitState(ws);
     const gitState = "state" in fetched ? fetched.state : undefined;
@@ -420,7 +418,7 @@ export const postWorkspaceCleanupStale: Handler = async (req) => {
     }
     rows.push(row);
   }
-  return json({ dryRun, landedOnly, offlineOwnerOnly, repoRoot, ...(workspaceId ? { workspaceId } : {}), scanned: candidates.length, eligible: rows.filter((r) => r.safe).length, cleaned, candidates: rows }, dryRun ? 200 : 202);
+  return json({ dryRun, landedOnly, repoRoot, ...(workspaceId ? { workspaceId } : {}), scanned: candidates.length, eligible: rows.filter((r) => r.safe).length, cleaned, candidates: rows }, dryRun ? 200 : 202);
 };
 
 export const postWorkspaceAction: Handler = async (req, params) => {

package/src/services/shutdown-agent.ts

@@ -79,6 +79,11 @@ function str(v: unknown): string | undefined {
   return typeof v === "string" && v.length > 0 ? v : undefined;
 }
 
+export function callerOwnsSpawnedAgent(ctx: AuthContext, target: AgentCard | null | undefined): boolean {
+  const callerId = ctx.callerAgentId;
+  return Boolean(callerId && target?.spawnedBy === callerId);
+}
+
 /** Build a ShutdownAgentInput from a WS-bus `agent.shutdown` command frame's target +
  * params. Lives here (not in bus.ts) so the bus transport stays a thin dispatcher and the
  * shutdown-input shape has one home. */
@@ -123,7 +128,7 @@ export function authorizeShutdown(ctx: AuthContext, input: ShutdownAgentInput):
   const target = input.agentId
     ? getAgent(input.agentId)
     : listAgents().find((a) => a.meta?.spawnRequestId === input.spawnRequestId);
-  if (!target || target.spawnedBy !== callerId) {
+  if (!target || !callerOwnsSpawnedAgent(ctx, target)) {
     throw new ShutdownAuthError(
       input.agentId
         ? `agent ${input.agentId} is not one of your spawned children`

package/src/services/spawn-agent.ts

@@ -28,7 +28,7 @@ import { DEFAULT_USER_ID, errMessage, isRecord, stringValue } from "agent-relay-
 import { statSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { countLiveSpawnedAgents, createActivityEvent, ensureTeam, getAgent, getTaskDetail, listAgents, listProjects, listWorkspaces, recordTaskSpawnRequested, resolveAgentOwnership, resolveProjectForCwd, resolveScopedAnchor, rootsForProject, setAgentTeam, ValidationError, withResolvedProvisioning } from "../db";
-import { createCommand } from "../commands-db";
+import { countInFlightSpawnCommands, createCommand, createSpawnCommandWithinQuota, findSpawnCommandByRequestId } from "../commands-db";
 import { emitCommandEvent } from "../command-events";
 import { buildSpawnCommand, generateSpawnRequestId, resolveSpawnModelParams } from "../spawn-command";
 import { runnerRuntimeTokenEnv } from "../runtime-tokens";
@@ -48,12 +48,14 @@ import { hasComponentScope, isComponentAuthorizedFor } from "../security";
 import { isPathWithinBase } from "../utils";
 import { McpAuthError, McpNotFoundError } from "../mcp-errors";
 import type { AuthContext } from "./auth-context";
-import type { AgentCard, AgentLifecycle, Command, SpawnApprovalMode, WorkspaceAutoMergePolicy, WorkspaceLandingPolicy, WorkspaceMode } from "../types";
+import { callerOwnsSpawnedAgent } from "./shutdown-agent";
+import type { AgentCard, AgentLifecycle, Command, CommandStatus, CreateCommandInput, SpawnApprovalMode, WorkspaceAutoMergePolicy, WorkspaceLandingPolicy, WorkspaceMode } from "../types";
 import { isOwnerAlive, liveAgentCwds, worktreeInUseByLiveAgent } from "../workspace-merge";
 import { TERMINAL_WORKSPACE_STATUSES } from "../workspace-phase";
 
 /** The spawn scope every transport must hold (admin `*` / `admin:*` pass; `system` bypasses). */
 const SPAWN_SCOPE = "command:spawn";
+const ACTIVE_SPAWN_COMMAND_STATUSES: CommandStatus[] = ["pending", "accepted", "running"];
 
 function hasGitMarker(dir: string): boolean {
   try {
@@ -362,11 +364,14 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
       throw new McpAuthError("spawned agents cannot spawn further agents (no grandchildren)");
     }
     const quota = ctx.constraints?.maxSpawnedAgents ?? 0;
-    const live = countLiveSpawnedAgents(callerId);
-    if (live >= quota) {
-      throw new ValidationError(`spawn quota reached (${live}/${quota} live children) — shut one down or wait for one to exit`);
+    const occupied = countLiveSpawnedAgents(callerId) + countInFlightSpawnCommands(callerId);
+    if (occupied >= quota) {
+      throw new ValidationError(`spawn quota reached (${occupied}/${quota} live or in-flight children) — shut one down or wait for one to exit`);
     }
   }
+  const spawnQuota = callerId
+    ? { parentId: callerId, maxSpawnedAgents: ctx.constraints?.maxSpawnedAgents ?? 0 }
+    : undefined;
   // Gate the child spawn on the token's legit bounds: the target orchestrator AND the spawn cwd
   // (`cwdPrefixes`/`cwd` constraint). Excludes the #323 footguns (spawnRequestIds/policies) — those
   // are self-scoping per-spawn ids the CHILD gets fresh, so gating on them makes the quota
@@ -379,6 +384,31 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
   // the raw token actor. Recorded in the command payload, the token mint, and the audit row.
   const requestedBy = callerId ?? taskCreatorAgentId ?? input.requestedBy ?? ctx.actor.id;
 
+  const requestedSpawnRequestId = input.spawnRequestId?.trim();
+  if (requestedSpawnRequestId) {
+    const registeredAgent = listAgents().find((agent) => agent.meta?.spawnRequestId === requestedSpawnRequestId);
+    const activeCommand = findSpawnCommandByRequestId(requestedSpawnRequestId, ACTIVE_SPAWN_COMMAND_STATUSES);
+    const existingCommand = activeCommand ?? (registeredAgent ? findSpawnCommandByRequestId(requestedSpawnRequestId) : null);
+    if (existingCommand || registeredAgent) {
+      const existingParent = existingCommand ? stringValue(existingCommand.params.spawnedBy) : undefined;
+      if (callerId && existingParent !== callerId && !callerOwnsSpawnedAgent(ctx, registeredAgent)) {
+        throw new ValidationError(`spawnRequestId ${requestedSpawnRequestId} is already in use`);
+      }
+      if (!existingCommand) {
+        throw new ValidationError(`spawnRequestId ${requestedSpawnRequestId} is already registered to agent ${registeredAgent!.id}`);
+      }
+      return {
+        ok: true,
+        spawnRequestId: requestedSpawnRequestId,
+        orchestratorId: stringValue(existingCommand.params.orchestratorId) ?? orchestrator.id,
+        provider: (stringValue(existingCommand.params.provider) as SpawnProvider | undefined) ?? input.provider,
+        agentId: registeredAgent?.id ?? null,
+        registered: Boolean(registeredAgent),
+        command: existingCommand,
+      };
+    }
+  }
+
   // #405 — durable project binding: the project whose registered root contains the spawn cwd.
   // Stamped on both the child token and an auto-scaffolded Task row so issueless spawned work
   // stays filterable by project.
@@ -579,7 +609,7 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
   // command payload.
   const expectReply = input.expectReply === true;
 
-  const command = createCommand({
+  const commandInput: CreateCommandInput = {
     type: "agent.spawn",
     source: "system",
     target: orchestrator.agentId,
@@ -619,7 +649,20 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
       // so there's no agent row to resolve `spawnedBy` from) can be routed back to it.
       ...(lineageAgentId ? { extra: { spawnedBy: lineageAgentId } } : {}),
     }),
-  });
+  };
+  let command: Command;
+  if (spawnQuota) {
+    const quotaResult = createSpawnCommandWithinQuota(commandInput, {
+      ...spawnQuota,
+      liveChildren: () => countLiveSpawnedAgents(spawnQuota.parentId),
+    });
+    if (!quotaResult.command) {
+      throw new ValidationError(`spawn quota reached (${quotaResult.occupiedSlots}/${spawnQuota.maxSpawnedAgents} live or in-flight children) — shut one down or wait for one to exit`);
+    }
+    command = quotaResult.command;
+  } else {
+    command = createCommand(commandInput);
+  }
   emitCommandEvent(command, "command.requested");
 
   // ONE spawn-request audit row, identical across transports (the MCP path previously emitted

package/src/services/transient-agent-reaper.ts

@@ -1,11 +1,14 @@
+import { RELAY_TOKEN_HEADER } from "agent-relay-sdk";
 import { createCommand } from "../commands-db";
 import { emitRelayEvent } from "../events";
-import { createActivityEvent, getAgent, listAgents, listWorkspaces, recordTerminalEvent } from "../db";
+import { createActivityEvent, getAgent, listAgents, listOrchestrators, listWorkspaces, recordTerminalEvent } from "../db";
 import { routeNotification } from "../notification-router";
 import { isProviderBlocked } from "../provider-state";
+import { relayToken } from "../config";
+import { isPathWithinBase } from "../utils";
 import { TERMINAL_WORKSPACE_STATUSES } from "../workspace-phase";
 import { finalizeEphemeralTasksOnReap } from "./task-entity";
-import type { AgentCard, Command, WorkspaceRecord } from "../types";
+import type { AgentCard, Command, WorkspaceGitState, WorkspaceRecord } from "../types";
 
 // The single home for "dispose a transient/one-shot agent" — the canonical `agent.shutdown`
 // command + its events/terminal-marker/activity. Extracted so the idle-grace scan below AND
@@ -65,19 +68,30 @@ export function resetTransientTrackerForTests(): void {
 }
 
 // How many commits the agent's branch has ahead of its base. Returns null when
-// the check can't run (missing fields, git failure) — callers treat null as
+// the check can't run (missing fields, host/probe failure) — callers treat null as
 // "unknown" and preserve the safe #614 hold-pending bias: only 0 is fast-reaped.
-function defaultCommitsAhead(ws: WorkspaceRecord): number | null {
-  const base = ws.baseSha ?? ws.baseRef;
-  if (!base || !ws.branch || !ws.worktreePath) return null;
+async function defaultCommitsAhead(ws: WorkspaceRecord): Promise<number | null> {
+  if (!ws.branch || !ws.worktreePath) return null;
+  const orch = listOrchestrators().find(
+    (candidate) => candidate.status === "online" && candidate.apiUrl && isPathWithinBase(ws.sourceCwd, candidate.baseDir),
+  );
+  if (!orch?.apiUrl) return null;
+  const query = new URLSearchParams({ path: ws.worktreePath });
+  if (ws.baseRef) query.set("baseRef", ws.baseRef);
+  if (ws.baseSha) query.set("baseSha", ws.baseSha);
+  const headers: Record<string, string> = {};
+  const token = relayToken();
+  if (token) headers[RELAY_TOKEN_HEADER] = token;
   try {
-    const proc = Bun.spawnSync(
-      ["git", "-C", ws.worktreePath, "rev-list", "--count", `${base}..${ws.branch}`],
-      { stdin: "ignore", stdout: "pipe", stderr: "ignore" },
-    );
-    if (proc.exitCode !== 0) return null;
-    const n = parseInt(Buffer.from(proc.stdout).toString("utf8").trim(), 10);
-    return Number.isFinite(n) ? n : null;
+    const res = await fetch(`${orch.apiUrl}/api/workspace/state?${query.toString()}`, {
+      headers,
+      signal: AbortSignal.timeout(8_000),
+    });
+    if (!res.ok) return null;
+    const state = await res.json() as WorkspaceGitState;
+    if (state.missing || state.error || (state.dirtyCount ?? 0) > 0) return null;
+    const n = state.landed === true ? 0 : (state.unmergedAhead ?? state.ahead);
+    return typeof n === "number" && Number.isFinite(n) ? n : null;
   } catch {
     return null;
   }
@@ -96,9 +110,9 @@ function reapProtected(agent: ReturnType<typeof listAgents>[number]): boolean {
   return agent.status !== "idle" || !agent.ready || isProviderBlocked(agent);
 }
 
-let _commitsAheadFn: (ws: WorkspaceRecord) => number | null = defaultCommitsAhead;
+let _commitsAheadFn: (ws: WorkspaceRecord) => number | null | Promise<number | null> = defaultCommitsAhead;
 
-export function overrideCommitsAheadForTests(fn: (ws: WorkspaceRecord) => number | null): void {
+export function overrideCommitsAheadForTests(fn: (ws: WorkspaceRecord) => number | null | Promise<number | null>): void {
   _commitsAheadFn = fn;
 }
 export function resetCommitsAheadForTests(): void {
@@ -116,7 +130,7 @@ function workspaceProducedWork(ws: WorkspaceRecord | undefined): boolean {
   return typeof ws.metadata.mergedAt === "number";
 }
 
-function transientLandComplete(agent: AgentCard): { complete: boolean; producedWork: boolean; workspaceId?: string; status?: string; reason?: string } {
+async function transientLandComplete(agent: AgentCard): Promise<{ complete: boolean; producedWork: boolean; workspaceId?: string; status?: string; reason?: string }> {
   const agentId = agent.id;
   const isolated = listWorkspaces({ ownerAgentId: agentId }).filter((ws) => ws.mode === "isolated");
   if (!isolated.length) return { complete: true, producedWork: completedProviderTurns(agent) > 0, reason: "no-isolated-workspace" };
@@ -134,7 +148,7 @@ function transientLandComplete(agent: AgentCard): { complete: boolean; producedW
   // instead of holding it pending a land that will never happen. Only fires when the
   // branch is provably empty (count === 0); null (unknown/git error) falls through to
   // the safe #614 hold-pending bias below.
-  if (live.status === "active" && _commitsAheadFn(live) === 0) {
+  if (live.status === "active" && await _commitsAheadFn(live) === 0) {
     return { complete: true, producedWork: false, workspaceId: live.id, status: live.status, reason: "empty-branch" };
   }
   return { complete: false, producedWork: false, workspaceId: live.id, status: live.status, reason: "land-pending" };
@@ -171,7 +185,7 @@ function notifyTransientHeld(agentId: string, workspaceId: string | undefined, s
   }
 }
 
-export function reapTransientAgents(): Record<string, unknown> {
+export async function reapTransientAgents(): Promise<Record<string, unknown>> {
   const now = Date.now();
   const grace = transientGraceMs();
   const maxLandWait = transientMaxLandWaitMs();
@@ -193,7 +207,7 @@ export function reapTransientAgents(): Record<string, unknown> {
     transientTracker.set(agent.id, entry);
     const idleForMs = now - entry.firstIdleAt;
     if (idleForMs < grace) { waiting.push(agent.id); continue; }
-    const land = transientLandComplete(agent);
+    const land = await transientLandComplete(agent);
     if (!land.complete) {
       if (idleForMs >= grace + maxLandWait) {
         held.push(agent.id);

package/src/workspace-actions.ts

@@ -14,8 +14,10 @@ import { isPathWithinBase } from "./utils";
 import {
   createActivityEvent,
   getWorkspace,
+  claimWorkspaceMetadata,
   listOrchestrators,
   patchWorkspaceMetadata,
+  releaseWorkspaceClaimMetadata,
   updateWorkspaceStatus,
 } from "./db";
 import { emitActivityEvent } from "./sse";
@@ -148,8 +150,17 @@ export function applyWorkspaceAction(workspace: WorkspaceRecord, input: ApplyWor
   // so deterministic landing can't race a steward mid-validation. No status change.
   if (action === "claim" || action === "release-claim") {
     const release = action === "release-claim";
-    const updated = patchWorkspaceMetadata(workspace.id, claimMetadataPatch(release, agentId ?? "steward", input.purpose));
-    if (!updated) return { ok: false, httpStatus: 404, error: "workspace not found" };
+    const claimant = agentId ?? "steward";
+    const result = release
+      ? releaseWorkspaceClaimMetadata(workspace.id, claimant, claimMetadataPatch(true), Date.now())
+      : claimWorkspaceMetadata(workspace.id, claimant, claimMetadataPatch(false, claimant, input.purpose), Date.now());
+    if (!result.ok) {
+      if (result.reason === "not-found") return { ok: false, httpStatus: 404, error: "workspace not found" };
+      const active = result.workspace ? workspaceActiveClaim(result.workspace) : null;
+      const owner = active?.by ? ` by ${active.by}` : "";
+      return { ok: false, httpStatus: 409, error: `workspace ${workspace.id} is already claimed${owner}` };
+    }
+    const updated = result.workspace;
     recordWorkspaceAudit({
       action,
       workspace: updated,
@@ -231,6 +242,14 @@ export function applyWorkspaceAction(workspace: WorkspaceRecord, input: ApplyWor
     };
   }
 
+  let command: Command | undefined;
+  if (requiresCommand) {
+    // Only `cleanup` reaches here — `merge` returned early via the shared helper.
+    const built = buildWorkspaceCleanupCommand(workspace, agentId ?? "dashboard", { force: input.force === true });
+    if (!built.ok) return { ok: false, httpStatus: built.status, error: built.error };
+    command = built.command;
+  }
+
   const updated = updateWorkspaceStatus(workspace.id, nextStatus, {
     ...metadata,
     ...(detail ? { detail } : {}),
@@ -250,13 +269,6 @@ export function applyWorkspaceAction(workspace: WorkspaceRecord, input: ApplyWor
   // + lease-serialized; a non-landable row is a harmless no-op (autoMergeForRepo re-checks).
   if (READY_TO_LAND_STATUSES.has(nextStatus)) scheduleRepoMerge(updated.repoRoot);
 
-  let command: Command | undefined;
-  if (requiresCommand) {
-    // Only `cleanup` reaches here — `merge` returned early via the shared helper.
-    const built = buildWorkspaceCleanupCommand(workspace, agentId ?? "dashboard", { force: input.force === true });
-    if (!built.ok) return { ok: false, httpStatus: built.status, error: built.error };
-    command = built.command;
-  }
   recordWorkspaceAudit({
     action,
     workspace: updated,
@@ -289,9 +301,8 @@ export function buildWorkspaceCleanupCommand(
       error: `workspace ${workspace.id} owner is still online; pass force:true to clean it up intentionally`,
     };
   }
-  const owners = listOrchestrators().filter((candidate) => isPathWithinBase(workspace.sourceCwd, candidate.baseDir));
-  const owner = owners.find((candidate) => candidate.status === "online") ?? owners[0];
-  if (!owner) return { ok: false, status: 409, error: "no orchestrator owns this workspace path; use DELETE /api/workspaces/:id to purge the record" };
+  const owner = listOrchestrators().find((candidate) => candidate.status === "online" && isPathWithinBase(workspace.sourceCwd, candidate.baseDir));
+  if (!owner) return { ok: false, status: 409, error: "no online orchestrator owns this workspace path; retry when the host is online or use DELETE /api/workspaces/:id to purge the record" };
   const command = createCommand({
     type: "workspace.cleanup",
     source: "system",
@@ -308,7 +319,7 @@ export function buildWorkspaceCleanupCommand(
       requestedBy,
       requestedAt: Date.now(),
       deleteBranch: true,
-      queued: owner.status !== "online",
+      queued: false,
     },
   });
   return { ok: true, command };