agent-relay-server 0.119.10 → 0.119.11

package/docs/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Relay API",
-    "version": "0.119.10",
+    "version": "0.119.11",
     "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",
@@ -9440,6 +9440,34 @@
         ]
       }
     },
+    "/api/tasks/reconcile-auto-scaffolded": {
+      "post": {
+        "operationId": "postTaskReconcileAutoScaffolded",
+        "summary": "Post Task Reconcile Auto Scaffolded",
+        "tags": [
+          "Tasks"
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {}
+            }
+          }
+        },
+        "security": [
+          {
+            "bearerAuth": []
+          },
+          {
+            "tokenHeader": []
+          },
+          {
+            "tokenQuery": []
+          }
+        ]
+      }
+    },
     "/api/tasks/{id}": {
       "get": {
         "operationId": "getTaskById",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-server",
-  "version": "0.119.10",
+  "version": "0.119.11",
   "description": "Lightweight HTTP message relay for inter-agent communication across machines",
   "module": "src/index.ts",
   "type": "module",
@@ -37,7 +37,7 @@
     "CONTRIBUTING.md"
   ],
   "dependencies": {
-    "agent-relay-channels-host": "0.119.10",
+    "agent-relay-channels-host": "0.119.11",
     "agent-relay-providers": "0.104.3",
     "agent-relay-sdk": "0.2.106",
     "ajv": "^8.20.0"

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.10",
+  "version": "0.119.11",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/src/routes/index.ts

@@ -45,7 +45,7 @@ import { getRecipeByName, getRecipeInstanceArtifacts, getRecipeInstanceById, get
 import { getSettingRoute, getSettingsNamespaceRoute, getSettingsRoute, putSettingRoute, putSettingsDefaultRoute } from "./settings";
 import { postNotificationPreviewRoute } from "./notifications";
 import { getStewardConfigRoute, getWorkspaceConfigRoute, putStewardConfigRoute, putWorkspaceConfigRoute } from "./steward";
-import { getTaskById, getTaskEntities, getTaskEvents, getTasks, patchTaskStatus, postClaimTask, postRenewTaskClaim, postTaskCreate, getTaskDetailRoute, getTaskMemoryRoute, getTaskHistoryRoute, patchTaskEntity, postTaskEntityStatus, postTaskEntityStage, postTaskEntityGate, postTaskDependency, deleteTaskDependency, postTaskRef, deleteTaskRef, postTaskAssign, postTaskComment, getTaskCloseBridge, postTaskDispatch } from "./tasks";
+import { getTaskById, getTaskEntities, getTaskEvents, getTasks, patchTaskStatus, postClaimTask, postRenewTaskClaim, postTaskCreate, postTaskReconcileAutoScaffolded, getTaskDetailRoute, getTaskMemoryRoute, getTaskHistoryRoute, patchTaskEntity, postTaskEntityStatus, postTaskEntityStage, postTaskEntityGate, postTaskDependency, deleteTaskDependency, postTaskRef, deleteTaskRef, postTaskAssign, postTaskComment, getTaskCloseBridge, postTaskDispatch } from "./tasks";
 import { getMyTeamRoute, getTeamOutcomesRoute, getTeamsRoute, postMyTeamDissolveRoute, putMyTeamBriefRoute } from "./teams";
 import { postTeamDissolveByIdRoute } from "./teams";
 import { deleteTeamTemplateRoute, getTeamTemplateRoute, getTeamTemplatesRoute, postTeamTemplateRoute, putTeamTemplateRoute } from "./team-templates";
@@ -353,6 +353,7 @@ const routes: Route[] = [
   route("GET", "/api/task-entities", getTaskEntities),
   route("GET", "/api/tasks", getTasks),
   route("POST", "/api/tasks", postTaskCreate),
+  route("POST", "/api/tasks/reconcile-auto-scaffolded", postTaskReconcileAutoScaffolded),
   route("GET", "/api/tasks/:id", getTaskById),
   route("GET", "/api/tasks/:id/detail", getTaskDetailRoute),
   route("GET", "/api/tasks/:id/memory", getTaskMemoryRoute),

package/src/routes/tasks.ts

@@ -9,7 +9,7 @@ import { ValidationError, claimTask, getMessage, getTask, listTaskEvents, listTa
 import { readTaskMemoryEnvelope } from "../db/task-memory";
 import {
   addTaskEntityDependency, addTaskEntityRef, assignTaskEntityAgent, createTaskEntity, getTaskEntity,
-  listTaskEntitySummaries, recordTaskEntityGate, removeTaskEntityDependency, removeTaskEntityRef, setTaskEntityStage, setTaskEntityStatus, taskEntityHistory, updateTaskEntity,
+  listTaskEntitySummaries, reconcileAutoScaffoldedTaskReaps, recordTaskEntityGate, removeTaskEntityDependency, removeTaskEntityRef, setTaskEntityStage, setTaskEntityStatus, taskEntityHistory, updateTaskEntity,
 } from "../services/task-entity";
 import { CommentThroughError, commentOnTaskThrough, taskCloseBridge } from "../services/task-issue-weave";
 import { captureTaskResultMemory, injectMemoryForTaskClaim } from "../memory-service";
@@ -86,6 +86,24 @@ export const getTaskEntities: Handler = (req) => {
   }));
 };
 
+export const postTaskReconcileAutoScaffolded: Handler = async (req) => {
+  const parsed = await parseBody<Record<string, unknown>>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const body = parsed.body ?? {};
+  if (!isRecord(body)) return error("JSON object body required");
+  const limit = body.limit === undefined ? undefined : Number(body.limit);
+  if (limit !== undefined && (!Number.isInteger(limit) || limit < 1 || limit > 500)) return error("limit must be an integer between 1 and 500");
+  try {
+    return json(reconcileAutoScaffoldedTaskReaps({
+      dryRun: body.dryRun !== false,
+      limit,
+      actor: actorOf(req),
+    }));
+  } catch (e) {
+    return entityError(e);
+  }
+};
+
 // --- #834 durable Task entity (kind='deliverable') HTTP surface ---
 
 export const postTaskCreate: Handler = async (req) => {

package/src/services/task-done-when.ts

@@ -15,6 +15,7 @@ export function doneWhenTargetStage(doneWhen: string | undefined): TaskDeliverab
 }
 
 export function stageSatisfiesDoneWhen(stage: TaskDeliverableStage, doneWhen: string | undefined): boolean {
+  if (isAgentExitDoneWhen(doneWhen)) return false;
   const current = STAGE_INDEX.get(stage) ?? 0;
   const target = STAGE_INDEX.get(doneWhenTargetStage(doneWhen)) ?? STAGE_INDEX.get("landed-on-main")!;
   return current >= target;

package/src/services/task-entity.ts

@@ -11,9 +11,11 @@ import {
   deliverableTaskIdsBySpawnRequestId,
   getAgent,
   getTaskDetail,
+  listAgents,
   listDeliverableTaskSummaries,
   listDeliverableTasks,
   listTaskEvents,
+  listWorkspaces,
   markTaskAgentReaped,
   recordGate,
   recordTaskDispatchDecision,
@@ -32,8 +34,9 @@ import {
   type SetTaskStatusInput,
   type UpdateDeliverableTaskInput,
 } from "../db";
+import { findSpawnCommandByRequestId } from "../commands-db";
 import { emitTaskChanged } from "../sse";
-import type { Task, TaskDetail, TaskEvent, TaskGateState, TaskListItem } from "../types";
+import type { CommandStatus, Task, TaskDetail, TaskEvent, TaskGateState, TaskListItem, TaskStatus, WorkspaceRecord } from "../types";
 import { removeSubscriptionsForTask } from "../db/notification-subscriptions";
 import { emitRelayEvent } from "../events";
 import { routeNotification } from "../notification-router";
@@ -190,6 +193,146 @@ export function taskEntityHistory(id: number): TaskEvent[] {
   return listTaskEvents(id);
 }
 
+const AUTO_SCAFFOLD_RECONCILE_STATUSES: TaskStatus[] = ["in_progress"];
+const AUTO_SCAFFOLD_RECONCILE_MIN_AGE_MS = 15 * 60_000;
+const SPAWN_IN_FLIGHT_STATUSES: CommandStatus[] = ["pending", "accepted", "running"];
+const SPAWN_TERMINAL_STATUSES: CommandStatus[] = ["succeeded", "failed", "timed_out", "rejected", "canceled"];
+const LANDED_STAGES = new Set(["landed-on-main", "deploying", "deployed"]);
+
+function hasLiveTaskOwner(task: Pick<Task, "ownerAgentId">): boolean {
+  const owner = task.ownerAgentId?.trim();
+  if (!owner) return false;
+  const agent = getAgent(owner);
+  return Boolean(agent && agent.status !== "offline");
+}
+
+function isAutoScaffoldedAgentExitTask(task: Pick<Task, "source" | "doneWhen">): boolean {
+  return task.source === "spawn" && isAgentExitDoneWhen(task.doneWhen);
+}
+
+function latestTaskActivityAt(task: Pick<Task, "createdAt" | "updatedAt" | "lastSeenAt">): number {
+  return Math.max(task.createdAt, task.updatedAt, task.lastSeenAt);
+}
+
+function spawnRequestIdsForTask(taskId: number): string[] {
+  return listTaskEvents(taskId)
+    .filter((event) => event.type === "agent.spawn_requested")
+    .map((event) => typeof event.metadata.spawnRequestId === "string" ? event.metadata.spawnRequestId.trim() : "")
+    .filter(Boolean);
+}
+
+function hasLiveSpawnAgent(spawnRequestId: string): boolean {
+  return listAgents().some((agent) => agent.meta?.spawnRequestId === spawnRequestId && agent.status !== "offline");
+}
+
+function ownerlessSpawnTerminal(taskId: number): { ok: boolean; reason?: string } {
+  const spawnRequestIds = spawnRequestIdsForTask(taskId);
+  if (spawnRequestIds.length === 0) return { ok: false, reason: "ownerless-no-spawn-request" };
+
+  let sawTerminal = false;
+  for (const spawnRequestId of spawnRequestIds) {
+    if (hasLiveSpawnAgent(spawnRequestId)) return { ok: false, reason: "live-spawn-agent" };
+    if (findSpawnCommandByRequestId(spawnRequestId, SPAWN_IN_FLIGHT_STATUSES)) {
+      return { ok: false, reason: "spawn-in-flight" };
+    }
+    if (findSpawnCommandByRequestId(spawnRequestId, SPAWN_TERMINAL_STATUSES)) {
+      sawTerminal = true;
+      continue;
+    }
+    return { ok: false, reason: "spawn-state-unknown" };
+  }
+  return sawTerminal ? { ok: true } : { ok: false, reason: "ownerless-no-spawn-request" };
+}
+
+function workspaceLanded(workspace: WorkspaceRecord): boolean {
+  return workspace.status === "merged" || typeof workspace.metadata.mergedAt === "number";
+}
+
+function landedEvidenceFor(task: Task, workspaces: WorkspaceRecord[]): string | undefined {
+  if (task.deliverableStage && LANDED_STAGES.has(task.deliverableStage)) return `stage:${task.deliverableStage}`;
+  const owner = task.ownerAgentId?.trim();
+  const branch = task.branch?.trim();
+  const workspace = workspaces.find((ws) => workspaceLanded(ws) && (
+    (owner && ws.ownerAgentId === owner) ||
+    (branch && ws.branch === branch)
+  ));
+  if (!workspace) return undefined;
+  return `workspace:${workspace.id}:${workspace.status}`;
+}
+
+function candidateAutoScaffoldedTasks(limit: number): Task[] {
+  const byId = new Map<number, Task>();
+  for (const status of AUTO_SCAFFOLD_RECONCILE_STATUSES) {
+    for (const task of listDeliverableTasks({ status, limit })) {
+      if (isAutoScaffoldedAgentExitTask(task)) byId.set(task.id, task);
+    }
+  }
+  return [...byId.values()].sort((a, b) => a.id - b.id);
+}
+
+export interface ReconcileAutoScaffoldedTaskReapsOptions {
+  dryRun?: boolean;
+  limit?: number;
+  actor?: string;
+  now?: number;
+  minAgeMs?: number;
+}
+
+export interface ReconcileAutoScaffoldedTaskReapsResult {
+  dryRun: boolean;
+  scanned: number;
+  completed: number[];
+  canceled: number[];
+  skipped: Array<{ taskId: number; reason: string }>;
+}
+
+export function reconcileAutoScaffoldedTaskReaps(opts: ReconcileAutoScaffoldedTaskReapsOptions = {}): ReconcileAutoScaffoldedTaskReapsResult {
+  const dryRun = opts.dryRun !== false;
+  const limit = Math.min(Math.max(opts.limit ?? 500, 1), 500);
+  const workspaces = listWorkspaces();
+  const completed: number[] = [];
+  const canceled: number[] = [];
+  const skipped: Array<{ taskId: number; reason: string }> = [];
+  const actor = opts.actor ?? "task-reconcile";
+  const now = opts.now ?? Date.now();
+  const minAgeMs = Math.max(opts.minAgeMs ?? AUTO_SCAFFOLD_RECONCILE_MIN_AGE_MS, 0);
+
+  for (const task of candidateAutoScaffoldedTasks(limit)) {
+    if (latestTaskActivityAt(task) > now - minAgeMs) {
+      skipped.push({ taskId: task.id, reason: "recent-task" });
+      continue;
+    }
+    if (hasLiveTaskOwner(task)) {
+      skipped.push({ taskId: task.id, reason: "live-owner" });
+      continue;
+    }
+    if (!task.ownerAgentId?.trim()) {
+      const ownerless = ownerlessSpawnTerminal(task.id);
+      if (!ownerless.ok) {
+        skipped.push({ taskId: task.id, reason: ownerless.reason ?? "ownerless-spawn-active" });
+        continue;
+      }
+    }
+    const landedEvidence = landedEvidenceFor(task, workspaces);
+    const status = landedEvidence ? "done" : "canceled";
+    if (!dryRun) {
+      if (task.ownerAgentId && !task.reapedAt) {
+        markTaskAgentReaped(task.id, { agentId: task.ownerAgentId, reason: landedEvidence ? "reconciled-landed-worker" : "reconciled-reaped-without-land" });
+      }
+      setTaskEntityStatus(task.id, {
+        status,
+        note: landedEvidence
+          ? `auto-scaffolded worker already landed (${landedEvidence}); reconciled doneWhen=agent-exit`
+          : "auto-scaffolded worker is no longer live and no landed workspace evidence was found; canceled",
+        actor,
+      });
+    }
+    (status === "done" ? completed : canceled).push(task.id);
+  }
+
+  return { dryRun, scanned: completed.length + canceled.length + skipped.length, completed, canceled, skipped };
+}
+
 // #889 — finalize bound tasks for a reaped agent whose doneWhen is "agent-exit" / "reaped".
 // Called by the transient reaper after requesting shutdown so ephemeral run-and-exit workers
 // don't leave their auto-scaffolded Task stuck in_progress forever.
@@ -208,8 +351,10 @@ export function finalizeEphemeralTasksOnReap(agentId: string, opts: { spawnReque
     if (!isAgentExitDoneWhen(task.doneWhen)) continue;
     if (opts.producedWork === false) {
       try {
-        setTaskEntityStatus(taskId, { status: "open", note: "worker reaped without producing work; task reopened for retry", actor: "task-lifecycle" });
+        if (!task.reapedAt) markTaskAgentReaped(taskId, { agentId, reason: opts.reason ?? "agent-exit" });
+        setTaskEntityStatus(taskId, { status: "canceled", note: "worker reaped without landing or producing work; task canceled", actor: "task-lifecycle" });
         notifyEmptyTransientReap(agentId, task, opts);
+        finalized.push(taskId);
       } catch {
         // best-effort; failures must not surface into the reaper scan
       }
@@ -247,7 +392,7 @@ function notifyEmptyTransientReap(agentId: string, task: TaskDetail, opts: { spa
     recipients,
     message: {
       subject: "Worker reaped without producing work",
-      body: `Worker \`${agentId}\` was reaped without producing work for Task #${task.id} (${task.title}). The task was reopened for retry instead of being marked done.`,
+      body: `Worker \`${agentId}\` was reaped without producing work for Task #${task.id} (${task.title}). The task was canceled instead of being marked done.`,
       payload,
       idempotencyKey: `task:${task.id}:empty-reap:${agentId}:${opts.reason ?? "agent-exit"}`,
       replyExpected: false,

package/src/services/task-lifecycle.ts

@@ -30,13 +30,13 @@ import {
   getTaskDetail,
   markTaskAgentReaped,
 } from "../db";
-import { setTaskEntityStage } from "./task-entity";
+import { setTaskEntityStage, setTaskEntityStatus } from "./task-entity";
 import { postTaskMilestoneComment, taskCloseBridge, type TaskCloseBridgeEntry } from "./task-issue-weave";
 import { requestTransientAgentShutdown } from "./transient-agent-reaper";
 import { emitRelayEvent } from "../events";
 import { routeNotification } from "../notification-router";
 import { resolveCoordinatorAgentId } from "../steward-identity";
-import { stageSatisfiesDoneWhen } from "./task-done-when";
+import { isAgentExitDoneWhen, stageSatisfiesDoneWhen } from "./task-done-when";
 import { emitTaskSemanticNotification, type TaskSemanticTransition } from "./task-semantic-events";
 import type { IssueRef, TaskDeliverableStage, TaskGateState, WorkspaceRecord } from "../types";
 import type { IssueTrackerAdapter } from "../issue-tracker";
@@ -253,6 +253,16 @@ function finalizeReap(outcomes: TaskLandOutcome[], reap: ReapResult, log: LogFn)
     if (reap.reaped && reap.agentId) {
       try {
         markTaskAgentReaped(outcome.taskId, { agentId: reap.agentId, reason: "deliverable-landed" });
+        const task = getTaskDetail(outcome.taskId);
+        if (task && task.status !== "done" && isAgentExitDoneWhen(task.doneWhen)) {
+          setTaskEntityStatus(outcome.taskId, {
+            status: "done",
+            note: "doneWhen=agent-exit satisfied by worker reap after land",
+            actor: "task-lifecycle",
+          });
+          outcome.doneWhenSatisfied = true;
+          outcome.statusAdvanced = true;
+        }
       } catch (error) {
         log(`task reap marker failed for task ${outcome.taskId}: ${errMessage(error)}`);
       }