agent-relay-server 0.108.0 → 0.110.0

package/src/mcp-dispatch-tools.ts

@@ -9,7 +9,7 @@
 import { McpNotFoundError } from "./mcp-errors";
 import { ValidationError } from "./db";
 import { authContextFromMcp } from "./services/auth-context";
-import { addTaskEntityDependency, createTaskEntity, getTaskEntity } from "./services/task-entity";
+import { addTaskEntityDependency, createTaskEntity, getTaskEntity, recordTaskEntityDispatchDecision } from "./services/task-entity";
 import { dispatchTask, type DispatchPin } from "./task-dispatcher";
 import { cleanString } from "./validation";
 import {
@@ -75,7 +75,7 @@ function taskIdArg(value: unknown): number {
   return n;
 }
 
-function pinArg(value: unknown): DispatchPin {
+export function pinArg(value: unknown): DispatchPin {
   if (value === undefined || value === null) return {};
   if (!isRecord(value)) throw new ValidationError("pin must be an object");
   const pin: DispatchPin = {};
@@ -93,7 +93,7 @@ function pinArg(value: unknown): DispatchPin {
   return pin;
 }
 
-function dispatchShapeArg(value: unknown): TaskDispatch | undefined {
+export function dispatchShapeArg(value: unknown): TaskDispatch | undefined {
   if (value === undefined || value === null) return undefined;
   if (!isRecord(value)) throw new ValidationError("dispatch must be an object");
   return value as TaskDispatch;
@@ -108,37 +108,49 @@ function findExistingReviewDependent(dependentIds: number[]): number | undefined
   return undefined;
 }
 
-export function relayDispatchTool(auth: McpAuthLike, name: string, args: Record<string, unknown>): Record<string, unknown> {
-  const actor = authContextFromMcp(auth).actor.id;
-  if (!isRecord(args)) throw new ValidationError("arguments must be an object");
-  if (name !== "relay_task_dispatch") throw new ValidationError(`unknown tool: ${name}`);
+export interface RunTaskDispatchInput {
+  taskId?: number;
+  dispatch?: TaskDispatch;
+  pin?: DispatchPin;
+  createReview?: boolean;
+  actor: string;
+}
 
-  const hasTaskId = args.taskId !== undefined && args.taskId !== null;
-  const taskId = hasTaskId ? taskIdArg(args.taskId) : undefined;
-  const inlineShape = dispatchShapeArg(args.dispatch);
+export interface RunTaskDispatchResult {
+  taskId?: number;
+  decision: ReturnType<typeof dispatchTask>;
+  reviewTaskId?: number;
+}
+
+/**
+ * Core dispatch logic shared between the MCP tool (relay_task_dispatch) and the HTTP route
+ * (POST /api/tasks/:id/dispatch). Both paths call this function — do NOT fork it (#845).
+ */
+export function runTaskDispatch(input: RunTaskDispatchInput): RunTaskDispatchResult {
+  const { taskId, dispatch: inlineShape, pin = {}, createReview = true, actor } = input;
 
   let parentTitle: string | undefined;
   let parentTeamId: string | undefined;
   let parentDependents: number[] = [];
   let shape = inlineShape;
+
   if (taskId !== undefined) {
     const task = getTaskEntity(taskId);
     if (!task) throw new McpNotFoundError("task not found");
     parentTitle = task.title;
     parentTeamId = task.teamId;
     parentDependents = task.dependents;
-    // Inline dispatch (if supplied) overrides the stored work-shape for this call.
     shape = inlineShape ?? task.dispatch;
   }
   if (!shape && !inlineShape) shape = {};
 
-  const decision = dispatchTask(shape, pinArg(args.pin));
+  const decision = dispatchTask(shape, pin);
+  if (taskId !== undefined) {
+    recordTaskEntityDispatchDecision(taskId, { decision, source: "dispatch", actor });
+  }
 
   let reviewTaskId: number | undefined;
-  const createReview = args.createReview !== false; // default true
   if (decision.review && createReview && taskId !== undefined) {
-    // Idempotent: if this build Task already has a review dependent, reuse it rather than
-    // spawning a duplicate on every re-dispatch.
     const existing = findExistingReviewDependent(parentDependents);
     if (existing !== undefined) {
       reviewTaskId = existing;
@@ -150,7 +162,6 @@ export function relayDispatchTool(auth: McpAuthLike, name: string, args: Record<
         createdBy: actor,
         ...(parentTeamId ? { teamId: parentTeamId } : {}),
       });
-      // The review Task depends on the build Task (build must complete first).
       addTaskEntityDependency(review.id, taskId, actor);
       reviewTaskId = review.id;
     }
@@ -158,7 +169,28 @@ export function relayDispatchTool(auth: McpAuthLike, name: string, args: Record<
 
   return {
     ...(taskId !== undefined ? { taskId } : {}),
-    decision: decision as unknown as Record<string, unknown>,
+    decision,
     ...(reviewTaskId !== undefined ? { reviewTaskId } : {}),
   };
 }
+
+export function relayDispatchTool(auth: McpAuthLike, name: string, args: Record<string, unknown>): Record<string, unknown> {
+  const actor = authContextFromMcp(auth).actor.id;
+  if (!isRecord(args)) throw new ValidationError("arguments must be an object");
+  if (name !== "relay_task_dispatch") throw new ValidationError(`unknown tool: ${name}`);
+
+  const hasTaskId = args.taskId !== undefined && args.taskId !== null;
+  const result = runTaskDispatch({
+    taskId: hasTaskId ? taskIdArg(args.taskId) : undefined,
+    dispatch: dispatchShapeArg(args.dispatch),
+    pin: pinArg(args.pin),
+    createReview: args.createReview !== false,
+    actor,
+  });
+
+  return {
+    ...(result.taskId !== undefined ? { taskId: result.taskId } : {}),
+    decision: result.decision as unknown as Record<string, unknown>,
+    ...(result.reviewTaskId !== undefined ? { reviewTaskId: result.reviewTaskId } : {}),
+  };
+}

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

@@ -1,10 +1,6 @@
-import { stringValue } from "agent-relay-sdk";
 import {
   appendTaskMemoryDecision,
   appendTaskMemoryRuledOut,
-  deliverableTaskIdsByOwnerAgent,
-  deliverableTaskIdsBySpawnRequestId,
-  getAgent,
   readTaskMemoryEnvelope,
   replaceTaskMemoryWorkingState,
   ValidationError,
@@ -13,6 +9,7 @@ import { McpAuthError } from "./mcp-errors";
 import { callerAgentId } from "./mcp/identity";
 import { optionalPositiveInt, stringField } from "./mcp/validation";
 import { renderContinuation } from "./self-resume";
+import { agentBoundTaskIds, hasTaskReadAdminScope } from "./task-authz";
 import type { McpAuthContext, ToolDefinition } from "./mcp/types";
 
 const TASK_ID_PROP = { type: "integer", minimum: 1, description: "Task id. Optional when the caller is bound to exactly one Task." } as const;
@@ -96,11 +93,12 @@ export function relayTaskMemoryTool(auth: McpAuthContext, name: string, args: Re
 
 function resolveTaskId(auth: McpAuthContext, args: Record<string, unknown>): number {
   const explicit = optionalPositiveInt(args.taskId, "taskId");
-  const ids = boundTaskIds(auth);
+  const agentId = callerAgentId(auth);
+  const ids = agentId ? agentBoundTaskIds(agentId) : new Set<number>();
   if (explicit !== undefined) {
     // Deliberate privileged escape hatch: admin/server tooling can inspect or repair any
     // task memory row, but ordinary provider tokens must be bound to the explicit task id.
-    if (hasTaskMemoryAdminScope(auth) || ids.has(explicit)) return explicit;
+    if (hasTaskReadAdminScope(auth.scopes) || ids.has(explicit)) return explicit;
     throw new McpAuthError("taskId is not bound to the caller");
   }
   if (ids.size === 1) return [...ids][0]!;
@@ -108,21 +106,6 @@ function resolveTaskId(auth: McpAuthContext, args: Record<string, unknown>): num
   throw new McpAuthError("caller is bound to multiple Tasks; pass taskId explicitly");
 }
 
-function boundTaskIds(auth: McpAuthContext): Set<number> {
-  const agentId = callerAgentId(auth);
-  if (!agentId) return new Set();
-  const ids = new Set<number>(deliverableTaskIdsByOwnerAgent(agentId));
-  const spawnRequestId = stringValue(getAgent(agentId)?.meta?.spawnRequestId);
-  if (spawnRequestId) {
-    for (const id of deliverableTaskIdsBySpawnRequestId(spawnRequestId)) ids.add(id);
-  }
-  return ids;
-}
-
-function hasTaskMemoryAdminScope(auth: McpAuthContext): boolean {
-  return auth.scopes.includes("*") || auth.scopes.includes("admin:*") || auth.scopes.includes("system:admin") || auth.scopes.includes("task:admin");
-}
-
 function response(envelope: ReturnType<typeof readTaskMemoryEnvelope>): Record<string, unknown> {
   return {
     taskId: envelope.taskId,

package/src/routes/agents-spawn.ts

@@ -1,5 +1,5 @@
 // Auto-split from routes.ts (#299). Domain: agents-spawn.
-import { APPROVAL_MODES, AUTO_MERGE_POLICIES, SPAWN_PROVIDERS, VALID_WORKSPACE_MODES, isRecord } from "agent-relay-sdk";
+import { APPROVAL_MODES, AUTO_MERGE_POLICIES, SPAWN_PROVIDERS, VALID_AGENT_LIFECYCLES, VALID_WORKSPACE_MODES, isRecord } from "agent-relay-sdk";
 import { McpAuthError, McpNotFoundError } from "../mcp-errors";
 import { VALID_AGENT_STATUSES, error, json, parseBody, type Handler } from "./_shared";
 import { ValidationError, listAgents } from "../db";
@@ -15,7 +15,7 @@ import { authContextFromRequest } from "../services/auth-context";
 import { listHostDirectories } from "../agent-spawn";
 import { rankRouteCandidates, type RouteAdvisorInput } from "../context-router";
 import { quotaStateFromUnknown } from "../quota";
-import { type AgentKind, type RegisterAgentInput, type SpawnApprovalMode, type SpawnProvider, type WorkspaceAutoMergePolicy, type WorkspaceLandingPolicy, type WorkspaceMode } from "../types";
+import { type AgentKind, type AgentLifecycle, type RegisterAgentInput, type SpawnApprovalMode, type SpawnProvider, type WorkspaceAutoMergePolicy, type WorkspaceLandingPolicy, type WorkspaceMode } from "../types";
 import { type ProviderEffort } from "agent-relay-sdk/provider-catalog";
 
 const VALID_AGENT_KINDS = ["provider", "channel", "orchestrator", "system", "user"] as const;
@@ -128,6 +128,7 @@ export const postAgentSpawn: Handler = async (req) => {
       effort: cleanString(parsed.body.effort, "effort", { max: 120 }) as ProviderEffort | undefined,
       approvalMode: optionalEnum(parsed.body.approvalMode, "approvalMode", APPROVAL_MODES) as SpawnApprovalMode | undefined,
       workspaceMode: optionalEnum(parsed.body.workspaceMode, "workspaceMode", VALID_WORKSPACE_MODES) as WorkspaceMode | undefined,
+      lifecycle: optionalEnum(parsed.body.lifecycle, "lifecycle", VALID_AGENT_LIFECYCLES) as AgentLifecycle | undefined,
       label: cleanString(parsed.body.label, "label", { max: 120 }),
       policyName: cleanString(parsed.body.policyName, "policyName", { max: 120 }),
       profile: cleanString(parsed.body.profile, "profile", { max: 120 }),

package/src/routes/agents.ts

@@ -7,6 +7,7 @@ import { cleanStringArray } from "../validation";
 import { clearActiveMemories, memoryBroker } from "../memory-service";
 import { emitAgentRemoved, emitAgentStatus } from "../sse";
 import { notifyAgentReady } from "../agent-lifecycle-events";
+import { bindSpawnedTaskToReadyAgent } from "../services/register-agent";
 import { flushQueuedDirectMessages } from "../services/managed-running";
 import { isAgentUnavailable } from "../db/agent-predicates";
 import { getCompactionWatch } from "../compaction-watch";
@@ -299,6 +300,7 @@ export const patchAgentReady: Handler = async (req, params) => {
     // agents and dedups repeat readies.
     if (body.ready && !before?.ready) {
       notifyAgentReady(params.id!);
+      bindSpawnedTaskToReadyAgent(params.id!, "agent-ready");
       // #416 — also flush queued direct messages: a not-ready agent that becomes ready
       // may have queued messages waiting (e.g. starting up, clearing context).
       flushQueuedDirectMessages(params.id!);

package/src/routes/index.ts

@@ -45,7 +45,7 @@ import { getRecipeByName, getRecipeInstanceArtifacts, getRecipeInstanceById, get
 import { getSettingRoute, getSettingsNamespaceRoute, getSettingsRoute, putSettingRoute, putSettingsDefaultRoute } from "./settings";
 import { postNotificationPreviewRoute } from "./notifications";
 import { getStewardConfigRoute, getWorkspaceConfigRoute, putStewardConfigRoute, putWorkspaceConfigRoute } from "./steward";
-import { getTaskById, getTaskEvents, getTasks, patchTaskStatus, postClaimTask, postRenewTaskClaim, postTaskCreate, getTaskDetailRoute, patchTaskEntity, postTaskEntityStatus, postTaskEntityStage, postTaskEntityGate, postTaskDependency, deleteTaskDependency, postTaskRef, deleteTaskRef, postTaskAssign, postTaskComment, getTaskCloseBridge } from "./tasks";
+import { getTaskById, getTaskEntities, getTaskEvents, getTasks, patchTaskStatus, postClaimTask, postRenewTaskClaim, postTaskCreate, getTaskDetailRoute, getTaskMemoryRoute, getTaskHistoryRoute, patchTaskEntity, postTaskEntityStatus, postTaskEntityStage, postTaskEntityGate, postTaskDependency, deleteTaskDependency, postTaskRef, deleteTaskRef, postTaskAssign, postTaskComment, getTaskCloseBridge, postTaskDispatch } from "./tasks";
 import { getMyTeamRoute, getTeamOutcomesRoute, getTeamsRoute, postMyTeamDissolveRoute, putMyTeamBriefRoute } from "./teams";
 import { postTeamDissolveByIdRoute } from "./teams";
 import { deleteTeamTemplateRoute, getTeamTemplateRoute, getTeamTemplatesRoute, postTeamTemplateRoute, putTeamTemplateRoute } from "./team-templates";
@@ -350,10 +350,13 @@ const routes: Route[] = [
   route("PATCH", "/api/automations/:id", patchAutomation),
   route("DELETE", "/api/automations/:id", deleteAutomationById),
   route("POST", "/api/automations/:id/run", postAutomationRun),
+  route("GET", "/api/task-entities", getTaskEntities),
   route("GET", "/api/tasks", getTasks),
   route("POST", "/api/tasks", postTaskCreate),
   route("GET", "/api/tasks/:id", getTaskById),
   route("GET", "/api/tasks/:id/detail", getTaskDetailRoute),
+  route("GET", "/api/tasks/:id/memory", getTaskMemoryRoute),
+  route("GET", "/api/tasks/:id/history", getTaskHistoryRoute),
   route("GET", "/api/tasks/:id/artifacts", getTaskArtifactsRoute),
   route("GET", "/api/tasks/:id/events", getTaskEvents),
   route("POST", "/api/tasks/:id/claim", postClaimTask),
@@ -370,6 +373,7 @@ const routes: Route[] = [
   route("POST", "/api/tasks/:id/assign", postTaskAssign),
   route("POST", "/api/tasks/:id/comments", postTaskComment),
   route("GET", "/api/tasks/:id/close-bridge", getTaskCloseBridge),
+  route("POST", "/api/tasks/:id/dispatch", postTaskDispatch),
 
   route("POST", "/api/pairs", postPair),
   route("GET", "/api/pairs", getPairs),

package/src/routes/messages.ts

@@ -162,12 +162,12 @@ export const postMessage: Handler = async (req) => {
       // injection needs request-derived context; the "message sent" audit is the HTTP domain row.
       const autoMemoryTarget = automaticMemoryTarget(message);
       if (autoMemoryTarget) {
-        try {
-          const memoryInjection = await injectMemoryForMessageDelivery(message, autoMemoryTarget, memoryContext(req));
-          if (memoryInjection) emitCommand(memoryInjection.command);
-        } catch (e) {
-          console.warn(`[memory] automatic message context assembly failed: ${errMessage(e)}`);
-        }
+        // Fire-and-forget: capture context synchronously then inject off the response path so
+        // POST latency is not gated on memory assembly (A1 fix, #847).
+        const ctx = memoryContext(req);
+        void injectMemoryForMessageDelivery(message, autoMemoryTarget, ctx)
+          .then((memoryInjection) => { if (memoryInjection) emitCommand(memoryInjection.command); })
+          .catch((e) => { console.warn(`[memory] automatic message context assembly failed: ${errMessage(e)}`); });
       }
       const isWork = message.kind === "task";
       auditEvent({

package/src/routes/tasks.ts

@@ -1,10 +1,15 @@
 // 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, resolveActorLabel, type Handler } from "./_shared";
+import { getComponentAuth, isFullReachRequest } from "../security";
+import { authContextFromRequest } from "../services/auth-context";
+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, updateTaskEntity,
+  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";
@@ -14,7 +19,9 @@ import { errMessage, isRecord, TASK_DELIVERABLE_STAGES, type TaskBlocker, type T
 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");
+  if (typeof fallback === "string" && fallback.trim()) return fallback.trim();
+  const ctx = authContextFromRequest(req);
+  return ctx.callerAgentId ?? resolveActorLabel(req) ?? (ctx.actor.id !== "system" ? ctx.actor.id : "dashboard");
 }
 
 function taskDetailOr404(id: number) {
@@ -61,6 +68,18 @@ export const getTasks: Handler = (req) => {
   }));
 };
 
+export const getTaskEntities: 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");
+  return json(listTaskEntities({
+    status: url.searchParams.get("status") ?? undefined,
+    deliverableStage: url.searchParams.get("deliverableStage") ?? undefined,
+    teamId: url.searchParams.get("teamId") ?? undefined,
+    limit: limitRaw ?? 100,
+  }));
+};
+
 // --- #834 durable Task entity (kind='deliverable') HTTP surface ---
 
 export const postTaskCreate: Handler = async (req) => {
@@ -101,6 +120,28 @@ export const getTaskDetailRoute: Handler = (_req, params) => {
   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");
@@ -291,6 +332,39 @@ export const postTaskComment: Handler = async (req, params) => {
   }
 };
 
+// #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 (!isFullReachRequest(req) && !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);

package/src/runtime-tokens.ts

@@ -94,6 +94,7 @@ export function issueRunnerRuntimeToken(input: {
   label?: string;
   policyName?: string;
   spawnRequestId?: string;
+  taskId?: number;
   createdBy?: string;
   /**
    * Agent profile name. The spawn grant (the `command:spawn`/`command:shutdown` scope + the
@@ -128,6 +129,7 @@ export function issueRunnerRuntimeToken(input: {
       cwdPrefixes: [input.cwd],
       ...(input.policyName ? { policies: [input.policyName] } : {}),
       ...(input.spawnRequestId ? { spawnRequestIds: [input.spawnRequestId] } : {}),
+      ...(input.taskId !== undefined ? { taskIds: [String(input.taskId)] } : {}),
       ...(grant.canSpawn && grant.maxSpawnedAgents ? { maxSpawnedAgents: grant.maxSpawnedAgents } : {}),
       ...(input.spawnedBy ? { spawnedBy: input.spawnedBy } : {}),
       ...(input.teamId ? { teamId: input.teamId } : {}),
@@ -250,6 +252,7 @@ export function runnerRuntimeTokenEnv(input: {
   label?: string;
   policyName?: string;
   spawnRequestId?: string;
+  taskId?: number;
   createdBy?: string;
   /** Agent profile name — spawn grant is resolved from it in the mint (see issueRunnerRuntimeToken). */
   profile?: string;
@@ -266,6 +269,7 @@ export function runnerRuntimeTokenEnv(input: {
     AGENT_RELAY_TOKEN_JTI: issued.record.jti,
     AGENT_RELAY_TOKEN_PROFILE: issued.record.profileId ?? "provider-agent",
     ...(issued.record.expiresAt ? { AGENT_RELAY_TOKEN_EXPIRES_AT: String(issued.record.expiresAt) } : {}),
+    ...(input.taskId !== undefined ? { AGENT_RELAY_TASK_ID: String(input.taskId) } : {}),
   };
 }
 

package/src/security.ts

@@ -87,6 +87,10 @@ export function isAuthorized(req: Request): boolean {
   return Boolean(presented && verifyComponentToken(presented));
 }
 
+export function isFullReachRequest(req: Request): boolean {
+  return Boolean(extractToken(req)) && isAuthorized(req) && !getComponentAuth(req) && !getIntegrationAuth(req);
+}
+
 type IntegrationAuth = IntegrationTokenConfig;
 
 type AuthorizationResource = {
@@ -195,6 +199,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 +310,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/services/register-agent.ts

@@ -9,8 +9,8 @@
 // managed came-up-running reconcile (delegated to managed-running.ts), the single
 // status broadcast, the single timeline note, the spawned-child parent-wake, and
 // the first-registration audit row.
-import { isReservedAgentId } from "agent-relay-sdk";
-import { ValidationError, createActivityEvent, getAgent, seedSpawnPromptMirror, seedSpawnReplyObligation, upsertAgent } from "../db";
+import { errMessage, isReservedAgentId } from "agent-relay-sdk";
+import { ValidationError, createActivityEvent, deliverableTaskIdsBySpawnRequestId, getAgent, getTaskDetail, seedSpawnPromptMirror, seedSpawnReplyObligation, upsertAgent } from "../db";
 import { emitAgentStatus, emitNewMessage } from "../sse";
 import { noteAgentTimelineEvent } from "../compaction-watch";
 import { agentProviderTimelineEvent } from "../provider-timeline-event";
@@ -19,6 +19,7 @@ import { resolveSpawnLineage, resolveTeamLineage } from "../security";
 import { flushQueuedDirectMessages, markManagedAgentRunning } from "./managed-running";
 import { isAgentUnavailable } from "../db/agent-predicates";
 import { recordSpawnPromptIssueActivity } from "./spawn-issue-activity";
+import { assignTaskEntityAgent, setTaskEntityStatus } from "./task-entity";
 import type { AuthContext } from "./auth-context";
 import type { AgentCard, RegisterAgentInput } from "../types";
 
@@ -27,6 +28,48 @@ function metaStr(meta: Record<string, unknown> | undefined, key: string): string
   return typeof value === "string" && value.length > 0 ? value : undefined;
 }
 
+function metaTaskId(meta: Record<string, unknown> | undefined): number | undefined {
+  const value = meta?.taskId;
+  const parsed = typeof value === "string" ? Number(value) : value;
+  return typeof parsed === "number" && Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined;
+}
+
+function taskIdsForReadyAgent(agent: AgentCard): number[] {
+  const ids = new Set<number>();
+  const directTaskId = metaTaskId(agent.meta);
+  if (directTaskId !== undefined) ids.add(directTaskId);
+  const spawnRequestId = metaStr(agent.meta, "spawnRequestId");
+  if (spawnRequestId) {
+    for (const id of deliverableTaskIdsBySpawnRequestId(spawnRequestId)) ids.add(id);
+  }
+  return [...ids].sort((a, b) => a - b);
+}
+
+export function bindSpawnedTaskToReadyAgent(agentId: string, actor = "agent-relay"): void {
+  const agent = getAgent(agentId);
+  if (!agent?.ready) return;
+  const taskIds = taskIdsForReadyAgent(agent);
+  for (const taskId of taskIds) {
+    try {
+      const before = getTaskDetail(taskId);
+      if (!before) continue;
+      if (before.ownerAgentId && before.ownerAgentId !== agent.id) continue;
+      const assigned = before.ownerAgentId === agent.id
+        ? before
+        : assignTaskEntityAgent(taskId, agent.id, "worker", agent.spawnedBy ?? actor);
+      if (assigned.status === "open" || assigned.status === "claimed") {
+        setTaskEntityStatus(taskId, {
+          status: "in_progress",
+          note: `worker ${agent.id} ready`,
+          actor: agent.spawnedBy ?? actor,
+        });
+      }
+    } catch (error) {
+      console.warn(`task ${taskId} ready binding skipped for ${agent.id}: ${errMessage(error)}`);
+    }
+  }
+}
+
 export function registerAgent(input: RegisterAgentInput, ctx: AuthContext): AgentCard {
   // Reserved built-in identities — the `system` lifecycle sender and the whole `user:` human
   // namespace (legacy bare `'user'`, `user:default`, every `user:<id>`) — are mechanical sinks,
@@ -73,6 +116,7 @@ export function registerAgent(input: RegisterAgentInput, ctx: AuthContext): Agen
   // case) wakes its block-polling parent. Fire on the first-ever ready, regardless of
   // transport. notifyAgentReady no-ops for non-spawned agents and dedups repeats.
   if (agent.ready && !existing?.ready) notifyAgentReady(agent.id);
+  if (agent.ready && !existing?.ready) bindSpawnedTaskToReadyAgent(agent.id, ctx.actor.id);
 
   // #416 — flush queued direct messages when a re-registering agent was previously unavailable
   // (stale, compacting, blocked) or a new agent becomes ready. No-op for brand-new agents