agent-relay-server 0.126.0 → 0.127.1

package/src/mcp/tools-workspace.ts

@@ -15,33 +15,19 @@ import { optionalBoolean, optionalPositiveInt, optionalString } from "./validati
 export const WORKSPACE_TOOLS: ToolDefinition[] = [
   {
     name: "relay_workspace_status",
-    description: "Get your isolated workspace's lifecycle status (active/ready/conflict/review_requested/merged/...). With wait:true this BLOCKS until the status changes; do not use wait:true after relay_workspace_ready unless explicitly debugging. Normal branch workers mark ready, stop their turn, and are woken later by landed-success or landed-failure notifications. Defaults to your own workspace; pass workspaceId to target another.",
+    description: "Get your isolated workspace's lifecycle status (active/ready/conflict/review_requested/merged/...). With wait:true this BLOCKS until the status changes; do not use wait:true after relay_task_deliver unless explicitly debugging. Normal branch workers deliver the Task, stop their turn, and are woken later by landed-success or landed-failure notifications. Defaults to your own workspace; pass workspaceId to target another.",
     requiredScopes: ["agents:read", "agent:read", "agent:write"],
     alwaysLoad: true,
     inputSchema: {
       type: "object",
       properties: {
         workspaceId: { type: "string", description: "Defaults to your own isolated workspace (resolved from your identity)." },
-        wait: { type: "boolean", description: "Block until the workspace status changes (the actionable signal), or until the timeout. Do not use this after relay_workspace_ready in the normal worker flow; stop and wait for landed-success/landed-failure instead." },
+        wait: { type: "boolean", description: "Block until the workspace status changes (the actionable signal), or until the timeout. Do not use this after relay_task_deliver in the normal worker flow; stop and wait for landed-success/landed-failure instead." },
         timeoutSeconds: { type: "integer", minimum: 1, maximum: 600, description: "Max seconds to wait when wait:true (default 300, max 600). Returns early on any transition." },
       },
       additionalProperties: false,
     },
   },
-  {
-    name: "relay_workspace_ready",
-    description: "Signal that your branch work is finished and ready to merge back to main. This kicks off the auto-merge-back: a clean merge lands immediately; on conflict a steward agent reconciles and lands it (escalating if it can't). After this tool returns, stop your turn and go idle; Relay wakes you later with landed-success when the merge lands and your branch refreshes, or landed-failure if landing fatally fails. Defaults to your own workspace.",
-    requiredScopes: ["agent:write"],
-    alwaysLoad: true,
-    inputSchema: {
-      type: "object",
-      properties: {
-        workspaceId: { type: "string", description: "Defaults to your own isolated workspace." },
-        detail: { type: "string", description: "Optional note recorded on the activity feed." },
-      },
-      additionalProperties: false,
-    },
-  },
   {
     name: "relay_workspace_deps",
     description: "Re-provision your worktree's dependencies when the shared symlinked node_modules has gone stale (e.g. typecheck reports a missing module). checkOnly:true just reports staleness without changing anything. Self-service — acts only on your own worktree.",
@@ -98,25 +84,6 @@ export const WORKSPACE_TOOLS: ToolDefinition[] = [
       additionalProperties: false,
     },
   },
-  {
-    name: "relay_workspace_land",
-    description: "Dispatch a base merge for your workspace directly (lease-serialized per repo, same path the auto-merge job uses). Most branch agents should use relay_workspace_ready instead and let the relay land it; this is the explicit/steward path and requires the command:write scope.",
-    requiredScopes: ["command:write"],
-    inputSchema: {
-      type: "object",
-      properties: {
-        workspaceId: { type: "string", description: "Defaults to your own isolated workspace." },
-        strategy: { type: "string", enum: ["pr", "rebase-ff", "auto"], description: "Merge strategy (default auto). Falls back to the instance landing.strategy config when unset." },
-        deleteBranch: { type: "boolean", description: "Delete the branch after a successful merge (default true)." },
-        prTitle: { type: "string" },
-        prBody: { type: "string" },
-        autoMerge: { type: "string", enum: AUTO_MERGE_POLICIES, description: "Auto-merge policy for PR-strategy lands. Defaults to 'on-green' when strategy resolves to 'pr'. Ignored for rebase-ff/auto strategies." },
-        reviewer: { type: "string", description: "GitHub login or team slug to request as a reviewer on the opened PR (pr strategy only)." },
-        detail: { type: "string" },
-      },
-      additionalProperties: false,
-    },
-  },
 ];
 
 function isWorkspaceAdmin(auth: McpAuthContext): boolean {
@@ -219,7 +186,7 @@ export async function relayWorkspaceMutation(auth: McpAuthContext, action: Works
   if (action === "ready") {
     payload.contract = readyContract(result.workspace);
     payload.guidance = describeWorkspacePhase(result.workspace);
-    // #1084 — relay_workspace_ready is an explicit, platform-owned completion signal: the caller
+    // Legacy workspace-ready route/CLI path is an explicit, platform-owned completion signal: the caller
     // is declaring its work window closed. Close it, forwarding only the held final group.
     markAgentWorkFinal(result.workspace.ownerAgentId ?? callerAgentId(auth), "workspace-ready");
   }

package/src/mcp-task-deliver-tools.ts

@@ -0,0 +1,143 @@
+import { McpAuthError } from "./mcp-errors";
+import { ValidationError } from "./db";
+import { authContextFromMcp } from "./services/auth-context";
+import { deliverTask } from "./services/task-delivery";
+import { ServiceAuthError } from "./services/errors";
+import { cleanString, optionalEnum } from "./validation";
+import {
+  TASK_DELIVERY_DISPOSITIONS,
+  TASK_BLOCKER_TYPES,
+  TASK_GATE_STATUSES,
+  isRecord,
+  type TaskDeliveryGateReports,
+  type TaskDeliveryResult,
+} from "./types";
+
+const TASK_ID_PROP = { oneOf: [{ type: "integer", minimum: 1 }, { type: "string" }], description: "Task id. Optional when the caller is bound to exactly one Task." } as const;
+const COMMIT_SCHEMA = {
+  type: "object",
+  properties: { sha: { type: "string" }, subject: { type: "string" } },
+  required: ["sha"],
+  additionalProperties: false,
+} as const;
+const GATE_RESULT_SCHEMA = {
+  type: "object",
+  properties: {
+    status: { type: "string", enum: TASK_GATE_STATUSES },
+    detail: { type: "string" },
+    count: { type: "integer", minimum: 0 },
+    runId: { type: "string" },
+  },
+  required: ["status"],
+  additionalProperties: false,
+} as const;
+
+export const TASK_DELIVER_TOOLS = [
+  {
+    name: "relay_task_deliver",
+    description: "Submit a structured Delivery Result for a durable Task. Writes a typed deliverable event to the Task thread before any side effect. disposition:'complete' requires passing typecheck+test gates and auto-triggers the caller's task-bound isolated workspace handoff to land.",
+    requiredScopes: ["task:write"],
+    alwaysLoad: true,
+    inputSchema: {
+      type: "object",
+      properties: {
+        taskId: TASK_ID_PROP,
+        disposition: { type: "string", enum: TASK_DELIVERY_DISPOSITIONS },
+        summary: { type: "string" },
+        reason: { type: "string", description: "Required for blocked/failed deliveries." },
+        blockedBy: {
+          type: "array",
+          description: "Required for blocked deliveries; records the blocker set on the Task.",
+          items: {
+            type: "object",
+            properties: { type: { type: "string", enum: TASK_BLOCKER_TYPES }, ref: { type: "string" }, note: { type: "string" } },
+            required: ["type"],
+            additionalProperties: false,
+          },
+        },
+        commits: { type: "array", items: COMMIT_SCHEMA },
+        gates: {
+          type: "object",
+          properties: {
+            typecheck: GATE_RESULT_SCHEMA,
+            test: GATE_RESULT_SCHEMA,
+            other: {
+              type: "array",
+              items: {
+                type: "object",
+                properties: { name: { type: "string" }, status: { type: "string", enum: TASK_GATE_STATUSES }, detail: { type: "string" }, count: { type: "integer", minimum: 0 }, runId: { type: "string" } },
+                required: ["name", "status"],
+                additionalProperties: false,
+              },
+            },
+          },
+          additionalProperties: false,
+        },
+        filesChanged: { type: "integer", minimum: 0 },
+        rca: { type: "string" },
+        testCoverage: { type: "string" },
+        risks: { type: "array", items: { type: "string" } },
+        selfAcceptance: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: { criterion: { type: "string" }, status: { type: "string", enum: ["met", "unmet"] }, note: { type: "string" } },
+            required: ["criterion", "status"],
+            additionalProperties: false,
+          },
+        },
+        workspaceId: { type: "string", description: "Defaults to the caller's isolated workspace." },
+        idempotencyKey: { type: "string", description: "Dedupes retry delivery and prevents double-land on replay." },
+      },
+      required: ["disposition", "summary"],
+      additionalProperties: false,
+    },
+  },
+] satisfies Array<{ name: string; description: string; requiredScopes: string[]; inputSchema: Record<string, unknown>; alwaysLoad?: boolean }>;
+
+type McpAuthLike = Parameters<typeof authContextFromMcp>[0];
+
+function optionalPositiveInt(value: unknown, field: string): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  const n = typeof value === "string" ? Number(value) : value;
+  if (typeof n !== "number" || !Number.isSafeInteger(n) || n < 1) throw new ValidationError(`${field} must be a positive integer`);
+  return n;
+}
+
+function cleanDeliveryGates(value: unknown): TaskDeliveryGateReports | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (!isRecord(value)) throw new ValidationError("gates must be an object");
+  return value as TaskDeliveryGateReports;
+}
+
+function cleanDeliveryResult(args: Record<string, unknown>): TaskDeliveryResult {
+  return {
+    disposition: optionalEnum(args.disposition, "disposition", TASK_DELIVERY_DISPOSITIONS)!,
+    summary: cleanString(args.summary, "summary", { required: true, max: 1_000_000 })!,
+    ...(args.reason !== undefined ? { reason: cleanString(args.reason, "reason", { max: 64_000 }) } : {}),
+    ...(Array.isArray(args.blockedBy) ? { blockedBy: args.blockedBy as TaskDeliveryResult["blockedBy"] } : {}),
+    ...(Array.isArray(args.commits) ? { commits: args.commits as TaskDeliveryResult["commits"] } : {}),
+    ...(args.gates !== undefined ? { gates: cleanDeliveryGates(args.gates) } : {}),
+    ...(typeof args.filesChanged === "number" ? { filesChanged: args.filesChanged } : {}),
+    ...(args.rca !== undefined ? { rca: cleanString(args.rca, "rca", { max: 64_000 }) } : {}),
+    ...(args.testCoverage !== undefined ? { testCoverage: cleanString(args.testCoverage, "testCoverage", { max: 64_000 }) } : {}),
+    ...(Array.isArray(args.risks) ? { risks: args.risks.filter((risk): risk is string => typeof risk === "string") } : {}),
+    ...(Array.isArray(args.selfAcceptance) ? { selfAcceptance: args.selfAcceptance as TaskDeliveryResult["selfAcceptance"] } : {}),
+  };
+}
+
+export async function relayTaskDeliverTool(auth: McpAuthLike, name: string, args: Record<string, unknown>): Promise<Record<string, unknown>> {
+  if (name !== "relay_task_deliver") throw new ValidationError(`unknown tool: ${name}`);
+  if (!isRecord(args)) throw new ValidationError("arguments must be an object");
+  try {
+    return await deliverTask({
+      ...cleanDeliveryResult(args),
+      taskId: optionalPositiveInt(args.taskId, "taskId"),
+      workspaceId: cleanString(args.workspaceId, "workspaceId", { max: 240 }),
+      idempotencyKey: cleanString(args.idempotencyKey, "idempotencyKey", { max: 240 }),
+    }, authContextFromMcp(auth));
+  } catch (error) {
+    if (error instanceof ServiceAuthError) throw new McpAuthError(error.message);
+    throw error;
+  }
+}

package/src/notification-rules.ts

@@ -274,6 +274,7 @@ registerDefaultAudienceRules("message.new", [
 ]);
 
 for (const type of [
+  "task.deliverable",
   "task.created",
   "task.started",
   "task.blocked",

package/src/notification-types.ts

@@ -2,6 +2,7 @@ export type NotificationType =
   | "message.new"
   | "landed-failure"
   | "branch.landed"
+  | "task.deliverable"
   | "task.deliverable_landed"
   | "task.created"
   | "task.started"
@@ -99,6 +100,7 @@ export const DEFAULT_TTL_MS: Record<NotificationType, number | null> = {
   "message.new": null,
   "landed-failure": null,
   "branch.landed": null,
+  "task.deliverable": null,
   // The #831 auto-driven "task deliverable landed" receipt to the coordinator. Durable (null):
   // it carries the auto-actions the coordinator confirms/exception-handles, so it must survive
   // the coordinator being briefly offline rather than expiring as an ephemeral bystander ping.

package/src/prompt-resolver.ts

@@ -289,7 +289,7 @@ const DEFAULT_PROMPT_TEMPLATES = [
     template: lines(
       "You are in an isolated git worktree on branch {{branch}}, based on {{baseRef}} — NOT the main checkout. {{baseRef}} moves under you as other agents land in parallel; that's expected.",
       "Your shell's working directory is already this worktree — run commands directly without prefixing `cd`.",
-      "Changes reach the base via: commit your work, then call `relay_workspace_ready`. Relay rebases onto the latest base, lands, and pushes for you.",
+      "Changes reach the base via: commit your work, then call `relay_task_deliver` with disposition `complete`, a summary, commits, and passing `typecheck` + `test` gates. Relay records the typed delivery on the Task, then rebases onto the latest base, lands, and pushes for you.",
       "Do NOT push, rebase, merge, resolve conflicts, or `cd` into the main checkout — Relay (and a steward, spawned only if a clean auto-merge isn't possible) own all of that.",
       "After `ready` the status is `ready` (a normal, healthy hand-off state, not a stall). Stop your turn and go idle; Relay wakes you with `landed-success` when your branch lands and refreshes, or `landed-failure` if landing fatally fails.",
       "Call `relay_workspace_status` anytime to see where you are and the exact next step.",
@@ -297,7 +297,7 @@ const DEFAULT_PROMPT_TEMPLATES = [
     defaultTemplate: lines(
       "You are in an isolated git worktree on branch {{branch}}, based on {{baseRef}} — NOT the main checkout. {{baseRef}} moves under you as other agents land in parallel; that's expected.",
       "Your shell's working directory is already this worktree — run commands directly without prefixing `cd`.",
-      "Changes reach the base via: commit your work, then call `relay_workspace_ready`. Relay rebases onto the latest base, lands, and pushes for you.",
+      "Changes reach the base via: commit your work, then call `relay_task_deliver` with disposition `complete`, a summary, commits, and passing `typecheck` + `test` gates. Relay records the typed delivery on the Task, then rebases onto the latest base, lands, and pushes for you.",
       "Do NOT push, rebase, merge, resolve conflicts, or `cd` into the main checkout — Relay (and a steward, spawned only if a clean auto-merge isn't possible) own all of that.",
       "After `ready` the status is `ready` (a normal, healthy hand-off state, not a stall). Stop your turn and go idle; Relay wakes you with `landed-success` when your branch lands and refreshes, or `landed-failure` if landing fatally fails.",
       "Call `relay_workspace_status` anytime to see where you are and the exact next step.",
@@ -423,8 +423,8 @@ const DEFAULT_PROMPT_TEMPLATES = [
     category: "workspace-phase",
     title: "Workspace Active Hint",
     description: "Workspace status hint for active isolated work.",
-    template: "Commit your work in this worktree, then mark it ready. Relay rebases onto the latest base, lands, and pushes for you — do NOT push, rebase, or merge yourself, and never touch the main checkout.",
-    defaultTemplate: "Commit your work in this worktree, then mark it ready. Relay rebases onto the latest base, lands, and pushes for you — do NOT push, rebase, or merge yourself, and never touch the main checkout.",
+    template: "Commit your work in this worktree, then deliver the Task with `relay_task_deliver` using disposition `complete` and passing `typecheck` + `test` gates. Relay records the typed delivery, lands the branch, and pushes for you — do NOT push, rebase, or merge yourself, and never touch the main checkout.",
+    defaultTemplate: "Commit your work in this worktree, then deliver the Task with `relay_task_deliver` using disposition `complete` and passing `typecheck` + `test` gates. Relay records the typed delivery, lands the branch, and pushes for you — do NOT push, rebase, or merge yourself, and never touch the main checkout.",
     variables: [],
   },
   {
@@ -432,8 +432,8 @@ const DEFAULT_PROMPT_TEMPLATES = [
     category: "workspace-phase",
     title: "Workspace Ready Headline",
     description: "Workspace status headline for healthy handoff states.",
-    template: "Handed off — stop this turn and go idle while Relay lands your branch. This is the normal, healthy post-ready state (not an escalation).",
-    defaultTemplate: "Handed off — stop this turn and go idle while Relay lands your branch. This is the normal, healthy post-ready state (not an escalation).",
+    template: "Delivered — stop this turn and go idle while Relay lands your branch. This is the normal, healthy post-delivery state (not an escalation).",
+    defaultTemplate: "Delivered — stop this turn and go idle while Relay lands your branch. This is the normal, healthy post-delivery state (not an escalation).",
     variables: [],
   },
   {

package/src/routes/agent-sessions.ts

@@ -614,7 +614,10 @@ export const postAgentTerminalSession: Handler = async (req, params) => {
       resource: { agentId: agent.id, orchestratorId: orchestrator.id, policyName: metaPolicyName, spawnRequestId: metaSpawnRequestId, terminalAttach: true },
     });
     if (denied) return denied;
-    if (agent.providerCapabilities?.terminal?.live?.read && metaTmuxSession) {
+    // Provider-owned attach surfaces are more specific than the runner's tmux pane.
+    // Codex runs its real interactive TUI as a guest attached to the app-server thread;
+    // the runner pane can be a stale launcher frame and is not the right input target.
+    if (agent.providerCapabilities?.terminal?.attach?.create !== true && agent.providerCapabilities?.terminal?.live?.read && metaTmuxSession) {
       return json({
         mode: "live",
         orchestratorId: orchestrator.id,

package/src/routes/agents.ts

@@ -216,6 +216,9 @@ export const postHeartbeat: Handler = async (req, params) => {
     if (!session.ok) return error(session.error!, agentSessionStatus(session.error));
     // #416 — capture unavailability before heartbeat to detect the transition.
     const beforeHeartbeat = getAgent(params.id!);
+    if (beforeHeartbeat?.kind === "channel" && !beforeHeartbeat.ready) {
+      return error("channel agent not ready; re-register required", 409);
+    }
     const wasUnavailable = beforeHeartbeat ? isAgentUnavailable(beforeHeartbeat) : false;
     if (!heartbeat(params.id!, guard)) return error("agent not found", 404);
     if (wasUnavailable) {

package/src/services/task-delivery.ts

@@ -0,0 +1,275 @@
+import {
+  getTaskDetail,
+  getWorkspace,
+  insertTaskEvent,
+  listTaskEvents,
+  ownedIsolatedWorkspace,
+  recordGate,
+  recordTaskDeliverable,
+  setTaskStatus,
+  ValidationError,
+} from "../db";
+import { emitRelayEvent } from "../events";
+import { routeNotification } from "../notification-router";
+import { emitTaskChanged, emitNewMessages } from "../sse";
+import { agentBoundTaskIds, hasTaskReadAdminScope } from "../task-authz";
+import { applyWorkspaceAction } from "../workspace-actions";
+import { emitTaskSemanticNotification } from "./task-semantic-events";
+import { ServiceAuthError } from "./errors";
+import { resolveCoordinatorAgentId } from "../steward-identity";
+import { markAgentWorkFinal } from "./work-finality";
+import type { AuthContext } from "./auth-context";
+import type { Command, TaskBlocker, TaskDeliverableEventMetadata, TaskDeliveryGateReports, TaskDeliveryResult, TaskGateStatus, TaskDetail, WorkspaceRecord } from "../types";
+
+const REQUIRED_COMPLETE_GATES = ["typecheck", "test"] as const;
+
+export interface DeliverTaskInput extends TaskDeliveryResult {
+  taskId?: number;
+  workspaceId?: string;
+  idempotencyKey?: string;
+}
+
+interface GateWrite {
+  gate: string;
+  status: TaskGateStatus;
+  detail?: string;
+  count?: number;
+  runId?: string;
+}
+
+function callerLabel(ctx: AuthContext): string {
+  return ctx.callerAgentId ?? ctx.actor.id;
+}
+
+function taskIdFrom(value: unknown): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  const n = typeof value === "string" ? Number(value) : value;
+  if (typeof n !== "number" || !Number.isSafeInteger(n) || n < 1) throw new ValidationError("taskId must be a positive integer");
+  return n;
+}
+
+function resolveTaskId(ctx: AuthContext, explicit: unknown): number {
+  const taskId = taskIdFrom(explicit);
+  const caller = ctx.callerAgentId;
+  const bound = caller ? agentBoundTaskIds(caller) : new Set<number>();
+  const admin = hasTaskReadAdminScope(ctx.scopes);
+  if (taskId !== undefined) {
+    if (admin || bound.has(taskId)) return taskId;
+    throw new ServiceAuthError("taskId is not bound to the caller");
+  }
+  if (bound.size === 1) return [...bound][0]!;
+  if (bound.size === 0) throw new ServiceAuthError("caller is not bound to a Task");
+  throw new ValidationError("caller is bound to multiple Tasks; pass taskId explicitly");
+}
+
+function resolveWorkspace(ctx: AuthContext, input: { workspaceId?: string }, taskId: number): WorkspaceRecord | undefined {
+  const caller = ctx.callerAgentId;
+  const explicit = input.workspaceId?.trim();
+  const ws = explicit ? getWorkspace(explicit) : caller ? ownedIsolatedWorkspace(caller) : undefined;
+  if (!ws) return undefined;
+  if (!hasTaskReadAdminScope(ctx.scopes) && (!caller || ws.ownerAgentId !== caller)) {
+    throw new ServiceAuthError(`workspace ${ws.id} is not owned by the caller`);
+  }
+  const task = getTaskDetail(taskId);
+  if (!task) throw new ValidationError("task not found");
+  if (task.branch && ws.branch && task.branch !== ws.branch) {
+    throw new ValidationError(`task ${taskId} is bound to branch ${task.branch}, not workspace branch ${ws.branch}`);
+  }
+  return ws;
+}
+
+function gateWrites(gates: TaskDeliveryGateReports | undefined, deliveryKey: string): GateWrite[] {
+  const writes: GateWrite[] = [];
+  if (gates?.typecheck) writes.push({ gate: "typecheck", ...gatePayload(gates.typecheck, `${deliveryKey}:typecheck`) });
+  if (gates?.test) writes.push({ gate: "test", ...gatePayload(gates.test, `${deliveryKey}:test`) });
+  for (const gate of gates?.other ?? []) {
+    writes.push({ gate: gate.name, ...gatePayload(gate, `${deliveryKey}:other:${gate.name}`) });
+  }
+  return writes;
+}
+
+function gatePayload(input: { status: TaskGateStatus; detail?: string; count?: number; runId?: string }, fallbackRunId: string): Omit<GateWrite, "gate"> {
+  return {
+    status: input.status,
+    ...(input.detail ? { detail: input.detail } : {}),
+    ...(typeof input.count === "number" ? { count: input.count } : {}),
+    runId: input.runId ?? fallbackRunId,
+  };
+}
+
+function normalizedDoneWhen(task: TaskDetail): string {
+  return (task.doneWhen ?? "").toLowerCase();
+}
+
+function completeDeliveryLands(task: TaskDetail): boolean {
+  const dispatchType = task.dispatch?.type;
+  if (dispatchType === "review" || dispatchType === "research" || dispatchType === "ops") return false;
+  const acceptance = normalizedDoneWhen(task);
+  if (/\b(no[-\s]?branch|review(?:ed)?|verdict|report[-\s]?only|none)\b/.test(acceptance)) return false;
+  if (/\b(merged?|landed(?:-on-main)?|live[-\s]?verified|deployed|agent[-\s]?exit|reaped)\b/.test(acceptance)) return true;
+  return true;
+}
+
+function cleanReason(value: unknown, disposition: "blocked" | "failed"): string {
+  if (typeof value !== "string" || !value.trim()) throw new ValidationError(`${disposition} delivery requires reason`);
+  const cleaned = value.trim();
+  if (cleaned.length > 64_000) throw new ValidationError("reason must be 64000 characters or fewer");
+  return cleaned;
+}
+
+function cleanBlockedBy(value: unknown): TaskBlocker[] {
+  if (!Array.isArray(value) || value.length === 0) throw new ValidationError("blocked delivery requires blockedBy");
+  return value as TaskBlocker[];
+}
+
+function completeGateProblem(gates: TaskDeliveryGateReports | undefined): string | undefined {
+  if (!gates) return "missing-gate-block";
+  const writes = gateWrites(gates, "check");
+  const byName = new Map(writes.map((gate) => [gate.gate, gate.status]));
+  const missing = REQUIRED_COMPLETE_GATES.filter((gate) => !byName.has(gate));
+  if (missing.length > 0) return `missing-gates:${missing.join("+")}`;
+  const failed = writes.filter((gate) => gate.status !== "pass").map((gate) => gate.gate);
+  if (failed.length > 0) return `failed-gates:${failed.join("+")}`;
+  return undefined;
+}
+
+function deliveryEvent(taskId: number, idempotencyKey: string | undefined): { id: number; metadata: TaskDeliverableEventMetadata } | undefined {
+  const events = listTaskEvents(taskId).filter((event) => event.type === "deliverable").reverse();
+  const event = idempotencyKey
+    ? events.find((item) => item.metadata.idempotencyKey === idempotencyKey)
+    : events[0];
+  if (!event) return undefined;
+  return { id: event.id, metadata: event.metadata as unknown as TaskDeliverableEventMetadata };
+}
+
+function notifyDelivery(taskId: number, eventId: number, metadata: TaskDeliverableEventMetadata): void {
+  const task = getTaskDetail(taskId);
+  if (!task) return;
+  emitRelayEvent({
+    type: "task.deliverable",
+    source: metadata.actor,
+    subject: String(taskId),
+    data: { taskId, eventId, disposition: metadata.disposition, summary: metadata.summary, workspaceId: metadata.workspaceId },
+  });
+  const coordinator = resolveCoordinatorAgentId(task.ownerAgentId ?? metadata.actor);
+  const recipients = [...new Set([coordinator, task.createdBy].filter((item): item is string => Boolean(item && item.trim())))];
+  const delivered = routeNotification({
+    type: "task.deliverable",
+    scope: {
+      taskId: String(taskId),
+      transition: "deliverable",
+      ...(task.ownerAgentId ? { agentId: task.ownerAgentId, author: task.ownerAgentId } : {}),
+      ...(task.createdBy ? { parent: task.createdBy } : {}),
+      ...(task.teamId ? { teamId: task.teamId } : {}),
+      ...(metadata.workspaceId ? { workspaceId: metadata.workspaceId } : {}),
+    },
+    recipients,
+    ttlMs: null,
+    message: {
+      subject: `Task T${taskId} delivery: ${metadata.disposition}`,
+      body: `Task T${taskId} delivery (${metadata.disposition}): ${metadata.summary}`,
+      payload: {
+        kind: "task.deliverable",
+        notification: "task-deliverable",
+        taskId,
+        eventId,
+        disposition: metadata.disposition,
+        summary: metadata.summary,
+        gates: metadata.gates,
+        risks: metadata.risks,
+        workspaceId: metadata.workspaceId,
+      },
+      idempotencyKey: metadata.idempotencyKey ? `task:${taskId}:deliverable:${metadata.idempotencyKey}` : `task:${taskId}:deliverable:event:${eventId}`,
+      replyExpected: false,
+    },
+  });
+  if (delivered.length > 0) emitNewMessages(delivered);
+}
+
+function emitCommand(command: Command): void {
+  emitRelayEvent({
+    type: command.status === "pending" ? "command.requested" : `command.${command.status}`,
+    source: command.source,
+    subject: command.id,
+    data: { command },
+  });
+}
+
+export async function deliverTask(input: DeliverTaskInput, ctx: AuthContext): Promise<Record<string, unknown>> {
+  const actor = callerLabel(ctx);
+  const taskId = resolveTaskId(ctx, input.taskId);
+  const before = getTaskDetail(taskId);
+  if (!before) throw new ValidationError("task not found");
+  if (before.kind !== "deliverable") throw new ValidationError("task not found");
+  const wantsLand = input.disposition === "complete" && completeDeliveryLands(before);
+  const isVerdictOnlyComplete = input.disposition === "complete" && !wantsLand;
+  const gateProblem = input.disposition === "complete" ? completeGateProblem(input.gates) : undefined;
+  if (gateProblem) throw new ValidationError(`complete delivery cannot land without passing gate block (${gateProblem})`);
+  const reason = input.disposition === "blocked" || input.disposition === "failed" ? cleanReason(input.reason, input.disposition) : undefined;
+  const blockedBy = input.disposition === "blocked" ? cleanBlockedBy(input.blockedBy) : input.blockedBy;
+  const workspace = wantsLand || input.workspaceId ? resolveWorkspace(ctx, input, taskId) : undefined;
+  if (wantsLand && (!workspace || workspace.mode !== "isolated" || !workspace.worktreePath)) {
+    throw new ValidationError("complete delivery requires a live isolated workspace");
+  }
+  const landMeta: TaskDeliverableEventMetadata["land"] | undefined = wantsLand && workspace
+    ? { requested: true, triggered: false, reason: "pending", workspaceId: workspace.id, workspaceStatus: workspace.status }
+    : undefined;
+  const delivery = recordTaskDeliverable(taskId, {
+    ...input,
+    actor,
+    ...(reason ? { reason } : {}),
+    ...(blockedBy ? { blockedBy } : {}),
+    ...(workspace ? { workspaceId: workspace.id } : {}),
+    ...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
+    ...(landMeta ? { land: landMeta } : {}),
+  });
+  const eventMeta = deliveryEvent(taskId, input.idempotencyKey)?.metadata;
+  if (delivery.created) {
+    const deliveryKey = input.idempotencyKey ?? `event:${delivery.event.id}`;
+    for (const gate of gateWrites(input.gates, deliveryKey)) {
+      recordGate(taskId, { ...gate, actor });
+    }
+    if (input.disposition === "blocked") {
+      setTaskStatus(taskId, { status: "blocked", blockedBy: blockedBy as TaskBlocker[], note: reason, actor });
+    } else if (input.disposition === "failed") {
+      setTaskStatus(taskId, { status: "failed", note: reason, actor });
+    } else if (isVerdictOnlyComplete) {
+      setTaskStatus(taskId, { status: "done", note: "complete delivery recorded without land", actor });
+    }
+    const detail = getTaskDetail(taskId);
+    if (detail) {
+      emitTaskChanged(detail, "task.deliverable");
+      notifyDelivery(taskId, delivery.event.id, eventMeta ?? (delivery.event.metadata as unknown as TaskDeliverableEventMetadata));
+      if (input.disposition === "failed") {
+        emitTaskSemanticNotification({ task: detail, transition: "gate-failed", actor, occurrenceKey: `event:${delivery.event.id}`, outcome: { disposition: "failed" } });
+      }
+    }
+  }
+
+  let land: Record<string, unknown> | undefined;
+  if (wantsLand && delivery.created && workspace) {
+    markAgentWorkFinal(actor, "task-deliver");
+    const result = await applyWorkspaceAction(workspace, {
+      action: "ready",
+      agentId: actor,
+      detail: `Task T${taskId} delivered complete`,
+      auditMetadata: { via: "task_deliver", actor, taskId, deliveryEventId: delivery.event.id },
+    });
+    if (!result.ok) {
+      land = { requested: true, triggered: false, error: result.error, workspaceId: workspace.id };
+    } else {
+      if (result.command) emitCommand(result.command);
+      land = { requested: true, triggered: true, workspace: result.workspace, command: result.command };
+    }
+  } else if (wantsLand && !delivery.created) {
+    land = { requested: true, triggered: false, reason: "duplicate-delivery" };
+  }
+
+  return {
+    taskId,
+    event: delivery.event,
+    created: delivery.created,
+    delivery: eventMeta ?? delivery.event.metadata,
+    ...(land ? { land } : {}),
+  };
+}

package/src/services/task-entity.ts

@@ -38,7 +38,7 @@ import { errMessage } from "agent-relay-sdk";
 import { findSpawnCommandByRequestId } from "../commands-db";
 import { defaultIssueRepo } from "../config";
 import { emitTaskChanged } from "../sse";
-import type { CommandStatus, Task, TaskDetail, TaskEvent, TaskGateState, TaskListItem, TaskStatus, WorkspaceRecord } from "../types";
+import type { CommandStatus, Task, TaskDeliverableEventMetadata, TaskDetail, TaskEvent, TaskGateState, TaskListItem, TaskStatus, WorkspaceRecord } from "../types";
 import { removeSubscriptionsForTask } from "../db/notification-subscriptions";
 import { emitRelayEvent } from "../events";
 import { routeNotification } from "../notification-router";
@@ -389,6 +389,30 @@ export function reconcileAutoScaffoldedTaskReaps(opts: ReconcileAutoScaffoldedTa
   return { dryRun, scanned: completed.length + canceled.length + skipped.length, completed, canceled, skipped };
 }
 
+function latestDeliverableEvent(taskId: number): TaskEvent | undefined {
+  return [...listTaskEvents(taskId)].reverse().find((event) => event.type === "deliverable");
+}
+
+function restoreDeliveredDisposition(task: TaskDetail, event: TaskEvent): void {
+  const metadata = event.metadata as unknown as Partial<TaskDeliverableEventMetadata>;
+  if (metadata.disposition === "failed" && task.status !== "failed") {
+    setTaskEntityStatus(task.id, {
+      status: "failed",
+      ...(typeof metadata.reason === "string" && metadata.reason.trim() ? { note: metadata.reason } : {}),
+      actor: "task-lifecycle",
+    });
+    return;
+  }
+  if (metadata.disposition === "blocked" && task.status !== "blocked" && Array.isArray(metadata.blockedBy) && metadata.blockedBy.length > 0) {
+    setTaskEntityStatus(task.id, {
+      status: "blocked",
+      blockedBy: metadata.blockedBy,
+      ...(typeof metadata.reason === "string" && metadata.reason.trim() ? { note: metadata.reason } : {}),
+      actor: "task-lifecycle",
+    });
+  }
+}
+
 // #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.
@@ -407,6 +431,13 @@ export function finalizeEphemeralTasksOnReap(agentId: string, opts: { spawnReque
     if (!isAgentExitDoneWhen(task.doneWhen)) continue;
     if (opts.producedWork === false) {
       try {
+        const deliverable = latestDeliverableEvent(taskId);
+        if (deliverable) {
+          if (!task.reapedAt) markTaskAgentReaped(taskId, { agentId, reason: opts.reason ?? "agent-exit" });
+          restoreDeliveredDisposition(task, deliverable);
+          finalized.push(taskId);
+          continue;
+        }
         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);

package/src/workspace-actions.ts

@@ -28,7 +28,7 @@ export { LAND_STRATEGIES, DEFAULT_MERGE_STRATEGY } from "./workspace-merge";
 import { claimMetadataPatch, workspaceActiveClaim } from "./workspace-claim";
 import { DIRTY_WORKTREE_LAND_SKIP_REASON, READY_TO_LAND_STATUSES, TERMINAL_WORKSPACE_STATUSES, worktreeReapable } from "./workspace-phase";
 import { CLEAR_MERGE_NO_PROGRESS, scheduleRepoMerge } from "./workspace-auto-merge";
-import { fetchHostMergePreview } from "./workspace-probe";
+import { fetchHostMergePreview, refreshWorkspaceGitState } from "./workspace-probe";
 import type { Command, WorkspaceAutoMergePolicy, WorkspaceMergeStrategy, WorkspaceRecord, WorkspaceStatus } from "./types";
 
 // Single source of truth for the action verb set. The route's `optionalEnum` and
@@ -251,7 +251,9 @@ export async function applyWorkspaceAction(workspace: WorkspaceRecord, input: Ap
   if (!nextStatus) return { ok: false, httpStatus: 400, error: `unsupported action: ${action}` };
 
   if (READY_TO_LAND_STATUSES.has(nextStatus)) {
-    const dirtyCount = metadataNumber(workspace.metadata, "gitDirtyCount") ?? 0;
+    await refreshWorkspaceGitState(workspace);
+    const freshWorkspace = getWorkspace(workspace.id) ?? workspace;
+    const dirtyCount = metadataNumber(freshWorkspace.metadata, "gitDirtyCount") ?? 0;
     if (dirtyCount > 0) {
       return {
         ok: false,