agent-relay-server 0.50.0 → 0.52.0

package/src/services/agent-action.ts

@@ -0,0 +1,138 @@
+import { createCommand } from "../commands-db";
+import { ValidationError, createActivityEvent, getAgent, sendMessage } from "../db";
+import { emitCommandEvent } from "../command-events";
+import { emitActivityEvent, emitNewMessage } from "../sse";
+import { authorizeShutdown, ShutdownAuthError, ShutdownTargetError } from "./shutdown-agent";
+import type { AuthContext } from "./auth-context";
+import type { AgentCard, Command } from "../types";
+
+export type AgentAction = "compact" | "clearContext" | "inject";
+
+export interface AgentActionInput {
+  agentId: string;
+  action: AgentAction;
+  message?: string;
+  requestedVia: "mcp";
+  requestedBy?: string;
+}
+
+export interface AgentActionResult {
+  action: AgentAction;
+  command: Command;
+}
+
+export class AgentActionTargetError extends Error {}
+
+function commandType(action: AgentAction): "agent.compact" | "agent.clearContext" | "prompt.inject" {
+  if (action === "compact") return "agent.compact";
+  if (action === "clearContext") return "agent.clearContext";
+  return "prompt.inject";
+}
+
+function title(action: AgentAction): string {
+  if (action === "compact") return "Agent compaction requested";
+  if (action === "clearContext") return "Agent context clear requested";
+  return "Agent prompt injected";
+}
+
+function icon(action: AgentAction): string {
+  if (action === "compact") return "ti-fold";
+  if (action === "clearContext") return "ti-clear-all";
+  return "ti-message-bolt";
+}
+
+function compactMemoryParams(agent: AgentCard): Record<string, unknown> {
+  const alwaysReload = agent.tags
+    .filter((tag) => tag.startsWith("memory-reload:"))
+    .map((tag) => tag.slice("memory-reload:".length).trim())
+    .filter(Boolean);
+  if (!alwaysReload.length) return {};
+  return { memory: { alwaysReload } };
+}
+
+function assertSupported(agent: AgentCard, action: AgentAction): void {
+  if (agent.id === "user" || agent.id === "system" || agent.meta?.kind === "channel" || agent.tags.includes("channel")) {
+    throw new ValidationError("agent cannot receive lifecycle actions");
+  }
+  if (agent.status === "offline") throw new ValidationError("agent is offline");
+  if (action === "compact" && agent.providerCapabilities?.context?.compact !== true) {
+    throw new ValidationError("agent does not support compact");
+  }
+  if (action === "clearContext" && agent.providerCapabilities?.context?.clear !== true) {
+    throw new ValidationError("agent does not support clearContext");
+  }
+  if (action === "inject" && agent.providerCapabilities?.liveSession?.inject !== true) {
+    throw new ValidationError("agent does not support inject");
+  }
+}
+
+function sessionMessageForInject(agentId: string, ctx: AuthContext, body: string) {
+  const from = ctx.callerAgentId && getAgent(ctx.callerAgentId) ? ctx.callerAgentId : "system";
+  const message = sendMessage({
+    from,
+    to: agentId,
+    kind: "session",
+    body,
+  });
+  emitNewMessage(message);
+  return message;
+}
+
+export function dispatchAgentAction(input: AgentActionInput, ctx: AuthContext): AgentActionResult {
+  const agent = getAgent(input.agentId);
+  if (!agent) throw new AgentActionTargetError(`agent ${input.agentId} not found`);
+
+  try {
+    authorizeShutdown(ctx, { agentId: input.agentId, requestedVia: input.requestedVia });
+  } catch (e) {
+    if (e instanceof ShutdownAuthError || e instanceof ShutdownTargetError) throw e;
+    throw e;
+  }
+  assertSupported(agent, input.action);
+
+  const body = input.action === "inject"
+    ? (input.message?.trim() || (() => { throw new ValidationError("message is required for inject"); })())
+    : undefined;
+  const sessionMessage = body ? sessionMessageForInject(agent.id, ctx, body) : undefined;
+  const command = createCommand({
+    type: commandType(input.action),
+    source: "system",
+    target: agent.id,
+    correlationId: typeof agent.meta?.spawnRequestId === "string" ? agent.meta.spawnRequestId : undefined,
+    params: {
+      action: input.action,
+      agentId: agent.id,
+      ...(typeof agent.meta?.sessionName === "string" ? { sessionName: agent.meta.sessionName } : {}),
+      ...(typeof agent.meta?.tmuxSession === "string" ? { tmuxSession: agent.meta.tmuxSession } : {}),
+      ...(typeof agent.meta?.policyName === "string" ? { policyName: agent.meta.policyName } : {}),
+      ...(typeof agent.meta?.spawnRequestId === "string" ? { spawnRequestId: agent.meta.spawnRequestId } : {}),
+      ...(input.action === "compact" ? compactMemoryParams(agent) : {}),
+      ...(body ? { body, messageId: sessionMessage!.id } : {}),
+      requestedBy: input.requestedBy ?? ctx.callerAgentId ?? ctx.actor.id,
+      requestedVia: input.requestedVia,
+      requestedAt: Date.now(),
+    },
+  });
+  emitCommandEvent(command, "command.requested");
+  const event = createActivityEvent({
+    clientId: `server-agent-${agent.id}-action-${input.action}-${command.id}`,
+    kind: "state",
+    title: title(input.action),
+    body: input.action,
+    meta: agent.id,
+    icon: icon(input.action),
+    view: "agents",
+    agentId: agent.id,
+    messageId: sessionMessage?.id,
+    metadata: {
+      action: input.action,
+      commandId: command.id,
+      actor: ctx.actor.id,
+      actorKind: ctx.actor.kind,
+      requestedVia: input.requestedVia,
+      source: "server",
+    },
+  });
+  emitActivityEvent(event);
+  return { action: input.action, command };
+}

package/src/services/plan-graph.ts

@@ -1,9 +1,9 @@
 import { isRecord } from "agent-relay-sdk";
-import { createPlanRow, deletePlan, getAgent, getEntry, getPlan, getPlanByTeam, getPlanByThread, planThreadExists, replacePlan, ValidationError } from "../db";
+import { createPlanRow, deletePlan, getAgent, getEntry, getPlan, getPlanByTeam, getPlanByThread, listPlansWithBoundOwner, planThreadExists, replacePlan, ValidationError } from "../db";
 import { emitRelayEvent } from "../events";
 import { cleanString, cleanStringArray, optionalEnum } from "../validation";
 import type { AuthContext } from "./auth-context";
-import type { Plan, PlanEdge, PlanNode, PlanOwnerRef, PlanStatus } from "../types";
+import type { AgentCard, Plan, PlanEdge, PlanNode, PlanOwnerRef, PlanStatus } from "../types";
 
 export const PLAN_STATUSES = ["pending", "in-progress", "landed", "blocked"] as const;
 
@@ -86,10 +86,22 @@ function cleanBlackboardRefs(value: unknown, planTeamId?: string): string[] | un
   return refs;
 }
 
-function cleanStatusSource(value: unknown): "manual" {
+function cleanStatusSource(value: unknown): PlanNode["statusSource"] {
   const statusSource = optionalEnum(value, "statusSource", ["manual", "bound"] as const, "manual");
-  if (statusSource !== "manual") throw new ValidationError("statusSource must be manual in this slice");
-  return "manual";
+  return statusSource;
+}
+
+function boundStatusForAgent(agent: Pick<AgentCard, "status"> | null | undefined): PlanStatus | undefined {
+  if (!agent) return undefined;
+  if (agent.status === "busy") return "in-progress";
+  return "pending";
+}
+
+function applyBoundStatus(node: PlanNode): PlanNode {
+  if (node.statusSource !== "bound") return node;
+  const agentId = node.ownerRef?.agentId;
+  if (!agentId) throw new ValidationError("bound plan nodes require ownerRef.agentId");
+  return { ...node, status: boundStatusForAgent(getAgent(agentId)) ?? "pending" };
 }
 
 function cleanNode(input: PlanNodeInput, planTeamId?: string): PlanNode {
@@ -99,17 +111,18 @@ function cleanNode(input: PlanNodeInput, planTeamId?: string): PlanNode {
   const lane = cleanString(input.lane, "node.lane", { max: 120 });
   const refs = cleanRefs(input.refs);
   const blackboardRefs = cleanBlackboardRefs(input.blackboardRefs, planTeamId);
-  return {
+  const statusSource = cleanStatusSource(input.statusSource);
+  return applyBoundStatus({
     id: cleanString(input.id, "node.id", { required: true, max: 120 })!,
     label: cleanString(input.label, "node.label", { required: true, max: 240 })!,
     ...(scopeBlurb ? { scopeBlurb } : {}),
     ...(ownerRef ? { ownerRef } : {}),
     ...(lane ? { lane } : {}),
     status: optionalEnum(input.status, "node.status", PLAN_STATUSES, "pending") as PlanStatus,
-    statusSource: cleanStatusSource(input.statusSource),
+    statusSource,
     ...(refs ? { refs } : {}),
     ...(blackboardRefs ? { blackboardRefs } : {}),
-  };
+  });
 }
 
 function cleanNodes(value: unknown, planTeamId?: string): PlanNode[] {
@@ -233,8 +246,8 @@ export function updatePlanNode(planId: string, nodeId: string, patch: PlanNodePa
   const plan = existingPlan(planId);
   const existing = plan.nodes.find((node) => node.id === nodeId);
   if (!existing) throw new ValidationError(`node ${nodeId} not found`);
-  if (patch.statusSource !== undefined) cleanStatusSource(patch.statusSource);
-  const next: PlanNode = {
+  const statusSource = patch.statusSource !== undefined ? cleanStatusSource(patch.statusSource) : existing.statusSource;
+  const base: PlanNode = {
     ...existing,
     ...(patch.label !== undefined ? { label: cleanString(patch.label, "label", { required: true, max: 240 })! } : {}),
     ...(patch.scopeBlurb !== undefined ? optionalProp("scopeBlurb", cleanString(patch.scopeBlurb, "scopeBlurb", { max: 2000 })) : {}),
@@ -243,8 +256,9 @@ export function updatePlanNode(planId: string, nodeId: string, patch: PlanNodePa
     ...(patch.status !== undefined ? { status: optionalEnum(patch.status, "status", PLAN_STATUSES) as PlanStatus } : {}),
     ...(patch.refs !== undefined ? optionalProp("refs", cleanRefs(patch.refs)) : {}),
     ...(patch.blackboardRefs !== undefined ? optionalProp("blackboardRefs", cleanBlackboardRefs(patch.blackboardRefs, plan.teamId)) : {}),
-    statusSource: "manual",
+    statusSource,
   };
+  const next = applyBoundStatus(base);
   const updated = replacePlan({ ...plan, nodes: plan.nodes.map((node) => node.id === nodeId ? next : node) }, actorId(ctx));
   emitPlan("plan.changed", updated, actorId(ctx));
   return updated;
@@ -294,6 +308,30 @@ export function deletePlanGraph(planId: string, ctx: AuthContext): { id: string;
   return { id: plan.id, deleted: true };
 }
 
+export function updateBoundPlanNodesForAgent(agentId: string, status: PlanStatus, actor = "server"): Plan[] {
+  const updated: Plan[] = [];
+  for (const plan of listPlansWithBoundOwner(agentId)) {
+    let changed = false;
+    const nodes = plan.nodes.map((node) => {
+      if (node.statusSource !== "bound" || node.ownerRef?.agentId !== agentId) return node;
+      if (node.status === "landed") return node;
+      if (node.status === status) return node;
+      changed = true;
+      return { ...node, status };
+    });
+    if (!changed) continue;
+    const next = replacePlan({ ...plan, nodes }, actor);
+    emitPlan("plan.changed", next, actor);
+    updated.push(next);
+  }
+  return updated;
+}
+
+export function updateBoundPlanNodesFromAgent(agentId: string, actor = "server"): Plan[] {
+  const status = boundStatusForAgent(getAgent(agentId));
+  return status ? updateBoundPlanNodesForAgent(agentId, status, actor) : [];
+}
+
 export function getPlanGraph(input: { planId?: unknown; threadId?: unknown; teamId?: unknown; channel?: unknown }): Plan | null {
   const planId = cleanString(input.planId, "planId", { max: 120 });
   if (planId) return getPlan(planId);

package/src/services/plan-live-bindings.ts

@@ -0,0 +1,88 @@
+import { getTeam } from "../db";
+import { subscribeRelayEvents, type RelayEvent } from "../events";
+import { notifySystemMessage } from "../notify";
+import { updateBoundPlanNodesForAgent, updateBoundPlanNodesFromAgent } from "./plan-graph";
+
+let unsubscribe: (() => void) | undefined;
+
+const GRACEFUL_EXIT_REASONS = new Set([
+  "transient-complete",
+  "shutdown",
+  "manual-stop",
+  "manual-restart",
+  "policy-deleted",
+  "task-complete",
+  "mcp-shutdown",
+  "http-shutdown",
+  "bus-shutdown",
+  "self-resume",
+  "self-resume-continuation",
+  "compact",
+  "clear",
+  "resume",
+  "restart",
+]);
+
+function stringField(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value : undefined;
+}
+
+function isGracefulExitReason(reason: string | undefined): boolean {
+  if (!reason) return false;
+  if (GRACEFUL_EXIT_REASONS.has(reason)) return true;
+  return reason.startsWith("self-resume budget exhausted:");
+}
+
+function agentIdFromEvent(event: RelayEvent): string | undefined {
+  return stringField(event.data.agentId) ?? stringField(event.data.id) ?? event.subject;
+}
+
+function notifyBoundExit(event: RelayEvent, updatedPlans: ReturnType<typeof updateBoundPlanNodesForAgent>): void {
+  const agentId = agentIdFromEvent(event);
+  if (!agentId) return;
+  const reason = stringField(event.data.reason);
+
+  for (const plan of updatedPlans) {
+    if (!plan.teamId) continue;
+    const team = getTeam(plan.teamId);
+    const target = team?.coordinatorId ?? `team:${plan.teamId}`;
+    const blockedNodes = plan.nodes.filter((node) => node.statusSource === "bound" && node.ownerRef?.agentId === agentId && node.status === "blocked");
+    if (blockedNodes.length === 0) continue;
+    notifySystemMessage(target, {
+      subject: "Bound plan node blocked",
+      body: `Agent \`${agentId}\` exited${reason ? ` (${reason})` : ""}; blocked plan node(s) ${blockedNodes.map((node) => `\`${node.id}\``).join(", ")} in \`${plan.id}\`.`,
+      payload: { kind: "plan.bound_agent_exited", planId: plan.id, agentId, nodeIds: blockedNodes.map((node) => node.id), reason },
+      replyExpected: false,
+    });
+  }
+}
+
+function handlePlanBindingEvent(event: RelayEvent): void {
+  if (event.type === "agent.status") {
+    const agentId = agentIdFromEvent(event);
+    if (agentId) updateBoundPlanNodesFromAgent(agentId, event.source || "server");
+    return;
+  }
+  if (event.type === "branch.landed") {
+    const agentId = stringField(event.data.author);
+    if (agentId) updateBoundPlanNodesForAgent(agentId, "landed", event.source || "server");
+    return;
+  }
+  if (event.type === "agent.exited") {
+    const agentId = agentIdFromEvent(event);
+    if (!agentId) return;
+    if (isGracefulExitReason(stringField(event.data.reason))) return;
+    const updated = updateBoundPlanNodesForAgent(agentId, "blocked", event.source || "server");
+    notifyBoundExit(event, updated);
+  }
+}
+
+export function startPlanLiveBindings(): void {
+  if (unsubscribe) return;
+  unsubscribe = subscribeRelayEvents(handlePlanBindingEvent);
+}
+
+export function __resetPlanLiveBindingsForTests(): void {
+  unsubscribe?.();
+  unsubscribe = undefined;
+}

package/src/services/spawn-agent.ts

@@ -36,7 +36,7 @@ import { hasComponentScope, isComponentAuthorizedFor } from "../security";
 import { isPathWithinBase } from "../utils";
 import { McpAuthError, McpNotFoundError } from "../mcp-errors";
 import type { AuthContext } from "./auth-context";
-import type { AgentCard, Command, SpawnApprovalMode, WorkspaceMode } from "../types";
+import type { AgentCard, AgentLifecycle, Command, SpawnApprovalMode, WorkspaceMode } from "../types";
 
 /** The spawn scope every transport must hold (admin `*` / `admin:*` pass; `system` bypasses). */
 const SPAWN_SCOPE = "command:spawn";
@@ -56,6 +56,7 @@ export interface SpawnAgentInput {
   effort?: string;
   approvalMode?: SpawnApprovalMode;
   workspaceMode?: WorkspaceMode;
+  lifecycle?: AgentLifecycle;
   label?: string;
   policyName?: string;
   profile?: string;
@@ -140,6 +141,7 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
   // 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);
+  const lifecycle = input.lifecycle ?? "persistent";
 
   const spawnRequestId = input.spawnRequestId ?? generateSpawnRequestId();
 
@@ -212,6 +214,7 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
       modelParams,
       cwd: resolvedCwd,
       ...(workspaceMode ? { workspaceMode } : {}),
+      lifecycle,
       label: input.label,
       profile: input.profile || undefined,
       agentProfile,
@@ -250,6 +253,7 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
       provider: input.provider,
       orchestratorId: orchestrator.id,
       approvalMode,
+      lifecycle,
       workspaceMode: workspaceMode ?? null,
       label: input.label ?? null,
       commandId: command.id,

package/src/services/team-templates.ts

@@ -0,0 +1,172 @@
+import { isRecord, SPAWN_PROVIDERS, VALID_WORKSPACE_MODES, APPROVAL_MODES, VALID_AGENT_LIFECYCLES } from "agent-relay-sdk";
+import { getTeam, ValidationError } from "../db";
+import { deleteConfig, getConfig, listConfig, setConfig } from "../config-store";
+import { TEAM_TEMPLATE_NAMESPACE } from "../team-template-config";
+import { cleanString, optionalEnum } from "../validation";
+import type { AuthContext } from "./auth-context";
+import { setCallerTeamBrief } from "./team";
+import { spawnAgent, type SpawnAgentInput, type SpawnAgentResult } from "./spawn-agent";
+import type { AgentLifecycle, SpawnApprovalMode, SpawnProvider, TeamTemplate, TeamTemplateCompositionEntry, WorkspaceMode } from "../types";
+
+export interface TeamTemplateInstantiateInput {
+  slug: string;
+  orchestratorId?: unknown;
+  cwd?: unknown;
+  approvalMode?: unknown;
+  workspaceMode?: unknown;
+  lifecycle?: unknown;
+  prompt?: unknown;
+  waitForRegistrationMs?: unknown;
+}
+
+export interface TeamTemplateInstantiateResult {
+  template: TeamTemplate;
+  team: ReturnType<typeof setCallerTeamBrief>["team"];
+  spawned: SpawnAgentResult[];
+}
+
+function slugify(value: string): string {
+  const slug = value.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 120);
+  return slug || "team-template";
+}
+
+function templateSlug(input: Record<string, unknown>): string {
+  return cleanString(input.slug ?? input.id, "slug", { max: 120 }) ?? slugify(cleanString(input.title, "title", { required: true, max: 240 })!);
+}
+
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+function withTimestamps(template: TeamTemplate, existing?: TeamTemplate): TeamTemplate {
+  const now = nowIso();
+  return {
+    ...template,
+    createdAt: existing?.createdAt ?? template.createdAt ?? now,
+    updatedAt: now,
+  };
+}
+
+export function saveTeamTemplate(input: Record<string, unknown>, updatedBy?: string): TeamTemplate {
+  if (input.teamId !== undefined && input.composition !== undefined) {
+    throw new ValidationError("teamId capture and manual composition are mutually exclusive");
+  }
+  if (input.teamId !== undefined) return captureTeamTemplateFromTeam(cleanString(input.teamId, "teamId", { required: true, max: 120 })!, input, updatedBy);
+  const slug = templateSlug(input);
+  const existing = getConfig<TeamTemplate>(TEAM_TEMPLATE_NAMESPACE, slug)?.value;
+  const template = withTimestamps({
+    id: slug,
+    slug,
+    title: cleanString(input.title, "title", { required: true, max: 240 })!,
+    ...(cleanString(input.description, "description", { max: 2000 }) ? { description: cleanString(input.description, "description", { max: 2000 }) } : {}),
+    composition: input.composition as TeamTemplateCompositionEntry[],
+    ...(cleanString(input.brief, "brief", { max: 16_000 }) ? { brief: cleanString(input.brief, "brief", { max: 16_000 }) } : {}),
+    ...(cleanString(input.definitionOfDone, "definitionOfDone", { max: 4000 }) ? { definitionOfDone: cleanString(input.definitionOfDone, "definitionOfDone", { max: 4000 }) } : {}),
+    ...(input.planSkeleton !== undefined ? { planSkeleton: input.planSkeleton as TeamTemplate["planSkeleton"] } : {}),
+  }, existing);
+  return setConfig(TEAM_TEMPLATE_NAMESPACE, template.slug, template, updatedBy).value as TeamTemplate;
+}
+
+export function listTeamTemplates(): TeamTemplate[] {
+  return listConfig<TeamTemplate>(TEAM_TEMPLATE_NAMESPACE).map((entry) => entry.value);
+}
+
+export function getTeamTemplate(slug: string): TeamTemplate | null {
+  return getConfig<TeamTemplate>(TEAM_TEMPLATE_NAMESPACE, slug)?.value ?? null;
+}
+
+export function deleteTeamTemplate(slug: string, updatedBy?: string): boolean {
+  return deleteConfig(TEAM_TEMPLATE_NAMESPACE, slug, updatedBy);
+}
+
+function parseFrozenComposition(raw: string): Array<Record<string, unknown>> {
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    if (!Array.isArray(parsed)) throw new Error("not array");
+    return parsed.filter(isRecord);
+  } catch {
+    throw new ValidationError("team composition snapshot is invalid JSON");
+  }
+}
+
+function compositionFromFrozenSnapshot(raw: string): TeamTemplateCompositionEntry[] {
+  const grouped = new Map<string, TeamTemplateCompositionEntry>();
+  for (const member of parseFrozenComposition(raw)) {
+    const provider = cleanString(member.provider, "composition.provider", { max: 40 });
+    if (!provider) continue;
+    if (!SPAWN_PROVIDERS.includes(provider as SpawnProvider)) throw new ValidationError(`unsupported captured provider: ${provider}`);
+    const model = cleanString(member.model, "composition.model", { max: 120 });
+    const label = cleanString(member.label ?? member.role, "composition.label", { max: 120 }) ?? provider;
+    const key = JSON.stringify({ label, provider, model });
+    const existing = grouped.get(key);
+    if (existing) existing.count += 1;
+    else grouped.set(key, { label, provider: provider as SpawnProvider, ...(model ? { model } : {}), count: 1 });
+  }
+  const composition = [...grouped.values()];
+  if (!composition.length) throw new ValidationError("team composition has no spawnable provider members");
+  return composition;
+}
+
+export function captureTeamTemplateFromTeam(teamId: string, input: Record<string, unknown> = {}, updatedBy?: string): TeamTemplate {
+  const team = getTeam(teamId);
+  if (!team) throw new ValidationError(`team ${teamId} not found`);
+  if (!team.composition) throw new ValidationError("team has no frozen composition snapshot; dissolve it before capture");
+  const title = cleanString(input.title, "title", { max: 240 }) ?? `${team.title ?? team.id} template`;
+  const slug = cleanString(input.slug ?? input.id, "slug", { max: 120 }) ?? slugify(title);
+  const existing = getConfig<TeamTemplate>(TEAM_TEMPLATE_NAMESPACE, slug)?.value;
+  const template = withTimestamps({
+    id: slug,
+    slug,
+    title,
+    ...(cleanString(input.description, "description", { max: 2000 }) ?? team.outcomeSummary ? { description: cleanString(input.description, "description", { max: 2000 }) ?? team.outcomeSummary } : {}),
+    composition: compositionFromFrozenSnapshot(team.composition),
+    ...(team.brief ? { brief: team.brief } : {}),
+    ...(team.definitionOfDone ? { definitionOfDone: team.definitionOfDone } : {}),
+  }, existing);
+  return setConfig(TEAM_TEMPLATE_NAMESPACE, template.slug, template, updatedBy).value as TeamTemplate;
+}
+
+function cleanWait(value: unknown): number {
+  if (value === undefined || value === null) return 0;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0 || value > 30_000) {
+    throw new ValidationError("waitForRegistrationMs must be an integer between 0 and 30000");
+  }
+  return value;
+}
+
+function spawnInputForEntry(template: TeamTemplate, entry: TeamTemplateCompositionEntry, index: number, count: number, input: TeamTemplateInstantiateInput): SpawnAgentInput {
+  return {
+    provider: entry.provider,
+    orchestratorId: cleanString(input.orchestratorId, "orchestratorId", { max: 200 }),
+    cwd: cleanString(input.cwd, "cwd", { max: 500 }),
+    model: entry.model,
+    effort: entry.effort,
+    approvalMode: optionalEnum(input.approvalMode, "approvalMode", APPROVAL_MODES) as SpawnApprovalMode | undefined,
+    workspaceMode: optionalEnum(input.workspaceMode, "workspaceMode", VALID_WORKSPACE_MODES) as WorkspaceMode | undefined,
+    lifecycle: optionalEnum(input.lifecycle, "lifecycle", VALID_AGENT_LIFECYCLES) as AgentLifecycle | undefined,
+    profile: entry.profile,
+    label: count === 1 ? entry.label : `${entry.label} ${index + 1}`,
+    prompt: cleanString(input.prompt, "prompt", { max: 16_000 }) ?? template.brief,
+    tags: ["team-template", `template:${template.slug}`],
+    requestedVia: "team-template",
+    waitForRegistrationMs: cleanWait(input.waitForRegistrationMs),
+  };
+}
+
+export async function instantiateTeamTemplate(input: TeamTemplateInstantiateInput, ctx: AuthContext): Promise<TeamTemplateInstantiateResult> {
+  const slug = cleanString(input.slug, "slug", { required: true, max: 120 })!;
+  const template = getTeamTemplate(slug);
+  if (!template) throw new ValidationError(`team template ${slug} not found`);
+  const teamPayload = setCallerTeamBrief(ctx, {
+    title: template.title,
+    brief: template.brief,
+    definitionOfDone: template.definitionOfDone,
+  });
+  const spawned: SpawnAgentResult[] = [];
+  for (const entry of template.composition) {
+    for (let i = 0; i < entry.count; i++) {
+      spawned.push(await spawnAgent(spawnInputForEntry(template, entry, i, entry.count, input), ctx));
+    }
+  }
+  return { template, team: teamPayload.team, spawned };
+}

package/src/services/transient-agent-reaper.ts

@@ -0,0 +1,108 @@
+import { createCommand } from "../commands-db";
+import { emitRelayEvent } from "../events";
+import { createActivityEvent, getAgent, listAgents, listWorkspaces } from "../db";
+import { notifySystemMessage } from "../notify";
+import { TERMINAL_WORKSPACE_STATUSES } from "../workspace-phase";
+
+const envMsOrDefault = (name: string, fallback: number): number => {
+  const v = Number(process.env[name]);
+  return Number.isFinite(v) && v >= 0 ? v : fallback;
+};
+const transientGraceMs = () => envMsOrDefault("AGENT_RELAY_TRANSIENT_GRACE_MS", 2 * 60 * 1000);
+const transientMaxLandWaitMs = () => envMsOrDefault("AGENT_RELAY_TRANSIENT_MAX_LAND_WAIT_MS", 30 * 60 * 1000);
+const transientTracker = new Map<string, { firstIdleAt: number; lastReapAt?: number; heldNoticeAt?: number }>();
+
+export function resetTransientTrackerForTests(): void {
+  transientTracker.clear();
+}
+
+function transientLandComplete(agentId: string): { complete: boolean; workspaceId?: string; status?: string; reason?: string } {
+  const isolated = listWorkspaces({ ownerAgentId: agentId }).filter((ws) => ws.mode === "isolated");
+  if (!isolated.length) return { complete: true, reason: "no-isolated-workspace" };
+  const live = isolated.find((ws) => !TERMINAL_WORKSPACE_STATUSES.has(ws.status));
+  if (!live) return { complete: true, workspaceId: isolated[0]?.id, status: isolated[0]?.status, reason: "terminal-workspace" };
+  const mergedAt = typeof live.metadata.mergedAt === "number" ? live.metadata.mergedAt : undefined;
+  const landReportedAt = typeof live.metadata.landReportedAt === "number" ? live.metadata.landReportedAt : undefined;
+  if (live.status === "active" && mergedAt !== undefined && mergedAt > (landReportedAt ?? 0)) {
+    return { complete: true, workspaceId: live.id, status: live.status, reason: "recycled-after-land" };
+  }
+  return { complete: false, workspaceId: live.id, status: live.status, reason: "land-pending" };
+}
+
+function notifyTransientHeld(agentId: string, workspaceId: string | undefined, status: string | undefined, waitMs: number): void {
+  const agent = getAgent(agentId);
+  const parent = agent?.spawnedBy;
+  const payload = { kind: "agent.transient_land_hold", agentId, parent, workspaceId, workspaceStatus: status, waitMs };
+  emitRelayEvent({ type: "agent.transient_land_hold", source: "server", subject: agentId, data: payload });
+  createActivityEvent({
+    clientId: `transient-agent-held-${agentId}-${Date.now()}`,
+    kind: "state",
+    title: "Transient agent held pending land",
+    body: `${agentId} is idle but its isolated workspace has not landed; holding unreaped to protect work`,
+    meta: agentId,
+    icon: "ti-hourglass",
+    view: "agents",
+    agentId,
+    metadata: { source: "server", maintenanceJobId: "transient-agent-reaper", ...payload },
+  });
+  if (parent) {
+    notifySystemMessage(parent, {
+      subject: "Transient worker held pending land",
+      body: `Transient agent \`${agentId}\` is idle but still unreaped because workspace \`${workspaceId ?? "unknown"}\` is \`${status ?? "unknown"}\` after ${Math.round(waitMs / 60_000)} min. Its work is being preserved; resolve the land before cleanup.`,
+      payload,
+      replyExpected: false,
+    });
+  }
+}
+
+export function reapTransientAgents(): Record<string, unknown> {
+  const now = Date.now();
+  const grace = transientGraceMs();
+  const maxLandWait = transientMaxLandWaitMs();
+  const seen = new Set<string>();
+  const reaped: string[] = [], held: string[] = [], waiting: string[] = [];
+  for (const agent of listAgents()) {
+    if (agent.lifecycle !== "transient") continue;
+    seen.add(agent.id);
+    if (agent.status !== "idle" || !agent.ready) { transientTracker.delete(agent.id); continue; }
+    const entry = transientTracker.get(agent.id) ?? { firstIdleAt: now };
+    transientTracker.set(agent.id, entry);
+    const idleForMs = now - entry.firstIdleAt;
+    if (idleForMs < grace) { waiting.push(agent.id); continue; }
+    const land = transientLandComplete(agent.id);
+    if (!land.complete) {
+      if (idleForMs >= grace + maxLandWait) {
+        held.push(agent.id);
+        if (!entry.heldNoticeAt) {
+          entry.heldNoticeAt = now;
+          notifyTransientHeld(agent.id, land.workspaceId, land.status, idleForMs);
+        }
+      } else waiting.push(agent.id);
+      continue;
+    }
+    if (entry.lastReapAt) continue;
+    entry.lastReapAt = now;
+    const command = createCommand({
+      type: "agent.shutdown",
+      source: "system",
+      target: agent.id,
+      params: { action: "shutdown", agentId: agent.id, graceful: true, timeoutMs: 10_000, reason: "transient-complete", requestedBy: "transient-agent-reaper", requestedAt: now },
+    });
+    emitRelayEvent({ type: "command.requested", source: command.source, subject: command.id, data: { command } });
+    emitRelayEvent({ type: "agent.exited", source: "server", subject: agent.id, data: { agentId: agent.id, parent: agent.spawnedBy, reason: "transient-complete", workspaceId: land.workspaceId, workspaceStatus: land.status } });
+    createActivityEvent({
+      clientId: `transient-agent-reaped-${agent.id}-${now}`,
+      kind: "state",
+      title: "Transient agent complete",
+      body: "Agent idle grace elapsed and branch work is land-complete; shutdown requested",
+      meta: agent.id,
+      icon: "ti-check",
+      view: "agents",
+      agentId: agent.id,
+      metadata: { source: "server", maintenanceJobId: "transient-agent-reaper", commandId: command.id, reason: "transient-complete", workspaceId: land.workspaceId, landReason: land.reason },
+    });
+    reaped.push(agent.id);
+  }
+  for (const key of transientTracker.keys()) if (!seen.has(key)) transientTracker.delete(key);
+  return { scanned: seen.size, waiting, held, reaped, tracked: transientTracker.size };
+}

package/src/spawn-command.ts

@@ -82,6 +82,7 @@ interface BuildSpawnCommandOptions {
   modelParams?: SpawnModelParams;
 
   workspaceMode?: string;
+  lifecycle?: string;
   label?: string;
   tags?: string[];
   capabilities?: string[];
@@ -123,6 +124,7 @@ export function buildSpawnCommand(opts: BuildSpawnCommandOptions): Record<string
     ...(opts.modelParams ?? {}),
     cwd: opts.cwd,
     ...def(opts.workspaceMode, "workspaceMode"),
+    ...def(opts.lifecycle, "lifecycle"),
     ...def(opts.profile, "profile"),
     ...def(opts.agentProfile, "agentProfile"),
     ...workspaceSpawnParams(),