agent-relay-server 0.109.0 → 0.110.0

package/src/bus.ts

@@ -7,7 +7,7 @@ import { getCommand, updateCommand } from "./commands-db";
 import { emitCommandEvent } from "./command-events";
 import { noteAgentTimelineEvent, noteCompactionCommandCompleted } from "./compaction-watch";
 import { reconcileTerminalProviderExit } from "./services/terminal-provider-exit";
-import { registerAgent } from "./services/register-agent";
+import { bindSpawnedTaskToReadyAgent, registerAgent } from "./services/register-agent";
 import { authContextFromBus } from "./services/auth-context";
 import { commandAuthorizationResource, dispatchCommand } from "./services/dispatch-command";
 import { auditProviderStateTransition } from "./services/provider-state-audit";
@@ -182,6 +182,7 @@ function handleFrame(ws: BusWebSocket, frame: ReturnType<typeof validateClientFr
         if (!setStatus(conn.agentId, frame.payload.agentStatus, guard)) {
           return sendError(ws, frame.id, "AGENT_NOT_FOUND", "agent not found");
         }
+        const readyTransition = frame.payload.ready === true && !before?.ready;
         if (frame.payload.ready !== undefined && !markReady(conn.agentId, frame.payload.ready, guard)) {
           return sendError(ws, frame.id, "AGENT_NOT_FOUND", "agent not found");
         }
@@ -192,6 +193,7 @@ function handleFrame(ws: BusWebSocket, frame: ReturnType<typeof validateClientFr
         auditProviderStateTransition(conn.agentId, before, after);
         const timelineEvent = agentProviderTimelineEvent(after);
         auditRunnerTimelineEvent(conn.agentId, timelineEvent);
+        if (readyTransition) bindSpawnedTaskToReadyAgent(conn.agentId, "bus-ready");
         // A real PreCompact/SessionStart hook arrives as a timelineEvent in the
         // merged meta — clears any pending stall watch (stale events ignored).
         noteAgentTimelineEvent(conn.agentId, timelineEvent);

package/src/db/merge-lease.ts

@@ -231,7 +231,11 @@ export function acquireMergePause(input: {
 
 export function renewMergePause(id: string, ttlMs: number = MAIN_MERGE_PAUSE_TTL_MS, now: number = Date.now()): MergePauseRecord | null {
   const current = getMergePause(id);
-  if (!current || current.expiresAt <= now) return null;
+  if (!current) return null;
+  // Re-establish even when the pause has just expired: the maintenance reaper runs on a
+  // ~60s cadence, so a tardy renew that arrives before the sweep can still extend the
+  // hold. Returns null only when the record is already gone (reaped or replaced by a
+  // concurrent acquirer via ON CONFLICT UPDATE, which changes the row id).
   getDb().query("UPDATE workspace_merge_pauses SET updated_at = ?, expires_at = ? WHERE id = ?").run(now, now + ttlMs, id);
   return getMergePause(id);
 }

package/src/db/task-detail-projection.ts

@@ -0,0 +1,66 @@
+import type {
+  TaskDetail,
+  TaskDispatch,
+  TaskDispatchDecisionProjection,
+  TaskDispatchWorkShapeProjection,
+} from "../types";
+import { parseJson } from "../utils";
+import { getAgent } from "./agents.ts";
+import { getDb } from "./connection.ts";
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function taskDispatchWorkShape(dispatch: TaskDispatch | undefined): TaskDispatchWorkShapeProjection {
+  return {
+    specified: dispatch !== undefined,
+    complexity: dispatch?.complexity ?? null,
+    type: dispatch?.type ?? null,
+    contextFootprint: dispatch?.contextFootprint ?? null,
+    criticality: dispatch?.criticality ?? null,
+  };
+}
+
+export function latestTaskDispatchDecision(id: number): TaskDispatchDecisionProjection | undefined {
+  const row = getDb().query(`
+    SELECT source, metadata, created_at FROM task_events
+    WHERE task_id = ? AND type = 'dispatch.resolved'
+    ORDER BY id DESC LIMIT 1
+  `).get(id) as { source: string; metadata: string; created_at: number } | undefined;
+  if (!row) return undefined;
+  const meta = parseJson<Record<string, unknown>>(row.metadata, {});
+  const decision = isObject(meta.decision) ? meta.decision : {};
+  const target = isObject(decision.target) ? decision.target : {};
+  const warnings = Array.isArray(decision.warnings)
+    ? decision.warnings.filter((item): item is string => typeof item === "string")
+    : [];
+  return {
+    target: {
+      ...(typeof target.provider === "string" ? { provider: target.provider } : {}),
+      ...(typeof target.model === "string" ? { model: target.model } : {}),
+      ...(typeof target.effort === "string" ? { effort: target.effort } : {}),
+    },
+    rationale: typeof decision.rationale === "string" ? decision.rationale : row.source,
+    pinned: decision.pinned === true,
+    ...(isObject(decision.factors) ? { factors: decision.factors } : {}),
+    warnings,
+    source: typeof meta.source === "string" ? meta.source : row.source,
+    decidedAt: row.created_at,
+  };
+}
+
+export function taskBoundWorkerModel(agentId: string | undefined): TaskDetail["boundWorkerModel"] {
+  if (!agentId) return undefined;
+  const agent = getAgent(agentId);
+  const model = agent?.providerCapabilities?.model;
+  return {
+    agentId,
+    ...(typeof model?.provider === "string" ? { provider: model.provider } : {}),
+    ...(typeof model?.id === "string" ? { model: model.id } : typeof model?.alias === "string" ? { model: model.alias } : {}),
+    ...(typeof model?.effort === "string" ? { effort: model.effort } : {}),
+    ...(typeof model?.source === "string" ? { source: model.source } : {}),
+    ...(typeof model?.confidence === "string" ? { confidence: model.confidence } : {}),
+    ...(typeof model?.lastUpdatedAt === "number" ? { lastUpdatedAt: model.lastUpdatedAt } : {}),
+  };
+}

package/src/db/task-entity.ts

@@ -28,6 +28,7 @@ import {
 import { parseJson } from "../utils";
 import { getDb, ValidationError } from "./connection.ts";
 import { rowToTask } from "./mappers.ts";
+import { latestTaskDispatchDecision, taskBoundWorkerModel, taskDispatchWorkShape } from "./task-detail-projection.ts";
 import { TASK_SELECT, insertTaskEvent, DELIVERABLE_TASK_KIND } from "./task-core.ts";
 import { associateIssue, listIssuesForEntity, removeAssociation } from "./issue-associations.ts";
 import { resolveIssueRefFromString } from "./issue-refs.ts";
@@ -483,6 +484,18 @@ export interface RecordTaskSpawnInput {
   steer?: string;
 }
 
+export interface RecordTaskDispatchDecisionInput {
+  decision: {
+    target?: unknown;
+    rationale?: string;
+    pinned?: boolean;
+    factors?: unknown;
+    warnings?: readonly unknown[];
+  };
+  source: string;
+  actor: string;
+}
+
 // Idempotent by spawnRequestId: a retried spawn (orchestrator re-dispatch, client retry) reusing
 // the SAME spawnRequestId must NOT append a second attribution event. The append-only `task_events`
 // is the ledger, so we check-before-insert on the spawnRequestId stamped in metadata (mirrors the
@@ -512,6 +525,35 @@ export function recordTaskSpawnRequested(id: number, input: RecordTaskSpawnInput
   return getTaskDetail(id)!;
 }
 
+export function recordTaskDispatchDecision(id: number, input: RecordTaskDispatchDecisionInput): TaskDetail {
+  requireDeliverable(id);
+  const source = requireText(input.source, "source", 120);
+  const actor = requireText(input.actor, "actor", 200);
+  const target = isObject(input.decision.target) ? input.decision.target : {};
+  const rationale = optionalText(input.decision.rationale, "rationale", 4000) ?? "No dispatch rationale recorded";
+  const warnings = Array.isArray(input.decision.warnings)
+    ? input.decision.warnings.filter((item): item is string => typeof item === "string")
+    : [];
+  insertTaskEvent(id, {
+    source: actor,
+    type: "dispatch.resolved",
+    severity: warnings.length ? "warning" : "info",
+    title: `Dispatch resolved: ${typeof target.provider === "string" ? target.provider : "provider"}`,
+    body: rationale,
+    metadata: {
+      source,
+      decision: {
+        target,
+        rationale,
+        pinned: input.decision.pinned === true,
+        ...(isObject(input.decision.factors) ? { factors: input.decision.factors } : {}),
+        warnings,
+      },
+    },
+  }, Date.now());
+  return getTaskDetail(id)!;
+}
+
 // --- Reads / projections.
 function issueLinks(id: number): TaskIssueLink[] {
   return listIssuesForEntity("task", taskEntityId(String(id))).map((item) => ({
@@ -525,15 +567,24 @@ function issueLinks(id: number): TaskIssueLink[] {
   }));
 }
 
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 export function getTaskDetail(id: number): TaskDetail | null {
   const task = getRawTask(id);
   if (!task || task.kind !== DELIVERABLE_TASK_KIND) return null;
+  const decision = latestTaskDispatchDecision(id);
+  const workerModel = taskBoundWorkerModel(task.ownerAgentId);
   return {
     ...task,
     issues: issueLinks(id),
     dependsOn: listTaskDependencies(id),
     dependents: listTaskDependents(id),
     gates: latestGates(id),
+    dispatchWorkShape: taskDispatchWorkShape(task.dispatch),
+    ...(decision ? { dispatchDecision: decision } : {}),
+    ...(workerModel ? { boundWorkerModel: workerModel } : {}),
   };
 }
 

package/src/mcp/tools-spawn.ts

@@ -24,7 +24,7 @@ const SPAWN_LAND_STRATEGIES = ["direct", "pr"] as const;
 export const SPAWN_TOOLS: ToolDefinition[] = [
   {
     name: "relay_spawn_agent",
-    description: `Spawn a long-living provider agent through Relay's orchestrator, optionally handing it its first task via \`prompt\` in the same call. Defaults to your own host (override with orchestratorId), applies profile \`${DEFAULT_SPAWN_PROFILE_NAME}\` when profile is omitted, and returns the resolved agent id once it registers. Gated: requires the command:spawn scope, granted only to agents whose profile sets maxSpawnedAgents>0, up to that live-children quota. Spawned agents cannot themselves spawn (no grandchildren).`,
+    description: `Spawn a long-living provider agent through Relay's orchestrator, optionally handing it its first task via \`prompt\` or binding it to a durable Task via \`taskId\` + \`steer\` so Relay hydrates the first turn server-side. Defaults to your own host (override with orchestratorId), applies profile \`${DEFAULT_SPAWN_PROFILE_NAME}\` when profile is omitted, and returns the resolved agent id once it registers. Gated: requires the command:spawn scope, granted only to agents whose profile sets maxSpawnedAgents>0, up to that live-children quota. Spawned agents cannot themselves spawn (no grandchildren).`,
     requiredScopes: ["command:spawn"],
     inputSchema: {
       type: "object",

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 {
@@ -145,6 +145,9 @@ export function runTaskDispatch(input: RunTaskDispatchInput): RunTaskDispatchRes
   if (!shape && !inlineShape) shape = {};
 
   const decision = dispatchTask(shape, pin);
+  if (taskId !== undefined) {
+    recordTaskEntityDispatchDecision(taskId, { decision, source: "dispatch", actor });
+  }
 
   let reviewTaskId: number | undefined;
   if (decision.review && createReview && taskId !== undefined) {

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, getTaskMemoryRoute, getTaskHistoryRoute, patchTaskEntity, postTaskEntityStatus, postTaskEntityStage, postTaskEntityGate, postTaskDependency, deleteTaskDependency, postTaskRef, deleteTaskRef, postTaskAssign, postTaskComment, getTaskCloseBridge, postTaskDispatch } 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,6 +350,7 @@ 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),

package/src/routes/tasks.ts

@@ -1,7 +1,8 @@
 // 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 } from "../security";
+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";
@@ -18,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) {
@@ -65,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) => {
@@ -328,7 +343,7 @@ export const postTaskDispatch: Handler = async (req, params) => {
   const component = getComponentAuth(req);
   const agentId = component ? agentIdFromComponent(component) : undefined;
   const scopes = component?.scope ?? [];
-  if (!isTaskDispatchAuthorized(id, agentId, scopes)) return error("forbidden", 403);
+  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 ?? {};

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 = {

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