agent-relay-server 0.119.6 → 0.119.9

package/src/maintenance/workspaces.ts

@@ -13,13 +13,14 @@ import {
   updateWorkspaceStatus,
   setWorkspaceBranch,
 } from "../db";
-import type { WorkspaceMergePreview, WorkspaceStatus } from "../types";
+import type { WorkspaceMergePreview, WorkspaceRecord, WorkspaceStatus } from "../types";
 import { notifyStewardHandoff, reconcileLandedWorkspace } from "../branch-landed";
 import { resolveStewardIdentity } from "../steward-identity";
 import { getStewardConfig } from "../config-store";
 import { preparePrCompletionScan, reconcileLandedPr } from "../workspace-pr-completion";
 import { applyBranchFreshness, fetchHostMergePreview, workspacePathWithinBase } from "../workspace-probe";
 import { wakeRepoSteward } from "../workspace-auto-merge";
+import { workspaceOwnerOrchestrator } from "../workspace-host";
 import {
   CONFLICT_SCAN_STATUSES,
   DAY_MS,
@@ -44,7 +45,7 @@ export async function scanWorkspaceConflicts(): Promise<Record<string, unknown>>
   const reviewerArmed: string[] = [], reviewerChangesRequested: string[] = [], relayPrMerged: string[] = [], relayPrWaiting: string[] = [];
 
   for (const ws of candidates) {
-    const orch = orchestrators.find((candidate) => workspacePathWithinBase(ws.sourceCwd, candidate.baseDir));
+    const orch = workspaceOwnerOrchestrator(ws, orchestrators, { requireApiUrl: true });
     if (!orch?.apiUrl) continue;
     const preview = await fetchHostMergePreview(orch.apiUrl, ws, { checkPr: LANDED_RECONCILE_STATUSES.has(ws.status) });
     if (!preview || (preview as { available?: false }).available === false) continue;
@@ -129,6 +130,31 @@ export async function scanWorkspaceConflicts(): Promise<Record<string, unknown>>
   return { scanned: candidates.length, flagged, cleared, merged, prRecycled, notifiedStewards, reviewerArmed, reviewerChangesRequested, relayPrMerged, relayPrWaiting };
 }
 
+type AutoAbandonDecision =
+  | { kind: "abandon" }
+  | { kind: "defer"; reason: string }
+  | { kind: "landed"; preview: WorkspaceMergePreview };
+
+function previewProvesLanded(preview: WorkspaceMergePreview): boolean {
+  const cleanWorktree = (preview.dirtyCount ?? 0) === 0;
+  return preview.landed === true
+    || preview.prMerged === true
+    || preview.noop === true
+    || (cleanWorktree && (preview.unmergedAhead === 0 || preview.ahead === 0));
+}
+
+async function reviewAutoAbandonDecision(ws: WorkspaceRecord, orchestrators: ReturnType<typeof listOrchestrators>): Promise<AutoAbandonDecision> {
+  const owner = workspaceOwnerOrchestrator(ws, orchestrators, { requireApiUrl: true });
+  if (!owner?.apiUrl) return ws.orchestratorId ? { kind: "defer", reason: "owner-unavailable" } : { kind: "abandon" };
+  const preview = await fetchHostMergePreview(owner.apiUrl, ws, { checkPr: true });
+  if (!preview || (preview as { available?: false }).available === false) return { kind: "defer", reason: "owner-unavailable" };
+  const p = preview as WorkspaceMergePreview;
+  if (p.error) return { kind: "defer", reason: "preview-error" };
+  if (previewProvesLanded(p)) return { kind: "landed", preview: p };
+  if ((p.dirtyCount ?? 0) > 0) return { kind: "defer", reason: "dirty-worktree" };
+  return { kind: "abandon" };
+}
+
 export async function workspaceGC(): Promise<Record<string, unknown>> {
   const now = Date.now();
   const cutoff = now - WORKSPACE_RETENTION_MS;
@@ -147,6 +173,7 @@ export async function workspaceGC(): Promise<Record<string, unknown>> {
   const escalatedIds: string[] = [];
   const reassignedIds: string[] = [];
   const escalationTargets: string[] = [];
+  const reconciledLandedIds: string[] = [];
   const escalationMs = stewardEscalationMs();
   const fallbackTarget = stewardFallbackTarget();
   for (const ws of all) {
@@ -159,6 +186,20 @@ export async function workspaceGC(): Promise<Record<string, unknown>> {
     const stewardOnline = Boolean(steward && getAgent(steward) && getAgent(steward)!.status !== "offline");
     const strandedAt = typeof meta.strandedAt === "number" ? meta.strandedAt : undefined;
 
+    if (!stewardOnline) {
+      const orch = workspaceOwnerOrchestrator(fresh, listOrchestrators().filter((o) => o.status === "online" && o.apiUrl), { requireApiUrl: true });
+      const preview = orch?.apiUrl ? await fetchHostMergePreview(orch.apiUrl, fresh, { checkPr: true }) : null;
+      if (preview && !("available" in preview) && !preview.error && !preview.missing) {
+        const landed = previewProvesLanded(preview);
+        if (landed) {
+          reconcileLandedWorkspace(fresh, preview);
+          patchWorkspaceMetadata(fresh.id, { strandedAt: undefined, escalatedAt: undefined, strandedNotifiedSteward: undefined });
+          reconciledLandedIds.push(fresh.id);
+          continue;
+        }
+      }
+    }
+
     if (stewardOnline) {
       if (strandedAt !== undefined && meta.strandedNotifiedSteward !== steward) {
         const sent = notifyTarget(
@@ -206,30 +247,45 @@ export async function workspaceGC(): Promise<Record<string, unknown>> {
   }
 
   const abandonedIds: string[] = [];
+  const autoAbandonDeferred: string[] = [];
   const notifiedStewards: string[] = [];
+  const reviewOrchestrators = listOrchestrators();
   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);
-      const target = ws.stewardAgentId ?? fallbackTarget;
+      const fresh = getWorkspace(ws.id);
+      if (!fresh || fresh.status !== "review_requested") continue;
+      const decision = await reviewAutoAbandonDecision(fresh, reviewOrchestrators);
+      if (decision.kind === "defer") {
+        autoAbandonDeferred.push(`${fresh.id}:${decision.reason}`);
+        continue;
+      }
+      if (decision.kind === "landed") {
+        reconcileLandedWorkspace(fresh, decision.preview);
+        reconciledLandedIds.push(fresh.id);
+        continue;
+      }
+
+      updateWorkspaceStatus(fresh.id, "abandoned", { autoAbandoned: true, abandonedReason: "review_requested TTL exceeded", abandonedAt: now });
+      abandonedIds.push(fresh.id);
+      const target = fresh.stewardAgentId ?? fallbackTarget;
       const sent = notifyTarget(
         "workspace.auto_abandoned",
-        { workspaceId: ws.id, repoRoot: ws.repoRoot },
+        { workspaceId: fresh.id, repoRoot: fresh.repoRoot },
         target,
         "Workspace auto-abandoned",
-        `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.`,
-        { kind: "workspace.auto-abandoned", workspaceId: ws.id, repoRoot: ws.repoRoot, branch: ws.branch },
+        `Workspace \`${fresh.branch ?? fresh.id}\` in ${fresh.repoRoot} was auto-abandoned after ${Math.round(WORKSPACE_REVIEW_TTL_MS / DAY_MS)}d without steward action. Run workspace cleanup to reclaim the worktree.`,
+        { kind: "workspace.auto-abandoned", workspaceId: fresh.id, repoRoot: fresh.repoRoot, branch: fresh.branch },
       );
       if (sent) notifiedStewards.push(sent);
       createActivityEvent({
-        clientId: `workspace-gc-abandon-${ws.id}-${now}`,
+        clientId: `workspace-gc-abandon-${fresh.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,
+        body: `${fresh.branch ?? fresh.id} in ${fresh.repoRoot} - review_requested for ${Math.round((now - fresh.updatedAt) / DAY_MS)}d`,
+        meta: fresh.branch ?? fresh.id,
         icon: "ti-clock-x",
         view: "orchestrators",
-        metadata: { source: "server", maintenanceJobId: "workspace-gc", workspaceId: ws.id },
+        metadata: { source: "server", maintenanceJobId: "workspace-gc", workspaceId: fresh.id },
       });
     }
   }
@@ -255,12 +311,14 @@ export async function workspaceGC(): Promise<Record<string, unknown>> {
   return {
     prunedTerminal: terminalIds,
     autoAbandoned: abandonedIds,
+    autoAbandonDeferred,
     notifiedStewards,
     pruneCommands,
     releasedLeaseRepos,
     escalated: escalatedIds,
     reassigned: reassignedIds,
     escalationTargets,
+    reconciledLanded: reconciledLandedIds,
   };
 }
 
@@ -288,7 +346,7 @@ export async function refreshIdleWorkspaces(): Promise<Record<string, unknown>>
   const now = Date.now();
 
   for (const ws of candidates) {
-    const orch = orchestrators.find((candidate) => workspacePathWithinBase(ws.sourceCwd, candidate.baseDir));
+    const orch = workspaceOwnerOrchestrator(ws, orchestrators);
     if (!orch?.agentId) { skipped.push(`${ws.id}:no-orchestrator`); continue; }
 
     // Gate: owner must exist and not be busy.

package/src/routes/commands.ts

@@ -22,6 +22,7 @@ import { handleReviewerMergeResult } from "../reviewer-pipeline";
 import { CLEAR_MERGE_NO_PROGRESS, noteMergeNoProgress, scheduleRepoMerge } from "../workspace-auto-merge";
 import { enqueueContinuationInjectionAfterSelfResume } from "../self-resume";
 import { type Command, type CommandStatus, type CreateCommandInput, type WorkspaceStatus } from "../types";
+import { commandTargetsWorkspaceOwner } from "../workspace-host";
 
 const VALID_COMMAND_STATUSES = ["pending", "accepted", "running", "succeeded", "failed", "timed_out", "rejected", "canceled"] as const;
 
@@ -227,10 +228,13 @@ export const patchCommand: Handler = async (req, params) => {
     if (command.type === "workspace.cleanup" && command.status === "succeeded" && isRecord(command.result)) {
       const workspaceId = cleanString(command.result.workspaceId, "result.workspaceId", { max: 160 });
       if (workspaceId) {
-        updateWorkspaceStatus(workspaceId, "cleaned", {
-          cleanupResult: command.result,
-          cleanupCommandId: command.id,
-        });
+        const workspace = getWorkspace(workspaceId);
+        if (workspace && commandTargetsWorkspaceOwner(command, workspace)) {
+          updateWorkspaceStatus(workspaceId, "cleaned", {
+            cleanupResult: command.result,
+            cleanupCommandId: command.id,
+          });
+        }
       }
     }
     if (command.type === "workspace.idle-refresh" && command.status === "succeeded" && isRecord(command.result)) {
@@ -261,6 +265,10 @@ export const patchCommand: Handler = async (req, params) => {
           // Snapshot the row BEFORE the recycle repoints `branch` (#206) — the landed
           // branch name + author (#239 branch.landed push) come from this pre-mutation state.
           const landedWorkspace = getWorkspace(workspaceId);
+          if (landedWorkspace && !commandTargetsWorkspaceOwner(command, landedWorkspace)) {
+            auditCommandOutcome(command);
+            return json(command);
+          }
           const newBranch = cleanString(command.result.newBranch, "result.newBranch", { max: 240 });
           const normalizedStatus = command.result.merged === true
             && !newBranch
@@ -361,6 +369,10 @@ export const patchCommand: Handler = async (req, params) => {
         // auto-merge job backs off after N instead of busy-looping (#638).
         const current = getWorkspace(command.correlationId);
         if (current && current.status === "merge_planned") {
+          if (!commandTargetsWorkspaceOwner(command, current)) {
+            auditCommandOutcome(command);
+            return json(command);
+          }
           const failedResultStatus = isRecord(command.result)
             ? optionalEnum(command.result.status, "result.status", VALID_WORKSPACE_STATUSES) as WorkspaceStatus | undefined
             : undefined;
@@ -420,6 +432,10 @@ export const patchCommand: Handler = async (req, params) => {
         // a status a human/agent has since moved on (merge_planned, abandoned, …).
         const current = getWorkspace(workspaceId);
         if (current && (current.status === "active" || current.status === "ready")) {
+          if (!commandTargetsWorkspaceOwner(command, current)) {
+            auditCommandOutcome(command);
+            return json(command);
+          }
           if (removed) {
             // The owner exited and the worktree had no work — the orchestrator
             // already deleted it on disk. Drop the DB row immediately instead of

package/src/routes/workspaces.ts

@@ -15,6 +15,7 @@ import { AUTO_MERGE_POLICIES } from "../workspace-merge";
 import { workspaceActiveClaim } from "../workspace-claim";
 import { resolveCoordinatorAgentId } from "../steward-identity";
 import { relayToken } from "../config";
+import { workspaceOwnerOrchestrator } from "../workspace-host";
 
 export const getWorkspaces: Handler = (req) => {
   try {
@@ -44,9 +45,7 @@ async function proxyWorkspaceHostGet(workspaceId: string, hostPath: string, extr
   if (workspace.mode !== "isolated" || !workspace.worktreePath) {
     return json({ available: false, reason: "no isolated worktree" });
   }
-  const orch = listOrchestrators().find(
-    (candidate) => candidate.status === "online" && candidate.apiUrl && isPathWithinBase(workspace.sourceCwd, candidate.baseDir),
-  );
+  const orch = workspaceOwnerOrchestrator(workspace, listOrchestrators(), { requireApiUrl: true });
   if (!orch?.apiUrl) return json({ available: false, reason: "owning orchestrator offline" });
   const query = new URLSearchParams({ path: workspace.worktreePath });
   if (workspace.baseRef) query.set("baseRef", workspace.baseRef);
@@ -287,9 +286,7 @@ export const postWorkspaceOrphanReclaim: Handler = async (req) => {
 
 async function fetchWorkspaceGitState(workspace: WorkspaceRecord): Promise<{ state: WorkspaceGitState } | { unavailable: string }> {
   if (workspace.mode !== "isolated" || !workspace.worktreePath) return { unavailable: "no isolated worktree" };
-  const orch = listOrchestrators().find(
-    (candidate) => candidate.status === "online" && candidate.apiUrl && isPathWithinBase(workspace.sourceCwd, candidate.baseDir),
-  );
+  const orch = workspaceOwnerOrchestrator(workspace, listOrchestrators(), { requireApiUrl: true });
   if (!orch?.apiUrl) return { unavailable: "owning orchestrator offline" };
   const query = new URLSearchParams({ path: workspace.worktreePath });
   if (workspace.baseRef) query.set("baseRef", workspace.baseRef);
@@ -342,7 +339,7 @@ export const getWorkspaceDiagnostics: Handler = async (_req, params) => {
   // #640 — surface the branch agent's coordinator (owner's `spawnedBy` lineage) so a steward
   // inspecting the workspace knows who to escalate to, not just `repoRoot`.
   const coordinatorAgentId = resolveCoordinatorAgentId(workspace.ownerAgentId);
-  const orch = listOrchestrators().find((candidate) => isPathWithinBase(workspace.sourceCwd, candidate.baseDir));
+  const orch = workspaceOwnerOrchestrator(workspace, listOrchestrators(), { onlineOnly: false });
   const orchOnline = Boolean(orch) && orch!.status === "online";
   const fetched = await fetchWorkspaceGitState(workspace);
   const gitState = "state" in fetched ? fetched.state : undefined;
@@ -380,8 +377,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 +391,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 +415,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, hasArtifactCreatedBy, listAgents, listFinalResponseCaptureMessages, listOrchestrators, listWorkspaces, recordTerminalEvent } from "../db";
 import { routeNotification } from "../notification-router";
 import { isProviderBlocked } from "../provider-state";
+import { relayToken } from "../config";
+import { workspaceOwnerOrchestrator } from "../workspace-host";
 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,28 @@ 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 = workspaceOwnerOrchestrator(ws, listOrchestrators(), { requireApiUrl: true });
+  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 +108,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,14 +128,61 @@ 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 } {
+const ACK_ONLY_RESPONSES = new Set([
+  "ok",
+  "okay",
+  "done",
+  "finished",
+  "complete",
+  "completed",
+  "ack",
+  "acknowledged",
+  "thanks",
+  "thank you",
+]);
+
+const REPORT_SIGNAL_RE = /\b(ship|hold|pass|fail|finding|findings|issue|issues|blocker|blockers|reviewed|verified|tested|tests?|risk|regression|artifact|summary|audited|inspected)\b/i;
+const GENERIC_COMPLETION_RE = /\b(?:i(?:'m| am)|we(?:'re| are))?\s*(?:done|finished|complete|completed)\b|\b(?:task|work)\s+(?:is\s+)?(?:done|finished|complete|completed)\b|\b(?:all set|nothing else|nothing more|no further action|no more to do|do not need to do anything else|don't need to do anything else)\b/i;
+
+function genericCompletionOnly(normalized: string): boolean {
+  return GENERIC_COMPLETION_RE.test(normalized) && !REPORT_SIGNAL_RE.test(normalized);
+}
+
+function substantiveFinalReport(body: string): boolean {
+  const normalized = body.trim().replace(/\s+/g, " ");
+  if (!normalized) return false;
+  const ackKey = normalized.toLowerCase().replace(/[.!?]+$/g, "");
+  if (ACK_ONLY_RESPONSES.has(ackKey)) return false;
+  if (genericCompletionOnly(normalized)) return false;
+  const words = normalized.match(/[A-Za-z0-9][A-Za-z0-9'_-]*/g) ?? [];
+  if (normalized.length >= 80 && words.length >= 6) return true;
+  if (normalized.length >= 40 && words.length >= 8) return true;
+  return normalized.length >= 30
+    && words.length >= 5
+    && REPORT_SIGNAL_RE.test(normalized);
+}
+
+function reportOnlyWorkEvidence(agent: AgentCard): { producedWork: boolean; reason?: string } {
+  const since = typeof agent.createdAt === "number" && Number.isFinite(agent.createdAt) ? agent.createdAt : 0;
+  if (hasArtifactCreatedBy(agent.id, since)) return { producedWork: true, reason: "artifact-upload" };
+  const reports = listFinalResponseCaptureMessages(agent.id, since);
+  const hasSubstantiveReport = reports.some((message) => {
+    if (agent.spawnedBy && message.to !== agent.spawnedBy) return false;
+    return substantiveFinalReport(message.body);
+  });
+  return hasSubstantiveReport ? { producedWork: true, reason: "final-response-report" } : { producedWork: false };
+}
+
+async function transientLandComplete(agent: AgentCard): Promise<{ complete: boolean; producedWork: boolean; workspaceId?: string; status?: string; reason?: string }> {
   const agentId = agent.id;
+  const reportEvidence = reportOnlyWorkEvidence(agent);
   const isolated = listWorkspaces({ ownerAgentId: agentId }).filter((ws) => ws.mode === "isolated");
-  if (!isolated.length) return { complete: true, producedWork: completedProviderTurns(agent) > 0, reason: "no-isolated-workspace" };
+  if (!isolated.length) return { complete: true, producedWork: reportEvidence.producedWork, reason: reportEvidence.reason ?? "no-isolated-workspace" };
   const live = isolated.find((ws) => !TERMINAL_WORKSPACE_STATUSES.has(ws.status));
   if (!live) {
     const latest = isolated[0];
-    return { complete: true, producedWork: workspaceProducedWork(latest), workspaceId: latest?.id, status: latest?.status, reason: "terminal-workspace" };
+    const producedWork = workspaceProducedWork(latest);
+    return { complete: true, producedWork: producedWork || reportEvidence.producedWork, workspaceId: latest?.id, status: latest?.status, reason: producedWork ? "terminal-workspace" : reportEvidence.reason ?? "terminal-workspace" };
   }
   const mergedAt = typeof live.metadata.mergedAt === "number" ? live.metadata.mergedAt : undefined;
   const landReportedAt = typeof live.metadata.landReportedAt === "number" ? live.metadata.landReportedAt : undefined;
@@ -134,8 +193,8 @@ 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) {
-    return { complete: true, producedWork: false, workspaceId: live.id, status: live.status, reason: "empty-branch" };
+  if (live.status === "active" && await _commitsAheadFn(live) === 0) {
+    return { complete: true, producedWork: reportEvidence.producedWork, workspaceId: live.id, status: live.status, reason: reportEvidence.reason ?? "empty-branch" };
   }
   return { complete: false, producedWork: false, workspaceId: live.id, status: live.status, reason: "land-pending" };
 }
@@ -171,7 +230,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 +252,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);
@@ -212,7 +271,7 @@ export function reapTransientAgents(): Record<string, unknown> {
       workspaceId: land.workspaceId,
       workspaceStatus: land.status,
       activityTitle: "Transient agent complete",
-      activityBody: "Agent idle grace elapsed and branch work is land-complete; shutdown requested",
+      activityBody: "Agent idle grace elapsed and transient work is complete; shutdown requested",
       landReason: land.reason,
       now,
     });