agent-relay-server 0.107.0 → 0.109.0

package/src/routes/tasks.ts

@@ -1,13 +1,31 @@
 // Auto-split from routes.ts (#299). Domain: tasks.
 import { MAX_BODY_BYTES } from "../config";
-import { VALID_TASK_STATUSES, agentSessionStatus, auditEvent, dispatchTaskCallbacks, emitCommand, error, json, normalizeAgentSessionGuard, parseBody, parseId, parseQueryInt, type Handler } from "./_shared";
+import { VALID_TASK_STATUSES, agentSessionStatus, auditEvent, dispatchTaskCallbacks, emitCommand, error, json, normalizeAgentSessionGuard, parseBody, parseId, parseQueryInt, resolveActorLabel, type Handler } from "./_shared";
+import { getComponentAuth } from "../security";
+import { agentIdFromComponent, isTaskDispatchAuthorized, isTaskReadAuthorized } from "../task-authz";
+import { dispatchShapeArg, pinArg, runTaskDispatch } from "../mcp-dispatch-tools";
 import { ValidationError, claimTask, getMessage, getTask, listTaskEvents, listTasks, recordTaskEvent, renewTaskClaim, updateTaskStatus } from "../db";
+import { readTaskMemoryEnvelope } from "../db/task-memory";
+import {
+  addTaskEntityDependency, addTaskEntityRef, assignTaskEntityAgent, createTaskEntity, getTaskEntity,
+  listTaskEntities, recordTaskEntityGate, removeTaskEntityDependency, removeTaskEntityRef, setTaskEntityStage, setTaskEntityStatus, taskEntityHistory, updateTaskEntity,
+} from "../services/task-entity";
+import { CommentThroughError, commentOnTaskThrough, taskCloseBridge } from "../services/task-issue-weave";
 import { captureTaskResultMemory, injectMemoryForTaskClaim } from "../memory-service";
 import { cleanEpoch, cleanMeta, cleanString, optionalEnum } from "../validation";
 import { emitMessageClaimed, emitTaskChanged } from "../sse";
-import { errMessage, isRecord } from "agent-relay-sdk";
+import { errMessage, isRecord, TASK_DELIVERABLE_STAGES, type TaskBlocker, type TaskDispatch, type TaskGateStatus } from "agent-relay-sdk";
 import { type AgentSessionGuard, type TaskStatus, type TaskStatusInput } from "../types";
 
+function actorOf(req: Request, fallback?: unknown): string {
+  return resolveActorLabel(req) ?? (typeof fallback === "string" && fallback.trim() ? fallback.trim() : "dashboard");
+}
+
+function taskDetailOr404(id: number) {
+  const detail = getTaskEntity(id);
+  return detail ? json(detail) : error("deliverable task not found", 404);
+}
+
 function normalizeTaskStatusInput(body: unknown): TaskStatusInput {
   if (!isRecord(body)) throw new ValidationError("JSON object body required");
   const status = optionalEnum(body.status, "status", VALID_TASK_STATUSES);
@@ -27,14 +45,329 @@ export const getTasks: Handler = (req) => {
   const url = new URL(req.url);
   const limitRaw = parseQueryInt(url.searchParams.get("limit"), { min: 1, max: 500 });
   if (Number.isNaN(limitRaw)) return error("limit must be an integer between 1 and 500");
+  // The legacy queue defaults to the claim lane (#834). `kind=deliverable` returns the
+  // durable Tasks (optionally filtered by deliverable stage / team).
+  const kind = url.searchParams.get("kind") ?? undefined;
+  if (kind === "deliverable") {
+    return json(listTaskEntities({
+      status: url.searchParams.get("status") ?? undefined,
+      deliverableStage: url.searchParams.get("deliverableStage") ?? undefined,
+      teamId: url.searchParams.get("teamId") ?? undefined,
+      limit: limitRaw ?? 100,
+    }));
+  }
   return json(listTasks({
     status: url.searchParams.get("status") ?? undefined,
     source: url.searchParams.get("source") ?? undefined,
     target: url.searchParams.get("target") ?? undefined,
+    kind: kind === "all" ? "all" : "claim",
     limit: limitRaw ?? 100,
   }));
 };
 
+// --- #834 durable Task entity (kind='deliverable') HTTP surface ---
+
+export const postTaskCreate: Handler = async (req) => {
+  const parsed = await parseBody<Record<string, unknown>>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const body = parsed.body;
+  if (!isRecord(body)) return error("JSON object body required");
+  try {
+    const created = createTaskEntity({
+      title: body.title as string,
+      intent: cleanString(body.intent, "intent", { max: MAX_BODY_BYTES }),
+      doneWhen: cleanString(body.doneWhen, "doneWhen", { max: MAX_BODY_BYTES }),
+      teamId: cleanString(body.teamId, "teamId", { max: 200 }),
+      dispatch: body.dispatch as TaskDispatch | undefined,
+      createdBy: actorOf(req, body.createdBy),
+    });
+    if (Array.isArray(body.issueRefs)) {
+      for (const ref of body.issueRefs) {
+        if (typeof ref === "string" && ref.trim()) addTaskEntityRef(created.id, { issue: ref, defaultRepo: cleanString(body.defaultRepo, "defaultRepo", { max: 500 }), actor: actorOf(req, body.createdBy) });
+      }
+    }
+    if (Array.isArray(body.dependsOn)) {
+      for (const dep of body.dependsOn) {
+        const depId = parseId(String(dep));
+        if (depId !== null) addTaskEntityDependency(created.id, depId, actorOf(req, body.createdBy));
+      }
+    }
+    return json(getTaskEntity(created.id), 201);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const getTaskDetailRoute: Handler = (_req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid task id");
+  return taskDetailOr404(id);
+};
+
+export const getTaskMemoryRoute: Handler = (req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid task id");
+  if (!getTaskEntity(id)) return error("deliverable task not found", 404);
+  const component = getComponentAuth(req);
+  const agentId = component ? agentIdFromComponent(component) : undefined;
+  const scopes = component?.scope ?? [];
+  if (!isTaskReadAuthorized(id, agentId, scopes)) return error("forbidden", 403);
+  return json(readTaskMemoryEnvelope(id));
+};
+
+export const getTaskHistoryRoute: Handler = (req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid task id");
+  if (!getTaskEntity(id)) return error("deliverable task not found", 404);
+  const component = getComponentAuth(req);
+  const agentId = component ? agentIdFromComponent(component) : undefined;
+  const scopes = component?.scope ?? [];
+  if (!isTaskReadAuthorized(id, agentId, scopes)) return error("forbidden", 403);
+  return json(taskEntityHistory(id));
+};
+
+export const patchTaskEntity: Handler = async (req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid task id");
+  const parsed = await parseBody<Record<string, unknown>>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const body = parsed.body;
+  if (!isRecord(body)) return error("JSON object body required");
+  try {
+    const detail = updateTaskEntity(id, {
+      ...(body.title !== undefined ? { title: cleanString(body.title, "title", { max: 500 }) } : {}),
+      ...(body.intent !== undefined ? { intent: cleanString(body.intent, "intent", { max: MAX_BODY_BYTES }) ?? "" } : {}),
+      ...(body.latestSteer !== undefined ? { latestSteer: cleanString(body.latestSteer, "latestSteer", { max: MAX_BODY_BYTES }) ?? "" } : {}),
+      ...(body.doneWhen !== undefined ? { doneWhen: cleanString(body.doneWhen, "doneWhen", { max: MAX_BODY_BYTES }) ?? "" } : {}),
+      ...(body.dispatch !== undefined ? { dispatch: body.dispatch as TaskDispatch } : {}),
+      ...(body.teamId !== undefined ? { teamId: cleanString(body.teamId, "teamId", { max: 200 }) ?? "" } : {}),
+      actor: actorOf(req),
+    });
+    return json(detail);
+  } catch (e) {
+    return entityError(e);
+  }
+};
+
+export const postTaskEntityStatus: Handler = async (req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid task id");
+  const parsed = await parseBody<Record<string, unknown>>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const body = parsed.body;
+  if (!isRecord(body)) return error("JSON object body required");
+  try {
+    const detail = setTaskEntityStatus(id, {
+      status: body.status as TaskStatus,
+      blockedBy: body.blockedBy as TaskBlocker[] | undefined,
+      note: cleanString(body.note, "note", { max: 4000 }),
+      actor: actorOf(req),
+    });
+    return json(detail);
+  } catch (e) {
+    return entityError(e);
+  }
+};
+
+export const postTaskEntityStage: Handler = async (req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid task id");
+  const parsed = await parseBody<Record<string, unknown>>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const body = parsed.body;
+  if (!isRecord(body)) return error("JSON object body required");
+  try {
+    const detail = setTaskEntityStage(id, {
+      deliverableStage: optionalEnum(body.deliverableStage, "deliverableStage", TASK_DELIVERABLE_STAGES) as any,
+      branch: cleanString(body.branch, "branch", { max: 500 }),
+      commit: isRecord(body.commit) ? { sha: body.commit.sha as string, subject: body.commit.subject as string | undefined } : undefined,
+      actor: actorOf(req),
+    });
+    return json(detail);
+  } catch (e) {
+    return entityError(e);
+  }
+};
+
+export const postTaskEntityGate: Handler = async (req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid task id");
+  const parsed = await parseBody<Record<string, unknown>>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const body = parsed.body;
+  if (!isRecord(body)) return error("JSON object body required");
+  try {
+    return json(recordTaskEntityGate(id, {
+      gate: cleanString(body.gate, "gate", { required: true, max: 120 })!,
+      status: body.status as TaskGateStatus,
+      detail: cleanString(body.detail, "detail", { max: 4000 }),
+      commitSha: cleanString(body.commitSha, "commitSha", { max: 80 }),
+      runId: cleanString(body.runId, "runId", { max: 240 }),
+      actor: actorOf(req),
+    }));
+  } catch (e) {
+    return entityError(e);
+  }
+};
+
+export const postTaskDependency: Handler = async (req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid task id");
+  const parsed = await parseBody<{ dependsOnTaskId?: number }>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const dep = parseId(String(parsed.body?.dependsOnTaskId));
+  if (dep === null) return error("dependsOnTaskId required");
+  try {
+    addTaskEntityDependency(id, dep, actorOf(req));
+    return taskDetailOr404(id);
+  } catch (e) {
+    return entityError(e);
+  }
+};
+
+export const deleteTaskDependency: Handler = async (req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid task id");
+  const parsed = await parseBody<{ dependsOnTaskId?: number }>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const dep = parseId(String(parsed.body?.dependsOnTaskId));
+  if (dep === null) return error("dependsOnTaskId required");
+  removeTaskEntityDependency(id, dep, actorOf(req));
+  return taskDetailOr404(id);
+};
+
+export const postTaskRef: Handler = async (req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid task id");
+  const parsed = await parseBody<Record<string, unknown>>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const body = parsed.body;
+  if (!isRecord(body)) return error("JSON object body required");
+  try {
+    const detail = addTaskEntityRef(id, {
+      issue: cleanString(body.issue, "issue", { max: 1000 }),
+      defaultRepo: cleanString(body.defaultRepo, "defaultRepo", { max: 500 }),
+      branch: cleanString(body.branch, "branch", { max: 500 }),
+      commit: isRecord(body.commit) ? { sha: body.commit.sha as string, subject: body.commit.subject as string | undefined } : undefined,
+      actor: actorOf(req),
+    });
+    return json(detail);
+  } catch (e) {
+    return entityError(e);
+  }
+};
+
+export const deleteTaskRef: Handler = async (req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid task id");
+  const parsed = await parseBody<Record<string, unknown>>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const body = parsed.body;
+  if (!isRecord(body)) return error("JSON object body required");
+  try {
+    const detail = removeTaskEntityRef(id, {
+      issueRefId: cleanString(body.issueRefId, "issueRefId", { max: 120 }),
+      branch: body.branch === true,
+      commitSha: cleanString(body.commitSha, "commitSha", { max: 80 }),
+      actor: actorOf(req),
+    });
+    return json(detail);
+  } catch (e) {
+    return entityError(e);
+  }
+};
+
+export const postTaskAssign: Handler = async (req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid task id");
+  const parsed = await parseBody<Record<string, unknown>>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const body = parsed.body;
+  if (!isRecord(body)) return error("JSON object body required");
+  try {
+    const detail = assignTaskEntityAgent(id, cleanString(body.agentId, "agentId", { required: true, max: 200 })!, cleanString(body.role, "role", { max: 120 }), actorOf(req));
+    return json(detail);
+  } catch (e) {
+    return entityError(e);
+  }
+};
+
+// #833 — comment-on-Task writes THROUGH to the linked GitHub issue (discussion lives in
+// GitHub, never a relay table). Execution telemetry never reaches this path.
+export const postTaskComment: Handler = async (req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid task id");
+  const parsed = await parseBody<Record<string, unknown>>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const body = parsed.body;
+  if (!isRecord(body)) return error("JSON object body required");
+  try {
+    const result = await commentOnTaskThrough({
+      taskId: id,
+      body: cleanString(body.body, "body", { required: true, max: MAX_BODY_BYTES })!,
+      clientId: cleanString(body.clientId, "clientId", { max: 240 }),
+      author: actorOf(req, body.author),
+    });
+    return json(result);
+  } catch (e) {
+    // Upstream GitHub write failed (well-formed request, no receipt written) → 502, not 400/500.
+    if (e instanceof CommentThroughError) return error(e.message, 502);
+    return entityError(e);
+  }
+};
+
+// #845 — HTTP dispatch decision endpoint. Invokes the SAME path as the MCP relay_task_dispatch
+// tool (via runTaskDispatch). Accepts an optional inline dispatch override + pin; always returns
+// the decision + rationale so the UI can show the #839 guard before any spawn. Never spawns.
+// Auth: admin scope OR a bound agent (#848: no scope-only gate).
+export const postTaskDispatch: Handler = async (req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid task id");
+  if (!getTaskEntity(id)) return error("deliverable task not found", 404);
+  const component = getComponentAuth(req);
+  const agentId = component ? agentIdFromComponent(component) : undefined;
+  const scopes = component?.scope ?? [];
+  if (!isTaskDispatchAuthorized(id, agentId, scopes)) return error("forbidden", 403);
+  const parsed = await parseBody<Record<string, unknown>>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const body = parsed.body ?? {};
+  try {
+    const result = runTaskDispatch({
+      taskId: id,
+      dispatch: dispatchShapeArg(body.dispatch),
+      pin: pinArg(body.pin),
+      createReview: body.createReview !== false,
+      actor: actorOf(req),
+    });
+    return json({
+      taskId: result.taskId,
+      decision: result.decision,
+      ...(result.reviewTaskId !== undefined ? { reviewTaskId: result.reviewTaskId } : {}),
+    });
+  } catch (e) {
+    return entityError(e);
+  }
+};
+
+// #833 — read the #482/#474 close-bridge projection for a Task's linked issues.
+export const getTaskCloseBridge: Handler = (_req, params) => {
+  const id = parseId(params.id);
+  if (id === null) return error("invalid task id");
+  try {
+    return json({ taskId: id, bridge: taskCloseBridge(id) });
+  } catch (e) {
+    return entityError(e);
+  }
+};
+
+function entityError(e: unknown): Response {
+  if (e instanceof ValidationError) {
+    return error(e.message, /not found/.test(e.message) ? 404 : 400);
+  }
+  throw e;
+}
+
 export const getTaskById: Handler = (_req, params) => {
   const id = parseId(params.id);
   if (id === null) return error("invalid task id");

package/src/routing-policy-store.ts

@@ -9,8 +9,25 @@
 import { ValidationError } from "./db";
 import { getConfig, setConfig } from "./config-store";
 import { notifyRoutingPolicyChanged } from "./routing-policy-push";
-import { isRecord, SPAWN_PROVIDERS } from "agent-relay-sdk";
-import type { ProviderQuotaRoutingConfig, QuotaBandThresholds, RoutingPolicy, RoutingRule } from "agent-relay-sdk";
+import {
+  isRecord,
+  SPAWN_PROVIDERS,
+  TASK_DISPATCH_COMPLEXITIES,
+  TASK_DISPATCH_CRITICALITIES,
+  TASK_DISPATCH_FOOTPRINTS,
+  TASK_DISPATCH_TYPES,
+} from "agent-relay-sdk";
+import type {
+  DispatchAutoReview,
+  DispatchMatch,
+  DispatchModelTarget,
+  DispatchPolicy,
+  DispatchRule,
+  ProviderQuotaRoutingConfig,
+  QuotaBandThresholds,
+  RoutingPolicy,
+  RoutingRule,
+} from "agent-relay-sdk";
 
 export const ROUTING_POLICY_NAMESPACE = "routing-policy";
 export const ROUTING_POLICY_KEY = "default";
@@ -21,6 +38,37 @@ export const DEFAULT_ROUTING_POLICY: RoutingPolicy = {
   rules: [],
 };
 
+/**
+ * #839 — built-in dispatch policy. Encodes the coordinator routing heuristics that used to
+ * live as tribal knowledge in memory files, so they are one inspectable + editable place that
+ * survives compaction. Used by the dispatcher whenever `RoutingPolicy.dispatch` is unset.
+ * Rules are evaluated top-down; the first match wins, so put the most specific rules first.
+ */
+export const DEFAULT_DISPATCH_POLICY: DispatchPolicy = {
+  rules: [
+    { label: "review → Codex (reviewer edge)", match: { type: "review" }, target: { provider: "codex", effort: "high" } },
+    { label: "debug → Codex high", match: { type: "debug" }, target: { provider: "codex", effort: "high" } },
+    { label: "ui → Sonnet", match: { type: "ui" }, target: { provider: "claude", model: "sonnet-4.6", effort: "medium" } },
+    { label: "complex build → Opus 4.8 high", match: { type: "build", complexity: "complex" }, target: { provider: "claude", model: "opus-4.8", effort: "high" } },
+    { label: "research → Opus 4.8 high", match: { type: "research" }, target: { provider: "claude", model: "opus-4.8", effort: "high" } },
+    { label: "refactor → Opus 4.8 medium", match: { type: "refactor" }, target: { provider: "claude", model: "opus-4.8", effort: "medium" } },
+    { label: "moderate build → Sonnet medium", match: { type: "build", complexity: "moderate" }, target: { provider: "claude", model: "sonnet-4.6", effort: "medium" } },
+    { label: "ops → Sonnet low", match: { type: "ops" }, target: { provider: "claude", model: "sonnet-4.6", effort: "low" } },
+    { label: "trivial → Sonnet low", match: { complexity: "trivial" }, target: { provider: "claude", model: "sonnet-4.6", effort: "low" } },
+  ],
+  fallback: { provider: "claude", model: "sonnet-4.6", effort: "medium" },
+  // Large footprint demands a 1M-window model; the dispatcher escalates same-family (e.g.
+  // opus-4.8 → opus-4.8[1m]) when the matched model's window is below this.
+  footprintMinContextTokens: { large: 1_000_000 },
+  // The winning build+review pattern, made automatic: high criticality OR complex builds get
+  // a dependent adversarial review Task, routed to Codex per the review rule above.
+  autoReview: {
+    whenCriticality: ["high"],
+    whenComplexity: ["complex"],
+    target: { provider: "codex", effort: "high" },
+  },
+};
+
 /** Retrieve the stored routing policy, falling back to the default when absent. */
 export function getRoutingPolicy(): RoutingPolicy {
   const entry = getConfig<RoutingPolicy>(ROUTING_POLICY_NAMESPACE, ROUTING_POLICY_KEY);
@@ -59,9 +107,106 @@ export function normalizeRoutingPolicy(value: unknown): RoutingPolicy {
     rules: normalizeRules(input.rules),
     ...(input.quotaBands !== undefined ? { quotaBands: normalizeQuotaBands(input.quotaBands) } : {}),
     ...(input.providerQuota !== undefined ? { providerQuota: normalizeProviderQuota(input.providerQuota) } : {}),
+    ...(input.dispatch !== undefined ? { dispatch: normalizeDispatchPolicy(input.dispatch) } : {}),
   };
 }
 
+// --- #839 dispatch-policy normalizer ---------------------------------------
+
+function normalizeDispatchTarget(raw: unknown, ctx: string): DispatchModelTarget {
+  if (!isRecord(raw)) throw new ValidationError(`${ctx} must be an object`);
+  if (typeof raw.provider !== "string" || !(SPAWN_PROVIDERS as readonly string[]).includes(raw.provider)) {
+    throw new ValidationError(`${ctx}.provider must be one of: ${SPAWN_PROVIDERS.join(", ")}`);
+  }
+  return {
+    provider: raw.provider as DispatchModelTarget["provider"],
+    ...(typeof raw.model === "string" && raw.model ? { model: raw.model } : {}),
+    ...(typeof raw.effort === "string" && raw.effort ? { effort: raw.effort } : {}),
+  };
+}
+
+// Preserves the input shape (scalar in → scalar out) so a stored policy round-trips identically
+// and no-op saves stay silent. Both forms are accepted by the dispatch matcher.
+function normalizeMatchDimension(raw: unknown, allowed: readonly string[], ctx: string): string | string[] | undefined {
+  if (raw === undefined) return undefined;
+  const values = Array.isArray(raw) ? raw : [raw];
+  for (const v of values) {
+    if (typeof v !== "string" || !allowed.includes(v)) {
+      throw new ValidationError(`${ctx} must be one of: ${allowed.join(", ")}`);
+    }
+  }
+  return (Array.isArray(raw) ? values : values[0]) as string | string[];
+}
+
+function normalizeDispatchMatch(raw: unknown, ctx: string): DispatchMatch {
+  if (!isRecord(raw)) throw new ValidationError(`${ctx} must be an object`);
+  const match: DispatchMatch = {};
+  const complexity = normalizeMatchDimension(raw.complexity, TASK_DISPATCH_COMPLEXITIES, `${ctx}.complexity`);
+  const type = normalizeMatchDimension(raw.type, TASK_DISPATCH_TYPES, `${ctx}.type`);
+  const footprint = normalizeMatchDimension(raw.contextFootprint, TASK_DISPATCH_FOOTPRINTS, `${ctx}.contextFootprint`);
+  const criticality = normalizeMatchDimension(raw.criticality, TASK_DISPATCH_CRITICALITIES, `${ctx}.criticality`);
+  if (complexity) match.complexity = complexity as DispatchMatch["complexity"];
+  if (type) match.type = type as DispatchMatch["type"];
+  if (footprint) match.contextFootprint = footprint as DispatchMatch["contextFootprint"];
+  if (criticality) match.criticality = criticality as DispatchMatch["criticality"];
+  return match;
+}
+
+function normalizeDispatchRule(raw: unknown, idx: number): DispatchRule {
+  if (!isRecord(raw)) throw new ValidationError(`dispatch.rules[${idx}] must be an object`);
+  const rule: DispatchRule = {
+    match: normalizeDispatchMatch(raw.match ?? {}, `dispatch.rules[${idx}].match`),
+    target: normalizeDispatchTarget(raw.target, `dispatch.rules[${idx}].target`),
+  };
+  if (typeof raw.label === "string" && raw.label) rule.label = raw.label;
+  if (typeof raw.enabled === "boolean") rule.enabled = raw.enabled;
+  return rule;
+}
+
+function normalizeAutoReview(raw: unknown): DispatchAutoReview {
+  if (!isRecord(raw)) throw new ValidationError("dispatch.autoReview must be an object");
+  const out: DispatchAutoReview = {};
+  const whenCriticality = normalizeMatchDimension(raw.whenCriticality, TASK_DISPATCH_CRITICALITIES, "dispatch.autoReview.whenCriticality");
+  const whenComplexity = normalizeMatchDimension(raw.whenComplexity, TASK_DISPATCH_COMPLEXITIES, "dispatch.autoReview.whenComplexity");
+  // These are always arrays (the dispatcher calls .includes); coerce a scalar form up.
+  if (whenCriticality !== undefined) out.whenCriticality = (Array.isArray(whenCriticality) ? whenCriticality : [whenCriticality]) as DispatchAutoReview["whenCriticality"];
+  if (whenComplexity !== undefined) out.whenComplexity = (Array.isArray(whenComplexity) ? whenComplexity : [whenComplexity]) as DispatchAutoReview["whenComplexity"];
+  if (raw.target !== undefined) out.target = normalizeDispatchTarget(raw.target, "dispatch.autoReview.target");
+  return out;
+}
+
+export function normalizeDispatchPolicy(raw: unknown): DispatchPolicy {
+  if (!isRecord(raw)) throw new ValidationError("dispatch must be an object");
+  if (!Array.isArray(raw.rules)) throw new ValidationError("dispatch.rules must be an array");
+  const policy: DispatchPolicy = {
+    rules: raw.rules.map((r, i) => normalizeDispatchRule(r, i)),
+    fallback: normalizeDispatchTarget(raw.fallback, "dispatch.fallback"),
+  };
+  if (raw.footprintMinContextTokens !== undefined) {
+    if (!isRecord(raw.footprintMinContextTokens)) throw new ValidationError("dispatch.footprintMinContextTokens must be an object");
+    const out: Partial<Record<string, number>> = {};
+    for (const band of TASK_DISPATCH_FOOTPRINTS) {
+      const v = raw.footprintMinContextTokens[band];
+      if (v === undefined) continue;
+      if (typeof v !== "number" || !Number.isFinite(v) || v <= 0) {
+        throw new ValidationError(`dispatch.footprintMinContextTokens.${band} must be a positive number`);
+      }
+      out[band] = v;
+    }
+    policy.footprintMinContextTokens = out as DispatchPolicy["footprintMinContextTokens"];
+  }
+  if (raw.autoReview !== undefined) policy.autoReview = normalizeAutoReview(raw.autoReview);
+  return policy;
+}
+
+/**
+ * The effective dispatch policy: the stored `RoutingPolicy.dispatch`, or the built-in
+ * {@link DEFAULT_DISPATCH_POLICY} when none is configured. The dispatcher reads this.
+ */
+export function getDispatchPolicy(): DispatchPolicy {
+  return getRoutingPolicy().dispatch ?? DEFAULT_DISPATCH_POLICY;
+}
+
 function normalizeRules(raw: unknown): RoutingRule[] {
   if (!Array.isArray(raw)) return [];
   const rules: RoutingRule[] = [];

package/src/security.ts

@@ -195,6 +195,8 @@ export function requiredScopeFor(method: string, pathname: string): string | nul
   if (pathname === "/api/tokens/me") return null;
   if (pathname.startsWith("/api/tokens") || pathname.startsWith("/api/token-profiles")) return method === "GET" ? "token:read" : "token:write";
   if (pathname.startsWith("/api/maintenance")) return "system:admin";
+  // Dispatch is spawn-class — requires command:spawn, not generic task:write (#845/#848).
+  if (pathname.match(/^\/api\/tasks\/[^/]+\/dispatch$/)) return "command:spawn";
   if (pathname.startsWith("/api/tasks")) return method === "GET" ? "task:read" : "task:write";
   if (pathname.startsWith("/api/pairs")) return method === "GET" ? "pairs:read" : "pairs:write";
   if (pathname === "/api/provider-quota-leases/acquire" || pathname === "/api/provider-quota-leases/release") return "quota:write";
@@ -304,6 +306,8 @@ export function requiredComponentScopeFor(method: string, pathname: string): str
   if (pathname.startsWith("/api/messages") || pathname.startsWith("/api/inbox")) return method === "GET" ? "message:read" : "message:send";
   if (pathname.startsWith("/api/agent-profiles")) return method === "GET" ? "agent:read" : "agent:write";
   if (pathname.startsWith("/api/provisioning")) return method === "GET" ? "provisioning:read" : "provisioning:write";
+  // Dispatch is spawn-class — requires command:spawn, not generic task:write (#845/#848).
+  if (pathname.match(/^\/api\/tasks\/[^/]+\/dispatch$/)) return "command:spawn";
   if (pathname.startsWith("/api/tasks")) return method === "GET" ? "task:read" : "task:write";
   if (pathname.startsWith("/api/orchestrators")) return method === "GET" ? "agent:read" : "command:write";
   if (pathname.startsWith("/api/plans")) return method === "GET" ? "plans:read" : "plans:write";

package/src/self-resume.ts

@@ -14,7 +14,7 @@ import {
 import { emitRelayEvent } from "./events";
 import { routeNotification } from "./notification-router";
 import { renderTemplate } from "./prompt-resolver";
-import type { AgentCard, Command, ContinuationEnvelope, ContinuationLedgerEntry, SelfResumeMode } from "./types";
+import type { AgentCard, Command, ContinuationDecisionEntry, ContinuationEnvelope, ContinuationLedgerEntry, SelfResumeMode } from "./types";
 
 interface CompactAndResumeInput {
   agentId: string;
@@ -146,19 +146,30 @@ export function enqueueContinuationInjectionAfterClear(command: Command): Comman
   return enqueueContinuationInjectionAfterSelfResume(command);
 }
 
-function renderContinuation(envelope: ContinuationEnvelope): string {
+export function renderContinuation(
+  envelope: ContinuationEnvelope,
+  input: { intro?: string } = {},
+): string {
   const ledger = envelope.ledger.length
     ? envelope.ledger.map((entry) => `- gen ${entry.gen} @ ${new Date(entry.at).toISOString()}: ${entry.ruledOut}${entry.why ? `; why: ${entry.why}` : ""}`).join("\n")
     : "- none";
+  const decisions = envelope.decisions.length ? envelope.decisions.map(renderDecisionEntry).join("\n") : "- none";
   return renderTemplate("continuation.envelope", {
+    intro: input.intro ?? `You have been resumed by Agent Relay — generation ${envelope.generation}.`,
     generation: String(envelope.generation),
     objective: envelope.objective,
     ruledOut: ledger,
+    decisions,
     workingState: envelope.workingState,
     archiveRefs: envelope.archiveRefs.length ? envelope.archiveRefs.join("\n") : "- none",
   });
 }
 
+function renderDecisionEntry(entry: ContinuationDecisionEntry): string {
+  const by = entry.by ? ` · ${entry.by}` : "";
+  return `- gen ${entry.gen} @ ${new Date(entry.at).toISOString()}${by}: ${entry.decision}${entry.rationale ? `; rationale: ${entry.rationale}` : ""}`;
+}
+
 function assertResumeSupported(agent: AgentCard, mode: SelfResumeMode): void {
   const context = agent.providerCapabilities?.context;
   const resume = context?.resume ?? (context?.clear && context?.inject ? "clear-inject" : "none");

package/src/services/issue-lifecycle.ts

@@ -1,5 +1,5 @@
 import { errMessage } from "agent-relay-sdk";
-import { getAgent, listPlansWithBoundOwner } from "../db";
+import { getAgent, listPlansWithBoundOwner, deliverableTaskIdsByBranch } from "../db";
 import { listIssuesForEntity, planNodeIssueEntityId } from "../db/issue-associations";
 import {
   getSuccessfulIssueLifecycleAction,
@@ -142,6 +142,14 @@ function associatedIssueRefs(workspace: LifecycleWorkspace): IssueRef[] {
       }
     }
   }
+  // #834 — task-aware resolution: a deliverable Task owns its branch, so the landed branch
+  // resolves to its linked issue(s). This is the resolution PATH; lifecycle automation that
+  // advances the Task itself on land is #831.
+  if (workspace.branch) {
+    for (const taskId of deliverableTaskIdsByBranch(workspace.branch)) {
+      refs.push(...listIssuesForEntity("task", String(taskId)).map((item) => item.issueRef));
+    }
+  }
   return issueRefMap(refs);
 }