agent-relay-server 0.126.0 → 0.127.0

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/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/workspace-phase.ts

@@ -84,7 +84,7 @@ export const LAND_PENDING_STALL_MS = 15 * 60 * 1000;
 export const DIRTY_WORKTREE_LAND_SKIP_REASON = "worktree has uncommitted changes";
 
 type WorkspacePhase =
-  | "working" // active — your turn: commit, then mark ready
+  | "working" // active — your turn: commit, then deliver
   | "land-pending" // ready | review_requested — handed off; auto-merge will land it
   | "landing" // merge_planned — merge dispatched, in progress
   | "steward" // conflict — auto-merge couldn't; a steward is reconciling (not your job)
@@ -122,13 +122,13 @@ const WAIT_ACTION: WorkspaceNextAction = {
 const CHECK_STATUS_ACTION: WorkspaceNextAction = {
   tool: "relay_workspace_status",
   cli: "agent-relay workspace status",
-  when: "only if you are explicitly checking state later; do not poll or wait after marking ready",
+  when: "only if you are explicitly checking state later; do not poll or wait after delivering",
 };
 
 const READY_ACTION: WorkspaceNextAction = {
-  tool: "relay_workspace_ready",
-  cli: "agent-relay workspace ready",
-  when: "after you commit your work in this worktree",
+  tool: "relay_task_deliver",
+  cli: "MCP relay_task_deliver",
+  when: "after you commit your work and have passing delivery gates",
 };
 
 // Map every WorkspaceStatus to the branch agent's mental model. Statuses that