agent-relay-server 0.125.0 → 0.127.0

package/src/db/task-deliverables.ts

@@ -0,0 +1,206 @@
+import {
+  TASK_DELIVERY_DISPOSITIONS,
+  TASK_GATE_STATUSES,
+  type TaskCommitRef,
+  type TaskBlocker,
+  type TaskDeliverableEventMetadata,
+  type TaskDeliveryDisposition,
+  type TaskDeliveryGateReports,
+  type TaskDeliveryResult,
+  type TaskDeliverySelfAcceptance,
+  type TaskEvent,
+  type TaskGateStatus,
+} from "../types";
+import { parseJson } from "../utils";
+import { getDb, ValidationError } from "./connection.ts";
+import { rowToTaskEvent } from "./mappers.ts";
+import { DELIVERABLE_TASK_KIND, insertTaskEvent } from "./task-core.ts";
+
+function requireText(value: unknown, field: string, max: number): string {
+  if (typeof value !== "string" || !value.trim()) throw new ValidationError(`${field} required`);
+  const cleaned = value.trim();
+  if (cleaned.length > max) throw new ValidationError(`${field} must be ${max} characters or fewer`);
+  return cleaned;
+}
+
+function optionalText(value: unknown, field: string, max: number): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "string") throw new ValidationError(`${field} must be a string`);
+  const cleaned = value.trim();
+  if (!cleaned) return undefined;
+  if (cleaned.length > max) throw new ValidationError(`${field} must be ${max} characters or fewer`);
+  return cleaned;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function taskCommitRows(id: number): TaskCommitRef[] {
+  const row = getDb().query("SELECT kind, commits FROM tasks WHERE id = ?").get(id) as { kind: string; commits: string | null } | undefined;
+  if (!row) throw new ValidationError(`task ${id} not found`);
+  if (row.kind !== DELIVERABLE_TASK_KIND) throw new ValidationError(`task ${id} is not a deliverable task`);
+  return parseJson<TaskCommitRef[]>(row.commits, []);
+}
+
+function appendCommitRow(id: number, commit: TaskCommitRef): void {
+  const sha = requireText(commit.sha, "commit.sha", 80);
+  const subject = optionalText(commit.subject, "commit.subject", 1000);
+  const commits = taskCommitRows(id);
+  if (commits.some((c) => c.sha === sha)) return;
+  commits.push({ sha, ...(subject ? { subject } : {}) });
+  getDb().query("UPDATE tasks SET commits = ?, updated_at = ? WHERE id = ?").run(JSON.stringify(commits), Date.now(), id);
+}
+
+function cleanCommitRefs(value: unknown): TaskCommitRef[] | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (!Array.isArray(value)) throw new ValidationError("commits must be an array");
+  const commits = value.map((entry, index) => {
+    if (!isObject(entry)) throw new ValidationError(`commits[${index}] must be an object`);
+    return {
+      sha: requireText(entry.sha, `commits[${index}].sha`, 80),
+      ...(optionalText(entry.subject, `commits[${index}].subject`, 1000) ? { subject: optionalText(entry.subject, `commits[${index}].subject`, 1000)! } : {}),
+    };
+  });
+  return commits.length > 0 ? commits : undefined;
+}
+
+function cleanGateReport(value: unknown, field: string): TaskDeliveryGateReports["typecheck"] {
+  if (value === undefined || value === null) return undefined;
+  if (!isObject(value)) throw new ValidationError(`${field} must be an object`);
+  if (!TASK_GATE_STATUSES.includes(value.status as TaskGateStatus)) throw new ValidationError(`${field}.status must be one of: ${TASK_GATE_STATUSES.join(", ")}`);
+  const count = value.count;
+  if (count !== undefined && (typeof count !== "number" || !Number.isSafeInteger(count) || count < 0)) {
+    throw new ValidationError(`${field}.count must be a non-negative integer`);
+  }
+  return {
+    status: value.status as TaskGateStatus,
+    ...(optionalText(value.detail, `${field}.detail`, 4000) ? { detail: optionalText(value.detail, `${field}.detail`, 4000)! } : {}),
+    ...(typeof count === "number" ? { count } : {}),
+    ...(optionalText(value.runId, `${field}.runId`, 240) ? { runId: optionalText(value.runId, `${field}.runId`, 240)! } : {}),
+  };
+}
+
+function cleanGateReports(value: unknown): TaskDeliveryGateReports | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (!isObject(value)) throw new ValidationError("gates must be an object");
+  const out: TaskDeliveryGateReports = {};
+  const typecheck = cleanGateReport(value.typecheck, "gates.typecheck");
+  const test = cleanGateReport(value.test, "gates.test");
+  if (typecheck) out.typecheck = typecheck;
+  if (test) out.test = test;
+  if (value.other !== undefined) {
+    if (!Array.isArray(value.other)) throw new ValidationError("gates.other must be an array");
+    const other = value.other.map((entry, index) => {
+      if (!isObject(entry)) throw new ValidationError(`gates.other[${index}] must be an object`);
+      const gate = cleanGateReport(entry, `gates.other[${index}]`)!;
+      return { name: requireText(entry.name, `gates.other[${index}].name`, 120), ...gate };
+    });
+    if (other.length > 0) out.other = other;
+  }
+  return out.typecheck || out.test || out.other?.length ? out : undefined;
+}
+
+function cleanRisks(value: unknown): string[] | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (!Array.isArray(value)) throw new ValidationError("risks must be an array");
+  const risks = value.map((entry, index) => requireText(entry, `risks[${index}]`, 4000));
+  return risks.length > 0 ? risks : undefined;
+}
+
+function cleanBlockedBy(value: unknown): TaskBlocker[] | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (!Array.isArray(value)) throw new ValidationError("blockedBy must be an array");
+  const entries = value.map((entry, index) => {
+    if (!isObject(entry)) throw new ValidationError(`blockedBy[${index}] must be an object`);
+    const type = entry.type as TaskBlocker["type"];
+    if (type !== "dep" && type !== "gate" && type !== "decision" && type !== "external") {
+      throw new ValidationError(`blockedBy[${index}].type must be one of: dep, gate, decision, external`);
+    }
+    return {
+      type,
+      ...(optionalText(entry.ref, `blockedBy[${index}].ref`, 240) ? { ref: optionalText(entry.ref, `blockedBy[${index}].ref`, 240)! } : {}),
+      ...(optionalText(entry.note, `blockedBy[${index}].note`, 2000) ? { note: optionalText(entry.note, `blockedBy[${index}].note`, 2000)! } : {}),
+    };
+  });
+  return entries.length > 0 ? entries : undefined;
+}
+
+function cleanSelfAcceptance(value: unknown): TaskDeliverySelfAcceptance[] | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (!Array.isArray(value)) throw new ValidationError("selfAcceptance must be an array");
+  const entries = value.map((entry, index) => {
+    if (!isObject(entry)) throw new ValidationError(`selfAcceptance[${index}] must be an object`);
+    if (entry.status !== "met" && entry.status !== "unmet") throw new ValidationError(`selfAcceptance[${index}].status must be met or unmet`);
+    return {
+      criterion: requireText(entry.criterion, `selfAcceptance[${index}].criterion`, 1000),
+      status: entry.status as TaskDeliverySelfAcceptance["status"],
+      ...(optionalText(entry.note, `selfAcceptance[${index}].note`, 4000) ? { note: optionalText(entry.note, `selfAcceptance[${index}].note`, 4000)! } : {}),
+    };
+  });
+  return entries.length > 0 ? entries : undefined;
+}
+
+export interface RecordTaskDeliverableInput extends TaskDeliveryResult {
+  actor: string;
+  workspaceId?: string;
+  idempotencyKey?: string;
+  land?: TaskDeliverableEventMetadata["land"];
+}
+
+export function recordTaskDeliverable(id: number, input: RecordTaskDeliverableInput): { event: TaskEvent; created: boolean } {
+  taskCommitRows(id);
+  const actor = requireText(input.actor, "actor", 200);
+  const idempotencyKey = optionalText(input.idempotencyKey, "idempotencyKey", 240);
+  if (idempotencyKey) {
+    const existing = getDb()
+      .query("SELECT * FROM task_events WHERE task_id = ? AND type = 'deliverable' AND json_extract(metadata, '$.idempotencyKey') = ? LIMIT 1")
+      .get(id, idempotencyKey) as any;
+    if (existing) return { event: rowToTaskEvent(existing), created: false };
+  }
+  if (!TASK_DELIVERY_DISPOSITIONS.includes(input.disposition as TaskDeliveryDisposition)) {
+    throw new ValidationError(`disposition must be one of: ${TASK_DELIVERY_DISPOSITIONS.join(", ")}`);
+  }
+  const commits = cleanCommitRefs(input.commits);
+  const gates = cleanGateReports(input.gates);
+  const reason = optionalText(input.reason, "reason", 64_000);
+  const blockedBy = cleanBlockedBy(input.blockedBy);
+  const filesChanged = input.filesChanged;
+  if (filesChanged !== undefined && (typeof filesChanged !== "number" || !Number.isSafeInteger(filesChanged) || filesChanged < 0)) {
+    throw new ValidationError("filesChanged must be a non-negative integer");
+  }
+  const now = Date.now();
+  const metadata: TaskDeliverableEventMetadata = {
+    v: 1,
+    disposition: input.disposition,
+    summary: requireText(input.summary, "summary", 1_000_000),
+    actor,
+    ...(reason ? { reason } : {}),
+    ...(blockedBy ? { blockedBy } : {}),
+    ...(commits ? { commits } : {}),
+    ...(gates ? { gates } : {}),
+    ...(typeof filesChanged === "number" ? { filesChanged } : {}),
+    ...(optionalText(input.rca, "rca", 64_000) ? { rca: optionalText(input.rca, "rca", 64_000)! } : {}),
+    ...(optionalText(input.testCoverage, "testCoverage", 64_000) ? { testCoverage: optionalText(input.testCoverage, "testCoverage", 64_000)! } : {}),
+    ...(cleanRisks(input.risks) ? { risks: cleanRisks(input.risks)! } : {}),
+    ...(cleanSelfAcceptance(input.selfAcceptance) ? { selfAcceptance: cleanSelfAcceptance(input.selfAcceptance)! } : {}),
+    ...(optionalText(input.workspaceId, "workspaceId", 240) ? { workspaceId: optionalText(input.workspaceId, "workspaceId", 240)! } : {}),
+    ...(idempotencyKey ? { idempotencyKey } : {}),
+    ...(input.land ? { land: input.land } : {}),
+  };
+  const event = getDb().transaction(() => {
+    if (commits) {
+      for (const commit of commits) appendCommitRow(id, commit);
+    }
+    getDb().query("UPDATE tasks SET updated_at = ?, last_seen_at = ? WHERE id = ?").run(now, now, id);
+    return insertTaskEvent(id, {
+      source: actor,
+      type: "deliverable",
+      severity: input.disposition === "failed" || input.disposition === "blocked" ? "warning" : "info",
+      title: `Delivery result: ${input.disposition}`,
+      body: metadata.summary,
+      metadata: metadata as unknown as Record<string, unknown>,
+    }, now);
+  })();
+  return { event, created: true };
+}

package/src/db/task-entity.ts

@@ -322,14 +322,7 @@ export function setTaskStage(id: number, input: SetTaskStageInput): TaskDetail {
   return getTaskDetail(id)!;
 }
 
-export interface RecordGateInput {
-  gate: string;
-  status: TaskGateStatus;
-  detail?: string;
-  commitSha?: string;
-  runId?: string;
-  actor?: string;
-}
+export interface RecordGateInput { gate: string; status: TaskGateStatus; detail?: string; count?: number; commitSha?: string; runId?: string; actor?: string; }
 
 // Quality-gate ledger write (#834). The append-only `task_events` IS the ledger (no second
 // system of record). Idempotent by runId: the SAME run reported twice does not double-append,
@@ -341,6 +334,7 @@ export function recordGate(id: number, input: RecordGateInput): TaskGateState {
   if (!TASK_GATE_STATUSES.includes(input.status)) {
     throw new ValidationError(`gate status must be one of: ${TASK_GATE_STATUSES.join(", ")}`);
   }
+  if (input.count !== undefined && (!Number.isSafeInteger(input.count) || input.count < 0)) throw new ValidationError("count must be a non-negative integer");
   const type = `${GATE_EVENT_PREFIX}${gate}`;
   const runId = optionalText(input.runId, "runId", 240);
   if (runId) {
@@ -360,6 +354,7 @@ export function recordGate(id: number, input: RecordGateInput): TaskGateState {
       gate,
       status: input.status,
       ...(input.detail ? { detail: input.detail } : {}),
+      ...(typeof input.count === "number" ? { count: input.count } : {}),
       ...(input.commitSha ? { commitSha: input.commitSha } : {}),
       ...(runId ? { runId } : {}),
     },
@@ -373,6 +368,7 @@ function gateStateFromEvent(row: { type: string; created_at: number; metadata: s
     gate: typeof meta.gate === "string" ? meta.gate : row.type.slice(GATE_EVENT_PREFIX.length),
     status: (meta.status as TaskGateStatus) ?? "fail",
     ...(typeof meta.detail === "string" ? { detail: meta.detail } : {}),
+    ...(typeof meta.count === "number" ? { count: meta.count } : {}),
     ...(typeof meta.commitSha === "string" ? { commitSha: meta.commitSha } : {}),
     ...(typeof meta.runId === "string" ? { runId: meta.runId } : {}),
     ranAt: row.created_at,

package/src/mcp/index.ts

@@ -6,6 +6,7 @@ import { McpAuthError, McpNotFoundError } from "../mcp-errors";
 import { createActivityEvent, ValidationError } from "../db";
 import { PLAN_TOOLS, relayPlanTool } from "../mcp-plan-tools";
 import { TASK_TOOLS, relayTaskTool } from "../mcp-task-tools";
+import { TASK_DELIVER_TOOLS, relayTaskDeliverTool } from "../mcp-task-deliver-tools";
 import { TASK_MEMORY_TOOLS, relayTaskMemoryTool } from "../mcp-task-memory-tools";
 import { DISPATCH_TOOLS, relayDispatchTool } from "../mcp-dispatch-tools";
 import { TASK_WEAVE_TOOLS, relayTaskWeaveTool } from "../mcp-task-weave-tools";
@@ -37,7 +38,7 @@ const TOOLS: ToolDefinition[] = [
   AGENT_ACTION_TOOL,
   ...WORKSPACE_TOOLS,
   ...MERGE_TOOLS, ...TEAM_TOOLS,
-  ...PLAN_TOOLS, ...TASK_TOOLS, ...TASK_MEMORY_TOOLS, ...DISPATCH_TOOLS, ...TASK_WEAVE_TOOLS, ...RELEASE_TOOLS, ...ISSUE_REF_TOOLS, ...ISSUE_ASSOCIATION_TOOLS, ...ISSUE_ACTIVITY_TOOLS, ...ISSUE_LIFECYCLE_TOOLS,
+  ...PLAN_TOOLS, ...TASK_TOOLS, ...TASK_DELIVER_TOOLS, ...TASK_MEMORY_TOOLS, ...DISPATCH_TOOLS, ...TASK_WEAVE_TOOLS, ...RELEASE_TOOLS, ...ISSUE_REF_TOOLS, ...ISSUE_ASSOCIATION_TOOLS, ...ISSUE_ACTIVITY_TOOLS, ...ISSUE_LIFECYCLE_TOOLS,
   ...BLACKBOARD_TOOLS,
   ...PROJECT_TOOLS,
   ...MEMORY_TOOLS,
@@ -52,7 +53,7 @@ export const RELAY_TOOL_GROUPS: Record<string, readonly string[]> = {
   core: ["relay_whoami", "relay_send_message", "relay_reply", "relay_get_message", "relay_get_thread", "relay_find_agents"],
   memory: ["relay_recall", "relay_compact_and_resume", "relay_memory_write", "relay_memory_promote", "relay_memory_retract", "relay_memory_read", "relay_memory_search"],
   artifacts: ["relay_upload_artifact", "relay_attach_artifact"],
-  workspace: ["relay_workspace_status", "relay_workspace_ready", "relay_workspace_deps", "relay_workspace_list", "relay_workspace_claim", "relay_workspace_release", "relay_workspace_land", "relay_merge_pause", "relay_merge_pauses", "relay_merge_renew", "relay_merge_resume"],
+  workspace: ["relay_workspace_status", "relay_workspace_deps", "relay_workspace_list", "relay_workspace_claim", "relay_workspace_release", "relay_task_deliver", "relay_merge_pause", "relay_merge_pauses", "relay_merge_renew", "relay_merge_resume"],
   "spawn-lifecycle": ["relay_spawn_agent", "relay_spawn_targets", "relay_my_agents", "relay_shutdown_agent", "relay_agent_action", "relay_agent_status", "relay_agent_crash_report"],
   schedule: ["relay_schedule_timer", "relay_list_timers", "relay_cancel_timer"],
   plans: ["relay_plan_create", "relay_plan_add_node", "relay_plan_update_node", "relay_plan_add_edge", "relay_plan_remove_node", "relay_plan_remove_edge", "relay_plan_archive", "relay_plan_delete", "relay_plan_get"],
@@ -167,13 +168,12 @@ async function callTool(auth: McpAuthContext, params: unknown): Promise<Record<s
     else if (name === "relay_agent_action") result = relayAgentAction(auth, args);
     else if (name === "relay_workspace_status") result = await relayWorkspaceStatus(auth, args);
     else if (name === "relay_workspace_list") result = relayWorkspaceList(auth, args);
-    else if (name === "relay_workspace_ready") result = await relayWorkspaceMutation(auth, "ready", args);
     else if (name === "relay_workspace_deps") result = await relayWorkspaceMutation(auth, "deps-refresh", args);
     else if (name === "relay_workspace_claim") result = await relayWorkspaceMutation(auth, "claim", args);
     else if (name === "relay_workspace_release") result = await relayWorkspaceMutation(auth, "release-claim", args);
-    else if (name === "relay_workspace_land") result = await relayWorkspaceMutation(auth, "merge", args);
     else if (name.startsWith("relay_merge_")) result = relayMergeTool(auth, name, args); else if (name.startsWith("relay_team_")) result = await relayTeamTool(auth, name, args);
     else if (name.startsWith("relay_plan_")) result = relayPlanTool(auth, name, args);
+    else if (name === "relay_task_deliver") result = await relayTaskDeliverTool(auth, name, args);
     else if (name.startsWith("relay_task_memory_")) result = relayTaskMemoryTool(auth, name, args);
     else if (name === "relay_task_dispatch") result = relayDispatchTool(auth, name, args);
     else if (name === "relay_task_comment" || name === "relay_task_close_bridge") result = await relayTaskWeaveTool(auth, name, args);

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

@@ -2,7 +2,7 @@
 import { RELAY_TOKEN_HEADER, isRecord, isSpawnProvider } from "agent-relay-sdk";
 import { VALID_AGENT_ACTIONS, agentControlActionIcon, auditEvent, authAuditMetadata, authorizeAgentRoute, authorizeRoute, canViewAgentRoute, cleanAttachmentRefs, dashboardAttribution, emitCommand, error, json, metaString, parseBody, requestUserAddress, requestUserId, spawnRequestId, type AgentControlAction, type Handler } from "./_shared";
 import { arbitrateDrive, currentDriver, drivingMessage, releaseDrive, type DriveArbitration } from "../agent-drive-arbiter";
-import { ValidationError, getAgent, getAgentTimeline, getOrchestrator, markReady, mergeAgentMeta, readSpawnCallerSystemPromptAppend, resolveAgentOwnership, sendMessage, withResolvedProvisioning } from "../db";
+import { ValidationError, getAgent, getAgentTimeline, getOrchestrator, markReady, mergeAgentMeta, sendMessage, withResolvedProvisioning } from "../db";
 import { announcePresence, viewersForAgent } from "../dashboard-presence";
 import { buildManagedSpawnParams } from "../managed-policy";
 import { buildSpawnCommand, generateSpawnRequestId, resolveSpawnModelParams } from "../spawn-command";
@@ -19,8 +19,8 @@ import { ShutdownAuthError, ShutdownTargetError, shutdownAgent } from "../servic
 import { type AgentCard, type SpawnApprovalMode } from "../types";
 import { type ProviderEffort } from "agent-relay-sdk/provider-catalog";
 import { getManifest } from "agent-relay-providers";
-import { composeProfileSpawnInstructions } from "../project-instructions";
 import { relayToken } from "../config";
+import { restartInstructionParamsForAgent } from "../services/restart-instructions";
 
 // 409 when a second human tries to drive an agent another user is already driving (#394). The
 // blocked driver learns who holds the wheel so the UI can show "X is driving" + offer "request".
@@ -133,6 +133,7 @@ export function restartSpawnParamsForAgent(
   const agentProfile = resolvedProfile ? applyDefaultSharedMcp(resolvedProfile) : undefined;
   const workspaceMode = metaString(agent.meta, "workspaceMode") ?? "inherit";
   const resolvedModel = resolveSpawnModelParams(provider, model, effort, { onError: "passthrough", skipDefaultWhenEmpty: true });
+  const projectedInstructions = restartInstructionParamsForAgent(agent, { spawnRequestId, cwd }) ?? {};
   // #1052-v2 — a dashboard-spawned agent has NO spawn policy, so its restart skips the
   // `buildManagedSpawnParams` policy branch above and lands here. Re-project the profile role
   // charter / project knowledge / scoped memory (the SAME projection a fresh spawn gets) so the
@@ -152,8 +153,6 @@ export function restartSpawnParamsForAgent(
   // params — the SAME field a fresh agent.spawn stashes it in, see spawn-agent.ts). The reader then
   // recovers it from either the original agent.spawn row OR a later agent.restart row, so each
   // generation has its own recoverable copy and the brief follows the agent across every rotation.
-  const callerAppend = readSpawnCallerSystemPromptAppend(spawnRequestId);
-  const composed = composeProfileSpawnInstructions({ cwd, operatorId: resolveAgentOwnership(agent.id).ownerUserId, ...(profileName ? { profileName } : {}), ...(agentProfile ? { profile: agentProfile } : {}), ...(callerAppend ? { callerSystemPromptAppend: callerAppend } : {}) });
   const params = buildSpawnCommand({
     provider,
     modelParams: resolvedModel,
@@ -168,12 +167,12 @@ export function restartSpawnParamsForAgent(
     approvalMode: approvalMode ?? "guarded",
     permissionMode: approvalMode ?? "guarded",
     providerArgs: providerArgs.length ? providerArgs : undefined,
-    ...(composed.systemPromptAppend ? { systemPromptAppend: composed.systemPromptAppend } : {}),
+    ...(typeof projectedInstructions.systemPromptAppend === "string" ? { systemPromptAppend: projectedInstructions.systemPromptAppend } : {}),
     // #1067 — re-persist the RAW brief (pre-composition) under this restart's fresh spawnRequestId so
     // the NEXT restart, whose predecessor id is this fresh id, can recover it. Without this the brief
     // survives only one restart (the original agent.spawn row is keyed on the very first id).
-    ...(callerAppend ? { callerSystemPromptAppend: callerAppend } : {}),
-    ...(composed.relayInjectionEvents.length ? { relayInjectionEvents: composed.relayInjectionEvents } : {}),
+    ...(typeof projectedInstructions.callerSystemPromptAppend === "string" ? { callerSystemPromptAppend: projectedInstructions.callerSystemPromptAppend } : {}),
+    ...(Array.isArray(projectedInstructions.relayInjectionEvents) ? { relayInjectionEvents: projectedInstructions.relayInjectionEvents } : {}),
     policyName: policyName || undefined,
     headless: true,
     spawnRequestId: requestId,
@@ -298,6 +297,9 @@ export const postAgentAction: Handler = async (req, params) => {
     const metaPolicyName = typeof agent.meta?.policyName === "string" ? agent.meta.policyName : undefined;
     const metaSpawnRequestId = typeof agent.meta?.spawnRequestId === "string" ? agent.meta.spawnRequestId : undefined;
     const resumeId = action === "resume" ? latestResumeIdForAgent(agent) : undefined;
+    const restartInstructions = action === "restart" || action === "resume"
+      ? restartInstructionParamsForAgent(agent, { spawnRequestId: metaSpawnRequestId, cwd: metaString(agent.meta, "cwd") ?? orchestrator?.baseDir })
+      : undefined;
     if (action === "resume" && !orchestrator) return error("no online orchestrator available to resume agent", 409);
     if (action === "resume" && !resumeId) return error("no resume id recorded for agent", 422);
     const denied = authorizeRoute(req, {
@@ -319,6 +321,7 @@ export const postAgentAction: Handler = async (req, params) => {
         ...(metaPolicyName ? { policyName: metaPolicyName } : {}),
         ...(metaSpawnRequestId ? { spawnRequestId: metaSpawnRequestId } : {}),
         ...(action === "restart" || action === "resume" ? { restartSpawn: restartSpawnParamsForAgent(agent, orchestrator, metaPolicyName, metaSpawnRequestId, { resumeId }) } : {}),
+        ...(restartInstructions ?? {}),
         ...(action === "compact" ? compactMemoryParams(agent) : {}),
         ...(resumeId ? { claudeResumeId: resumeId } : {}),
         requestedBy: "dashboard",