agent-relay-server 0.109.0 → 0.111.0

package/src/services/spawn-agent.ts

@@ -25,7 +25,9 @@
 // deliberately out of scope here — this slice converges the two external TRANSPORTS.
 import type { SpawnProvider } from "agent-relay-sdk";
 import { DEFAULT_USER_ID, errMessage, isRecord, stringValue } from "agent-relay-sdk";
-import { assignTaskAgent, countLiveSpawnedAgents, createActivityEvent, ensureTeam, getAgent, listAgents, listWorkspaces, recordTaskSpawnRequested, resolveAgentOwnership, resolveProjectForCwd, resolveScopedAnchor, setAgentTeam, ValidationError, withResolvedProvisioning } from "../db";
+import { statSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { countLiveSpawnedAgents, createActivityEvent, ensureTeam, getAgent, getTaskDetail, listAgents, listProjects, listWorkspaces, recordTaskSpawnRequested, resolveAgentOwnership, resolveProjectForCwd, resolveScopedAnchor, rootsForProject, setAgentTeam, ValidationError, withResolvedProvisioning } from "../db";
 import { createCommand } from "../commands-db";
 import { emitCommandEvent } from "../command-events";
 import { buildSpawnCommand, generateSpawnRequestId, resolveSpawnModelParams } from "../spawn-command";
@@ -39,6 +41,8 @@ import type { ProjectSkillsPolicy } from "../project-skills";
 import { applyDefaultSharedMcp, type SharedMcpSpawnOverride } from "../shared-mcp";
 import { autoSeedProjectForCwd } from "./project";
 import { hydrateTaskContext, projectTaskHydration } from "./task-context-hydration";
+import { recordTaskEntityDispatchDecision } from "./task-entity";
+import { autoSubscribeTaskCoordinator } from "./task-semantic-events";
 import { dispatchTask } from "../task-dispatcher";
 import { hasComponentScope, isComponentAuthorizedFor } from "../security";
 import { isPathWithinBase } from "../utils";
@@ -51,6 +55,60 @@ import { TERMINAL_WORKSPACE_STATUSES } from "../workspace-phase";
 /** The spawn scope every transport must hold (admin `*` / `admin:*` pass; `system` bypasses). */
 const SPAWN_SCOPE = "command:spawn";
 
+function hasGitMarker(dir: string): boolean {
+  try {
+    const marker = statSync(`${dir}/.git`);
+    return marker.isDirectory() || marker.isFile();
+  } catch {
+    return false;
+  }
+}
+
+function findGitRepoRoot(cwd: string): string | null {
+  if (!cwd.trim()) return null;
+  let current = resolve(cwd);
+  try {
+    const stat = statSync(current);
+    if (!stat.isDirectory()) current = dirname(current);
+  } catch {
+    return null;
+  }
+  for (;;) {
+    if (hasGitMarker(current)) return current;
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function assertIsolatedSpawnHasGitRepo(cwd: string): void {
+  if (findGitRepoRoot(cwd)) return;
+  throw new ValidationError(`workspaceMode "isolated" requires a git repo, but ${cwd} is not one. Pass an explicit cwd under a repo, or use workspaceMode "shared"/"inherit".`);
+}
+
+function taskLinkedRepoCwd(taskId: number, callerCwd?: string): string {
+  const task = getTaskDetail(taskId);
+  if (!task) throw new ValidationError(`task ${taskId} not found or not a deliverable task`);
+  const repos = [...new Set(task.issues.map((issue) => issue.repo).filter((repo): repo is string => Boolean(repo)))];
+  if (repos.length === 0) {
+    throw new ValidationError(`task ${taskId} has no linked issue repo; pass cwd/orchestratorId explicitly`);
+  }
+  const candidates = listProjects()
+    .filter((project) => project.issueRepo && repos.includes(project.issueRepo))
+    .flatMap((project) => rootsForProject(project.id).map((root) => ({ project, root })));
+  if (candidates.length === 0) {
+    throw new ValidationError(`task ${taskId} links repo ${repos.join(", ")} but no Relay project root is registered for it; pass cwd/orchestratorId explicitly or add a project root`);
+  }
+  const matchingCallerRoot = callerCwd
+    ? candidates
+      .filter((candidate) => isPathWithinBase(callerCwd, candidate.root.rootPath))
+      .sort((a, b) => b.root.rootPath.length - a.root.rootPath.length)[0]
+    : undefined;
+  if (matchingCallerRoot) return matchingCallerRoot.root.rootPath;
+  if (candidates.length === 1) return candidates[0]!.root.rootPath;
+  throw new ValidationError(`task ${taskId} links repo ${repos.join(", ")} with multiple registered roots; pass cwd explicitly`);
+}
+
 /**
  * A normalized spawn request — every transport validates its own wire shape (enums,
  * lengths) and hands the service this. Caller-context defaults (cwd, approvalMode,
@@ -177,6 +235,19 @@ function canSpawn(ctx: AuthContext): boolean {
   return ctx.scopes.includes(SPAWN_SCOPE);
 }
 
+function agentIdFromTaskCreator(createdBy: string | undefined): string | undefined {
+  const raw = createdBy?.trim();
+  if (!raw) return undefined;
+  const candidates = [raw, raw.startsWith("agent:") ? raw.slice("agent:".length) : undefined].filter((value): value is string => Boolean(value));
+  return candidates.find((candidate) => getAgent(candidate)) ?? undefined;
+}
+
+function taskSpawnLabel(task: { id: number; title: string } | undefined, fallback?: string): string | undefined {
+  if (fallback || !task) return fallback;
+  const label = `task-${task.id}: ${task.title.trim() || "untitled"}`;
+  return label.length <= 120 ? label : `${label.slice(0, 117)}...`;
+}
+
 /**
  * Spawn a provider agent. Transport-agnostic: every gate + side effect lives here so the
  * MCP and HTTP paths cannot drift. Throws `McpAuthError` (→403) on a gate denial,
@@ -189,22 +260,30 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
   // the #221 gate AND the #328/#331/#324 caller-context inheritance — one lookup, reused.
   const callerId = ctx.callerAgentId;
   const caller: AgentCard | undefined = (callerId ? getAgent(callerId) : undefined) ?? undefined;
+  const linkedTask = input.taskId !== undefined ? getTaskDetail(input.taskId) ?? undefined : undefined;
+  const taskCreatorAgentId = !callerId ? agentIdFromTaskCreator(linkedTask?.createdBy) : undefined;
+  const lineageAgentId = callerId ?? taskCreatorAgentId;
+  const lineageAgent: AgentCard | undefined = (lineageAgentId ? getAgent(lineageAgentId) : undefined) ?? undefined;
+  const callerCwd = stringValue(caller?.meta?.cwd) ?? stringValue(lineageAgent?.meta?.cwd);
+  const taskDefaultCwd = input.taskId !== undefined && !input.orchestratorId && !input.cwd
+    ? taskLinkedRepoCwd(input.taskId, callerCwd)
+    : undefined;
+  const requestedCwd = input.cwd ?? taskDefaultCwd;
 
   // #255/#328 — bias the host to the caller's own machine when neither an explicit
   // orchestratorId nor a cwd pins it, so an agent spawning a helper lands on its own host.
-  const orchestrator = selectSpawnOrchestrator(input.provider, input.orchestratorId, input.cwd, caller?.machine);
+  const orchestrator = selectSpawnOrchestrator(input.provider, input.orchestratorId, requestedCwd, caller?.machine ?? lineageAgent?.machine);
 
   // #308 §3 — an explicit cwd must resolve within the TARGET host's base dir (a path valid on
   // your host may not exist on a different orchestrator).
-  if (input.cwd && !isPathWithinBase(input.cwd, orchestrator.baseDir)) {
-    throw new ValidationError(`cwd '${input.cwd}' is not within ${orchestrator.id} (host ${orchestrator.hostname})'s base dir '${orchestrator.baseDir}' — a path valid on your host may not exist on the target. Pass a cwd under that base dir, or omit cwd to default to it.`);
+  if (requestedCwd && !isPathWithinBase(requestedCwd, orchestrator.baseDir)) {
+    throw new ValidationError(`cwd '${requestedCwd}' is not within ${orchestrator.id} (host ${orchestrator.hostname})'s base dir '${orchestrator.baseDir}' — a path valid on your host may not exist on the target. Pass a cwd under that base dir, or omit cwd to default to it.`);
   }
   // #328 — default cwd to the caller's OWN repo (so "spawn a helper for my current task" Just
   // Works, esp. isolated mode which needs a git repo), but only when it resolves within the
   // target host's base. Precedence: explicit cwd > caller cwd > base dir.
-  const callerCwd = stringValue(caller?.meta?.cwd);
   const inheritedCwd = callerCwd && isPathWithinBase(callerCwd, orchestrator.baseDir) ? callerCwd : undefined;
-  const resolvedCwd = input.cwd || inheritedCwd || orchestrator.baseDir;
+  const resolvedCwd = requestedCwd || inheritedCwd || orchestrator.baseDir;
 
   // #838 — spawn-with-task hydration. When a taskId is given, relay assembles the worker's
   // first-turn context FROM the durable Task (intent + linked-issue spec/acceptance + recorded
@@ -234,9 +313,11 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
   // and a no-taskId spawn is untouched — the coupling is opt-in, not hard-wired.
   let dispatchModel = input.model;
   let dispatchEffort = input.effort;
+  let taskDispatchDecision: ReturnType<typeof dispatchTask> | undefined;
   if (hydratedTask && !input.model && !input.effort && hydratedTask.task.dispatch) {
     try {
       const decision = dispatchTask(hydratedTask.task.dispatch, { provider: input.provider });
+      taskDispatchDecision = decision;
       dispatchModel = decision.target.model ?? dispatchModel;
       dispatchEffort = decision.target.effort ?? dispatchEffort;
     } catch (err) {
@@ -245,18 +326,23 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
   }
 
   const modelParams = resolveSpawnModelParams(input.provider, dispatchModel, dispatchEffort);
+  const resolvedLabel = taskSpawnLabel(linkedTask, input.label);
 
   // #331 — default the child's approval mode to the CALLER's, not a hardcoded `guarded` (a
   // headless `guarded` child wedges on its first tool-call approval prompt). Explicit always
   // wins and can NARROW a child; non-agent callers keep the safe `guarded` default.
-  const callerApprovalMode = caller?.meta?.approvalMode as SpawnApprovalMode | undefined;
-  const approvalMode = input.approvalMode ?? callerApprovalMode ?? "guarded";
+  const callerApprovalMode = (caller?.meta?.approvalMode ?? lineageAgent?.meta?.approvalMode) as SpawnApprovalMode | undefined;
+  const approvalMode = input.approvalMode ?? callerApprovalMode ?? (input.taskId !== undefined ? "open" : "guarded");
 
   // #324 — agent-initiated spawns (a real caller behind the token) default to `isolated` (a
   // branch worker that auto-lands); non-agent callers (admin/dashboard) keep the orchestrator's
-  // `inherit` fallback. Explicit wins.
-  const workspaceMode = input.workspaceMode ?? (callerId ? ("isolated" as WorkspaceMode) : undefined);
+  // `inherit` fallback. Task-triggered spawns are coordinator work and should get an isolated
+  // branch unless explicitly narrowed.
+  const workspaceMode = input.workspaceMode ?? (callerId || input.taskId !== undefined ? ("isolated" as WorkspaceMode) : undefined);
   const lifecycle = input.lifecycle ?? "persistent";
+  if (workspaceMode === "isolated" && (input.taskId !== undefined || input.workspaceMode === "isolated")) {
+    assertIsolatedSpawnHasGitRepo(resolvedCwd);
+  }
 
   const spawnRequestId = input.spawnRequestId ?? generateSpawnRequestId();
 
@@ -344,9 +430,9 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
 
   // Provenance actor: the resolved caller agent when known, else the transport's label, else
   // the raw token actor. Recorded in the command payload, the token mint, and the audit row.
-  const requestedBy = callerId ?? input.requestedBy ?? ctx.actor.id;
-  const callerTeam = callerId ? (caller?.teamId ? { id: caller.teamId } : ensureTeam(callerId)) : undefined;
-  if (callerId && callerTeam && !caller?.teamId) setAgentTeam(callerId, callerTeam.id);
+  const requestedBy = callerId ?? taskCreatorAgentId ?? input.requestedBy ?? ctx.actor.id;
+  const callerTeam = lineageAgentId ? (lineageAgent?.teamId ? { id: lineageAgent.teamId } : ensureTeam(lineageAgentId)) : undefined;
+  if (lineageAgentId && callerTeam && !lineageAgent?.teamId) setAgentTeam(lineageAgentId, callerTeam.id);
 
   // #405 — durable project binding: the project whose registered root contains the spawn cwd.
   // Stamped on the child token's constraints (identity-only, like teamId) so callerProject(auth)
@@ -374,7 +460,7 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
   // Both resolve null until someone has actually written to them, so a fresh deployment stays
   // byte-identical. Injection of their active (promoted) entries happens in the composer.
   const profileAnchor = resolveScopedAnchor("profile", profileName);
-  const operatorId = callerId ? resolveAgentOwnership(callerId).ownerUserId : DEFAULT_USER_ID;
+  const operatorId = lineageAgentId ? resolveAgentOwnership(lineageAgentId).ownerUserId : DEFAULT_USER_ID;
   const userAnchor = resolveScopedAnchor("user", operatorId);
   const composedInstructions = composeSpawnInstructionsWithEvents({
     ...(callerProject ? { callerProject } : {}),
@@ -382,7 +468,7 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
     ...(profileAnchor ? { profileAnchor } : {}),
     ...(userAnchor ? { userAnchor } : {}),
     ...(agentProfile ? { profile: agentProfile } : {}),
-    ...(callerId ? { spawnedBy: callerId } : {}),
+    ...(lineageAgentId ? { spawnedBy: lineageAgentId } : {}),
     ...(resolvedSystemPromptAppend ? { callerSystemPromptAppend: resolvedSystemPromptAppend } : {}),
   });
   const systemPromptAppend = composedInstructions.systemPromptAppend;
@@ -395,9 +481,10 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
     orchestratorId: orchestrator.id,
     cwd: resolvedCwd,
     provider: input.provider,
-    label: input.label,
+    label: resolvedLabel,
     policyName: input.policyName,
     spawnRequestId,
+    taskId: input.taskId,
     createdBy: requestedBy,
     // Thread the resolved profile into the mint so the spawn grant (command:spawn/shutdown +
     // maxSpawnedAgents quota) is honored — parity with the HTTP path (agent-sessions.ts). #349
@@ -405,7 +492,7 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
     // (P0 regression #364). For an agent caller, agentInitiated still forces a non-spawn-capable
     // child regardless of profile (no grandchildren).
     profile: profileName,
-    ...(callerId ? { agentInitiated: true, spawnedBy: callerId } : {}),
+    ...(lineageAgentId ? { agentInitiated: true, spawnedBy: lineageAgentId } : {}),
     ...(callerTeam ? { teamId: callerTeam.id } : {}),
     ...(callerProject ? { projectId: callerProject.id } : {}),
   });
@@ -426,7 +513,7 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
       cwd: resolvedCwd,
       ...(workspaceMode ? { workspaceMode } : {}),
       lifecycle,
-      label: input.label,
+      label: resolvedLabel,
       profile: profileName,
       agentProfile,
       tags: input.tags ?? [],
@@ -440,6 +527,7 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
       landStrategy: input.landStrategy,
       autoMerge: input.autoMerge,
       reviewer: input.reviewer,
+      taskId: input.taskId,
       resumeWorkspace: input.resumeWorkspace,
       ...(expectReply ? { expectReply } : {}),
       policyName: input.policyName,
@@ -451,7 +539,7 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
       orchestratorId: orchestrator.id,
       // #308 — stamp the spawning parent so a FAILED agent.spawn command (child never registers,
       // so there's no agent row to resolve `spawnedBy` from) can be routed back to it.
-      ...(callerId ? { extra: { spawnedBy: callerId } } : {}),
+      ...(lineageAgentId ? { extra: { spawnedBy: lineageAgentId } } : {}),
     }),
   });
   emitCommandEvent(command, "command.requested");
@@ -472,7 +560,7 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
       approvalMode,
       lifecycle,
       workspaceMode: workspaceMode ?? null,
-      label: input.label ?? null,
+      label: resolvedLabel ?? null,
       commandId: command.id,
       spawnRequestId,
       requestedVia: input.requestedVia ?? null,
@@ -486,12 +574,20 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
   // drive one-shot reap. Best-effort: an attribution write never fails the spawn.
   if (input.taskId !== undefined) {
     try {
+      if (taskDispatchDecision) {
+        recordTaskEntityDispatchDecision(input.taskId, {
+          decision: taskDispatchDecision,
+          source: "spawn",
+          actor: requestedBy,
+        });
+      }
       recordTaskSpawnRequested(input.taskId, {
         spawnRequestId,
         provider: input.provider,
         requestedBy,
         ...(hydratedTask?.steer ? { steer: hydratedTask.steer } : {}),
       });
+      autoSubscribeTaskCoordinator(requestedBy, input.taskId);
     } catch (err) {
       console.warn(`task ${input.taskId} spawn attribution skipped: ${errMessage(err)}`);
     }
@@ -502,16 +598,6 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
   const waitMs = Math.min(input.waitForRegistrationMs ?? 0, 30_000);
   const agentId = waitMs > 0 ? await waitForSpawnedAgent(spawnRequestId, waitMs) : null;
 
-  // #838 — once the child's id is known (waitForRegistrationMs > 0), stamp it as the Task owner
-  // via the #834 attribution API. Fire-and-forget spawns resolve the id later; #831 closes that
-  // gap by reading the spawn_requested event above. Best-effort, never fails the spawn.
-  if (input.taskId !== undefined && agentId) {
-    try {
-      assignTaskAgent(input.taskId, agentId, "worker", requestedBy);
-    } catch (err) {
-      console.warn(`task ${input.taskId} owner attribution skipped: ${errMessage(err)}`);
-    }
-  }
   return {
     ok: true,
     spawnRequestId,

package/src/services/task-entity.ts

@@ -11,6 +11,7 @@ import {
   listDeliverableTasks,
   listTaskEvents,
   recordGate,
+  recordTaskDispatchDecision,
   removeTaskDependency,
   removeTaskRef,
   setTaskStage,
@@ -19,6 +20,7 @@ import {
   type AddTaskRefInput,
   type CreateDeliverableTaskInput,
   type ListDeliverableTasksFilter,
+  type RecordTaskDispatchDecisionInput,
   type RecordGateInput,
   type RemoveTaskRefInput,
   type SetTaskStageInput,
@@ -27,16 +29,17 @@ import {
 } from "../db";
 import { emitTaskChanged } from "../sse";
 import type { Task, TaskDetail, TaskEvent, TaskGateState } from "../types";
-import { emitTaskSemanticNotification, taskTransitionForStatus } from "./task-semantic-events";
+import { removeSubscriptionsForTask } from "../db/notification-subscriptions";
+import { autoSubscribeTaskCoordinator, emitTaskSemanticNotification, taskTransitionForStage, taskTransitionForStatus } from "./task-semantic-events";
 
 export function createTaskEntity(input: CreateDeliverableTaskInput): TaskDetail {
   const detail = createDeliverableTask(input);
+  autoSubscribeTaskCoordinator(input.createdBy, detail.id);
   emitTaskChanged(detail, "task.created");
   emitTaskSemanticNotification({
     task: detail,
     transition: "created",
     actor: input.createdBy,
-    recipients: input.createdBy ? [input.createdBy] : [],
     occurrenceKey: latestTaskEventOccurrence(detail.id, "task.created"),
   });
   return detail;
@@ -66,23 +69,27 @@ export function setTaskEntityStatus(id: number, input: SetTaskStatusInput): Task
       task: detail,
       transition,
       actor: input.actor,
-      recipients: detail.createdBy ? [detail.createdBy] : [],
       occurrenceKey: latestTaskEventOccurrence(detail.id, `status:${detail.status}`),
     });
   }
+  if (isTerminalTaskStatus(detail.status)) removeSubscriptionsForTask(detail.id);
   return detail;
 }
 
+function isTerminalTaskStatus(status: Task["status"]): boolean {
+  return status === "done" || status === "failed" || status === "canceled";
+}
+
 export function setTaskEntityStage(id: number, input: SetTaskStageInput): TaskDetail {
   const before = getTaskDetail(id);
   const detail = setTaskStage(id, input);
   emitTaskChanged(detail, "task.stage");
-  if (input.actor !== "task-lifecycle" && before?.deliverableStage !== "landed-on-main" && detail.deliverableStage === "landed-on-main") {
+  const transition = taskTransitionForStage(detail.deliverableStage);
+  if (input.actor !== "task-lifecycle" && transition && before?.deliverableStage !== detail.deliverableStage) {
     emitTaskSemanticNotification({
       task: detail,
-      transition: "landed",
+      transition,
       actor: input.actor,
-      recipients: detail.createdBy ? [detail.createdBy] : [],
       branch: detail.branch,
       occurrenceKey: latestTaskEventOccurrence(detail.id, `stage:${detail.deliverableStage}`),
     });
@@ -109,6 +116,15 @@ export function recordTaskEntityGate(id: number, input: RecordGateInput): { gate
   const gate = recordGate(id, input);
   const detail = getTaskDetail(id);
   if (detail) emitTaskChanged(detail, "task.gate");
+  if (detail && gate.status === "fail") {
+    emitTaskSemanticNotification({
+      task: detail,
+      transition: "gate-failed",
+      actor: input.actor,
+      occurrenceKey: latestTaskEventOccurrence(detail.id, `gate:${gate.gate}`),
+      outcome: { gate: gate.gate, status: gate.status, ...(gate.detail ? { detail: gate.detail } : {}) },
+    });
+  }
   return { gate, gates: detail?.gates ?? [] };
 }
 
@@ -144,6 +160,12 @@ export function assignTaskEntityAgent(id: number, agentId: string, role?: string
   return detail;
 }
 
+export function recordTaskEntityDispatchDecision(id: number, input: RecordTaskDispatchDecisionInput): TaskDetail {
+  const detail = recordTaskDispatchDecision(id, input);
+  emitTaskChanged(detail, "task.dispatch");
+  return detail;
+}
+
 export function taskEntityHistory(id: number): TaskEvent[] {
   return listTaskEvents(id);
 }

package/src/services/task-lifecycle.ts

@@ -36,7 +36,7 @@ import { requestTransientAgentShutdown } from "./transient-agent-reaper";
 import { emitRelayEvent } from "../events";
 import { routeNotification } from "../notification-router";
 import { resolveCoordinatorAgentId } from "../steward-identity";
-import { emitTaskSemanticNotification } from "./task-semantic-events";
+import { emitTaskSemanticNotification, type TaskSemanticTransition } from "./task-semantic-events";
 import type { IssueRef, TaskDeliverableStage, TaskGateState, WorkspaceRecord } from "../types";
 import type { IssueTrackerAdapter } from "../issue-tracker";
 
@@ -179,7 +179,7 @@ function landKeyFor(input: LandedTaskLifecycleInput): string {
 // `agent.spawn_requested` attribution keyed on the worker's meta.spawnRequestId (fire-and-forget,
 // owner not yet backfilled), and the Task's recorded branch column. Deduped + ordered. Returns []
 // for an ordinary non-task branch → the land is a strict no-op (behavior byte-identical).
-function resolveBoundTaskIds(workspace: LifecycleWorkspace): number[] {
+export function boundTaskIdsForWorkspace(workspace: LifecycleWorkspace): number[] {
   const ids = new Set<number>();
   const owner = workspace.ownerAgentId?.trim();
   if (owner) {
@@ -195,6 +195,35 @@ function resolveBoundTaskIds(workspace: LifecycleWorkspace): number[] {
   return [...ids].sort((a, b) => a - b);
 }
 
+export function emitWorkspaceTaskSemanticNotifications(input: {
+  workspace: LifecycleWorkspace;
+  transition: TaskSemanticTransition;
+  actor?: string;
+  occurrenceKey?: string;
+  outcome?: Record<string, unknown>;
+  sha?: string;
+}): number[] {
+  const emitted: number[] = [];
+  const coordinator = resolveCoordinatorAgentId(input.workspace.ownerAgentId ?? undefined);
+  for (const taskId of boundTaskIdsForWorkspace(input.workspace)) {
+    const task = getTaskDetail(taskId);
+    if (!task) continue;
+    emitTaskSemanticNotification({
+      task,
+      transition: input.transition,
+      actor: input.actor,
+      recipients: coordinator ? [coordinator] : [],
+      workspaceId: input.workspace.id,
+      branch: input.workspace.branch,
+      ...(input.sha ? { sha: input.sha } : {}),
+      ...(input.occurrenceKey ? { occurrenceKey: input.occurrenceKey } : {}),
+      ...(input.outcome ? { outcome: input.outcome } : {}),
+    });
+    emitted.push(taskId);
+  }
+  return emitted;
+}
+
 // --- reap signal (decoupled from task-done) ----------------------------------------------------
 interface ReapResult {
   reaped: boolean;
@@ -382,7 +411,7 @@ function emitDeliverableLandedEvent(input: LandedTaskLifecycleInput, outcome: Ta
   const coordinator = resolveCoordinatorAgentId(input.workspace.ownerAgentId ?? undefined);
   emitTaskSemanticNotification({
     task,
-    transition: "landed",
+    transition: "landed-on-main",
     actor: "task-lifecycle",
     recipients: coordinator ? [coordinator] : [],
     workspaceId: input.workspace.id,
@@ -401,7 +430,7 @@ function emitDeliverableErrorReceipt(input: LandedTaskLifecycleInput, outcome: T
     type: "task.landed",
     scope: {
       taskId: String(outcome.taskId),
-      transition: "landed",
+      transition: "landed-on-main",
       landKey,
       ...(input.workspace.ownerAgentId ? { agentId: input.workspace.ownerAgentId, author: input.workspace.ownerAgentId } : {}),
       ...(task?.createdBy ? { parent: task.createdBy } : {}),
@@ -417,8 +446,8 @@ function emitDeliverableErrorReceipt(input: LandedTaskLifecycleInput, outcome: T
         kind: "task.lifecycle-error",
         notification: "task-lifecycle-error",
         taskId: outcome.taskId,
-        transition: "landed",
-        semanticEvent: "task.landed",
+        transition: "landed-on-main",
+        semanticEvent: "task.landed-on-main",
         workspaceId: input.workspace.id,
         branch: input.workspace.branch,
         ...(input.mergedSha ? { sha: input.mergedSha } : {}),
@@ -442,7 +471,7 @@ export async function handleLandedTaskLifecycle(
   const log = opts.log ?? ((message: string) => console.warn(message));
   // Non-default-base lands never drive a deliverable (mirror the issue-lifecycle guard).
   if ((input.workspace.baseRef ?? "main") !== "main") return { handled: false, reason: "non-default-branch", tasks: [] };
-  const taskIds = resolveBoundTaskIds(input.workspace);
+  const taskIds = boundTaskIdsForWorkspace(input.workspace);
   if (taskIds.length === 0) return { handled: false, reason: "no-bound-task", tasks: [] };
 
   const diffSummary = landedDiffSummary(input, log);