@runfusion/fusion 0.75.1-beta.2 → 0.76.0-beta.0

package/dist/plugin-sdk/index.js

@@ -5763,6 +5763,7 @@ __export(project_exports, {
   unplannedExecutionBlocks: () => unplannedExecutionBlocks,
   usageEvents: () => usageEvents,
   verificationCache: () => verificationCache,
+  workflowAgentCapacityLeases: () => workflowAgentCapacityLeases,
   workflowPromptOverrides: () => workflowPromptOverrides,
   workflowRunBranches: () => workflowRunBranches,
   workflowRunStepInstances: () => workflowRunStepInstances,
@@ -5871,6 +5872,8 @@ var tasks = projectSchema.table("tasks", {
   nextRecoveryAt: text("next_recovery_at"),
   error: text("error"),
   summary: text("summary"),
+  // FNXC:TaskRecommendations 2026-08-08-05:02: structured completion suggestions remain project-scoped JSONB beside the source task.
+  recommendations: jsonb("recommendations"),
   thinkingLevel: text("thinking_level"),
   // FNXC:Settings-ThinkingLevel 2026-07-13 (merge port): validator/planning reasoning-effort overrides.
   validatorThinkingLevel: text("validator_thinking_level"),
@@ -6451,7 +6454,9 @@ var agents = projectSchema.table("agents", {
   projectId: text("project_id").notNull().default(sql`current_setting('fusion.project_id', true)`),
   id: text("id").notNull(),
   name: text("name").notNull(),
+  /** Deprecated singular compatibility column; canonical roles live in roles JSONB. */
   role: text("role").notNull(),
+  roles: jsonb("roles").notNull().default([]),
   state: text("state").notNull().default("idle"),
   taskId: text("task_id"),
   createdAt: text("created_at").notNull(),
@@ -6575,6 +6580,17 @@ var completionHandoffMarkers = projectSchema.table("completion_handoff_markers",
   foreignKey({ columns: [t.projectId, t.taskId], foreignColumns: [tasks.projectId, tasks.id] }).onDelete("cascade"),
   index("idx_completion_handoff_markers_acceptedAt").on(t.acceptedAt)
 ]);
+var workflowAgentCapacityLeases = projectSchema.table("workflow_agent_capacity_leases", {
+  projectId: text("project_id").notNull().default(sql`current_setting('fusion.project_id', true)`),
+  attemptId: text("attempt_id").notNull(),
+  agentId: text("agent_id").notNull(),
+  createdAt: text("created_at").notNull(),
+  // FNXC:WorkflowAgentRouting 2026-08-07-07:16: A crashed engine cannot run its finally cleanup, so durable workflow capacity leases expire and are reclaimed on the next admission.
+  expiresAt: text("expires_at").notNull()
+}, (t) => [
+  primaryKey({ columns: [t.projectId, t.attemptId] }),
+  index("idx_workflow_agent_capacity_leases_agent").on(t.projectId, t.agentId)
+]);
 var workflowWorkItems = projectSchema.table("workflow_work_items", {
   projectId: text("project_id").notNull().default(sql`current_setting('fusion.project_id', true)`),
   id: text("id").notNull(),
@@ -6595,6 +6611,13 @@ var workflowWorkItems = projectSchema.table("workflow_work_items", {
   sourceColumn: text("source_column"),
   targetColumn: text("target_column"),
   irHash: text("ir_hash"),
+  // FNXC:WorkflowAgentRouting 2026-08-07-03:25:
+  // A workflow claim fences its durable principal and exact template instance.
+  // Session retries must reuse this identity rather than re-routing a task.
+  principalAgentId: text("principal_agent_id"),
+  workflowRole: text("workflow_role"),
+  authorityKind: text("authority_kind"),
+  nodeInstanceId: text("node_instance_id"),
   createdAt: text("created_at").notNull(),
   updatedAt: text("updated_at").notNull()
 }, (t) => [
@@ -8590,6 +8613,7 @@ var BLOCKING_TASK_STATUSES = /* @__PURE__ */ new Set([
 // ../core/src/tasks/in-review-stall.ts
 var DEFAULT_STALE_MERGING_MIN_AGE_MS = 5 * 6e4;
 var DEFAULT_MAX_AUTO_MERGE_RETRIES = 3;
+var CONSECUTIVE_TOOL_FAILURE_RETRY_THRESHOLD = 1;
 
 // ../core/src/config/settings-schema.ts
 var DEFAULT_GLOBAL_SETTINGS = {
@@ -8930,6 +8954,8 @@ var DEFAULT_GLOBAL_SETTINGS = {
   cliAgents: {}
 };
 var DEFAULT_PROJECT_SETTINGS = {
+  // FNXC:TaskRecommendations 2026-08-08-05:02: completion follows-ups stay bounded by default; 0 disables writing them.
+  maxRecommendationsPerTask: 3,
   globalPause: false,
   globalPauseReason: void 0,
   defaultWorkflowId: void 0,
@@ -9098,9 +9124,15 @@ var DEFAULT_PROJECT_SETTINGS = {
    * Project settings own the auto-merge conflict retry cap because existing engine/dashboard consumers already resolve project settings; the default imports core's stall-detection fallback to keep every surface on the historical value of 3.
    */
   maxAutoMergeRetries: DEFAULT_MAX_AUTO_MERGE_RETRIES,
+  /*
+  FNXC:ExecutorToolFailureRetry 2026-08-06-14:56:
+  Fresh projects retry the existing bounded same-model continuation after one
+  terminal tool error. Persisted project values are not migrated, so explicit
+  operator thresholds remain authoritative.
+  */
   executorToolFailureRetryCount: 2,
   executorToolFailureRetryBackoffMs: 2e3,
-  executorToolFailureThreshold: 3,
+  executorToolFailureThreshold: CONSECUTIVE_TOOL_FAILURE_RETRY_THRESHOLD,
   executorModelEscalationEnabled: false,
   executorEscalationProvider: void 0,
   executorEscalationModelId: void 0,
@@ -9136,6 +9168,12 @@ var DEFAULT_PROJECT_SETTINGS = {
   // proportional to the change; the thin merge gate carries cross-cutting
   // coverage. Falls back to package/explicit command when no tests resolve.
   scopeVerificationToChangedFiles: true,
+  /*
+  FNXC:WorkflowAgentRouting 2026-08-07-08:45:
+  Keep the legacy project setting defaulted and persistable for existing clients and
+  configuration records. Workflow-stage routing must ignore its value; durable role
+  principals own scheduler, executor, and mission-stage authority.
+  */
   ephemeralAgentsEnabled: true,
   /*
   FNXC:EphemeralAgentTaskCreation 2026-07-01-00:00:
@@ -9437,6 +9475,23 @@ function isEphemeralAgent(agent) {
 }
 
 // ../core/src/types/agents/agents.ts
+var AGENT_CAPABILITIES = [
+  "triage",
+  "executor",
+  "reviewer",
+  "merger",
+  "scheduler",
+  "engineer",
+  "custom"
+];
+function normalizeAgentRoles(roles, legacyRole) {
+  const values = roles?.length ? roles : legacyRole ? [legacyRole] : [];
+  const unique2 = new Set(values);
+  const normalized = AGENT_CAPABILITIES.filter((role) => unique2.has(role));
+  if (normalized.length !== unique2.size) throw new Error("Agent roles contain an unknown capability");
+  if (normalized.length === 0) throw new Error("Agent requires at least one role");
+  return normalized;
+}
 var AGENT_PERMISSIONS = [
   "tasks:assign",
   // Assign tasks to agents
@@ -9558,6 +9613,7 @@ function getDefaultHeartbeatProcedurePath(agentId, agentName) {
 function agentToConfigSnapshot(agent) {
   return {
     name: agent.name,
+    roles: [...agent.roles],
     role: agent.role,
     title: agent.title,
     icon: agent.icon,
@@ -9892,6 +9948,41 @@ function resolveColumnFlags(column) {
   return getTraitRegistry().resolveColumnFlags(column);
 }
 
+// ../core/src/workflows/workflow-ir-types.ts
+var WORKFLOW_AGENT_ROLES = ["triage", "executor", "reviewer", "merger"];
+function isWorkflowAgentRole(value) {
+  return typeof value === "string" && WORKFLOW_AGENT_ROLES.includes(value);
+}
+function classifyWorkflowAgentNode(node) {
+  if (node.kind === "step-review") return "reviewer";
+  if (node.kind !== "prompt" && node.kind !== "script") return void 0;
+  switch (node.config?.seam) {
+    /*
+     * FNXC:WorkflowAgentRouting 2026-08-07-05:52:
+     * Planning, independent review, and promotion seams each launch work under
+     * their permanent stage owner. Classify those production seams here rather
+     * than treating their handoff worker as an unowned lifecycle operation.
+     * Only pure handoff/scheduling seams remain principal-free.
+     */
+    case "planning":
+      return "triage";
+    case "execute":
+    case "step-execute":
+      return "executor";
+    case "review":
+      return "reviewer";
+    case "merge":
+      return "merger";
+    case "review-handoff":
+    case "schedule":
+      return void 0;
+    default: {
+      const explicit = node.config?.workflowRole;
+      return isWorkflowAgentRole(explicit) ? explicit : void 0;
+    }
+  }
+}
+
 // ../core/src/workflows/workflow-extension-types.ts
 function workflowExtensionRegistryId(pluginId, extensionId) {
   return `plugin:${pluginId}:${extensionId}`;
@@ -10880,6 +10971,20 @@ function validateCredentialInstanceIdConfig(nodes2) {
     if (Array.isArray(templateNodes)) validateCredentialInstanceIdConfig(templateNodes);
   }
 }
+function validateReviewerAgentOverrides(nodes2) {
+  for (const node of nodes2) {
+    if (node.reviewerAgentId !== void 0) {
+      if (typeof node.reviewerAgentId !== "string" || !node.reviewerAgentId.trim()) {
+        throw new WorkflowIrError(`Workflow node '${node.id}' reviewerAgentId must be a non-empty string`);
+      }
+      if (classifyWorkflowAgentNode(node) !== "reviewer") {
+        throw new WorkflowIrError(`Workflow node '${node.id}' reviewerAgentId is only legal on reviewer-session nodes`);
+      }
+    }
+    const templateNodes = node.config?.template?.nodes;
+    if (Array.isArray(templateNodes)) validateReviewerAgentOverrides(templateNodes);
+  }
+}
 function validateThinkingLevelConfig(nodes2) {
   for (const node of nodes2) {
     const value = node.config?.thinkingLevel;
@@ -11495,6 +11600,7 @@ function validateV2(ir) {
   validateStepExecutePlacement(ir.nodes);
   validateThinkingLevelConfig(ir.nodes);
   validateCredentialInstanceIdConfig(ir.nodes);
+  validateReviewerAgentOverrides(ir.nodes);
   for (const node of ir.nodes) {
     if (node.kind === "foreach") validateForeach(node, topLevelIds, columnIds);
     if (node.kind === "loop") validateLoop(node, topLevelIds, columnIds);
@@ -15728,7 +15834,8 @@ function normalizePermissions(raw) {
   return permissions;
 }
 function computeAccessState(agent) {
-  const roleDefaultPermissions = new Set(ROLE_DEFAULT_PERMISSIONS[agent.role] ?? []);
+  const roles = agent.roles?.length ? agent.roles : [agent.role];
+  const roleDefaultPermissions = new Set(roles.flatMap((role) => ROLE_DEFAULT_PERMISSIONS[role] ?? []));
   const explicitPermissions = normalizePermissions(agent.permissions ?? {});
   const resolvedPermissions = new Set(roleDefaultPermissions);
   for (const permission of explicitPermissions) {
@@ -15759,6 +15866,9 @@ var IMPLEMENTATION_TASK_COLUMNS = /* @__PURE__ */ new Set([
   "in-progress",
   "in-review"
 ]);
+function agentRoles(agent) {
+  return agent.roles?.length ? agent.roles : agent.role ? [agent.role] : [];
+}
 function getAgentAssignmentPolicy(agent) {
   const raw = (agent.runtimeConfig ?? {})["assignmentPolicy"];
   return raw === "explicit-only" || raw === "none" ? raw : "auto";
@@ -15773,10 +15883,10 @@ function isImplementationTask(task) {
   return IMPLEMENTATION_TASK_COLUMNS.has(task.column);
 }
 function isExecutorRoleAgent(agent) {
-  return agent.role === "executor";
+  return agentRoles(agent).includes("executor");
 }
 function isEngineerRoleAgent(agent) {
-  return agent.role === "engineer";
+  return agentRoles(agent).includes("engineer");
 }
 function canAgentTakeImplementationTaskForExplicitRouting(agent, task) {
   if (!isImplementationTask(task)) return true;
@@ -15825,7 +15935,8 @@ function formatRoleMismatchReason(agent, task) {
   if (policy !== "auto") {
     return `Agent ${agent.id} has assignmentPolicy "${policy}"; implementation task ${task.id} cannot be routed to it${policy === "none" ? " by any path (no override supported)" : " automatically \u2014 explicit routing only"}.`;
   }
-  return `Agent ${agent.id} has role "${agent.role}"; implementation task ${task.id} requires an "executor"-role agent by default, with durable "engineer" supported only for explicit routing. Pass override=true to bypass.`;
+  const roles = agentRoles(agent);
+  return `Agent ${agent.id} has roles "${roles.join(", ") || "none"}"; implementation task ${task.id} requires an "executor"-role agent by default, with durable "engineer" supported only for explicit routing. Pass override=true to bypass.`;
 }
 
 // ../core/src/agents/agent-permission-policy.ts
@@ -15948,6 +16059,7 @@ var agentColumns = {
   id: project_exports.agents.id,
   name: project_exports.agents.name,
   role: project_exports.agents.role,
+  roles: project_exports.agents.roles,
   state: project_exports.agents.state,
   taskId: project_exports.agents.taskId,
   createdAt: project_exports.agents.createdAt,
@@ -15978,6 +16090,7 @@ function agentToData(agent) {
   return {
     id: agent.id,
     name: agent.name,
+    roles: agent.roles,
     role: agent.role,
     state: agent.state,
     taskId: agent.taskId,
@@ -16012,6 +16125,7 @@ async function writeAgent(handle, agent, projectId) {
     id: agent.id,
     name: agent.name,
     role: agent.role,
+    roles: agent.roles,
     state: agent.state,
     taskId: agent.taskId ?? null,
     createdAt: agent.createdAt,
@@ -16024,6 +16138,7 @@ async function writeAgent(handle, agent, projectId) {
     set: {
       name: agent.name,
       role: agent.role,
+      roles: agent.roles,
       state: agent.state,
       taskId: agent.taskId ?? null,
       updatedAt: agent.updatedAt,
@@ -16045,6 +16160,7 @@ function mergeAgentRow(row) {
     ...data,
     id: row.id,
     name: row.name,
+    roles: row.roles?.length ? row.roles : [row.role],
     role: row.role,
     state: row.state,
     taskId: row.taskId ?? void 0,
@@ -16374,8 +16490,62 @@ var FsWatchPollController = class {
   }
 };
 
+// ../core/src/agents/workflow-role-agent-defaults.ts
+var BUILTIN_WORKFLOW_AGENT_BUNDLE_CONFIG = {
+  mode: "managed",
+  entryFile: "AGENTS.md",
+  files: ["AGENTS.md", "soul.md"]
+};
+var BUILTIN_WORKFLOW_ROLE_AGENT_DEFAULTS = {
+  triage: {
+    role: "triage",
+    name: "Workflow Planner",
+    title: "Built-in workflow planning owner",
+    instructionsText: "You are the Workflow Planner. Turn incoming work into clear, bounded, testable plans. Identify the user outcome, constraints, affected surfaces, and acceptance evidence before release. Keep planning distinct from implementation: do not claim code is complete, invent decisions, or bypass approval gates. Communicate concisely, make uncertainty explicit, and leave an executable plan that another agent can follow.",
+    soul: "Calm, structured, and curious. You reduce ambiguity without adding ceremony, respect operator intent, and prefer concrete evidence over confident guesses."
+  },
+  executor: {
+    role: "executor",
+    name: "Workflow Executor",
+    title: "Built-in workflow execution owner",
+    instructionsText: "You are the Workflow Executor. Implement the approved scope with production-quality, maintainable changes. Read the task specification, preserve existing behavior outside scope, and verify the smallest relevant checks before reporting completion. Do not redesign workflow policy, broaden permissions, or conceal blockers; record concrete evidence and surface a genuine dependency when work cannot proceed. Communicate changes and verification precisely.",
+    soul: "Methodical, practical, and accountable. You favor small safe steps, protect user work, and let tests and observable behavior guide your confidence."
+  },
+  reviewer: {
+    role: "reviewer",
+    name: "Workflow Reviewer",
+    title: "Built-in workflow review owner",
+    instructionsText: "You are the Workflow Reviewer. Independently assess whether the submitted work satisfies its specification, preserves system invariants, and has credible verification. Focus on correctness, regressions, security, maintainability, and missing evidence rather than rewriting the implementation. State actionable findings with severity and rationale; approve only when the evidence supports it. Do not perform implementation or override workflow gates.",
+    soul: "Independent, exacting, and fair. You are skeptical of unsupported claims, respectful in feedback, and clear about what would make the work safe to accept."
+  },
+  merger: {
+    role: "merger",
+    name: "Workflow Merger",
+    title: "Built-in workflow merge owner",
+    instructionsText: "You are the Workflow Merger. Integrate only work that has met the project\u2019s configured completion and review requirements. Protect the target branch, inspect merge state and conflicts carefully, and preserve unrelated work. Do not substitute judgment for missing approval, bypass safeguards, or silently discard changes. Report the integration result, any conflicts, and the evidence used to make the decision.",
+    soul: "Deliberate, conservative, and transparent. You optimize for repository integrity, treat uncertainty as a reason to stop, and communicate operational state plainly."
+  }
+};
+var BUILTIN_WORKFLOW_ROLE_AGENT_DEFAULT_LIST = Object.values(BUILTIN_WORKFLOW_ROLE_AGENT_DEFAULTS);
+
 // ../core/src/agents/agent-store.ts
 var agentStoreLog = createLogger("agent-store");
+function isCanonicalOrPartialBuiltinWorkflowBundle(config2) {
+  if (config2?.mode !== "managed" || config2.entryFile !== "AGENTS.md") return false;
+  return config2.files.every((file) => (file === "AGENTS.md" || file === "soul.md") && config2.files.indexOf(file) === config2.files.lastIndexOf(file));
+}
+function isCompleteBuiltinWorkflowBundle(config2) {
+  return isCanonicalOrPartialBuiltinWorkflowBundle(config2) && config2.files.length === BUILTIN_WORKFLOW_AGENT_BUNDLE_CONFIG.files.length;
+}
+function compareBuiltinWorkflowOwnerAge(a, b) {
+  const aTime = Date.parse(a.createdAt);
+  const bTime = Date.parse(b.createdAt);
+  const aValid = Number.isFinite(aTime);
+  const bValid = Number.isFinite(bTime);
+  if (aValid && bValid && aTime !== bTime) return aTime - bTime;
+  if (aValid !== bValid) return aValid ? -1 : 1;
+  return a.id.localeCompare(b.id);
+}
 var DEFAULT_AGENT_HEARTBEAT_INTERVAL_MS = 36e5;
 function normalizeStoredPermissions(raw) {
   if (!raw) return void 0;
@@ -16486,6 +16656,73 @@ var AgentStore = class _AgentStore extends EventEmitter {
     }
     return projectId;
   }
+  /** The durable project partition used by workflow routing and capacity leases. */
+  get workflowProjectId() {
+    return this.asyncLayer?.projectId;
+  }
+  /**
+   * FNXC:WorkflowAgentRouting 2026-08-07-05:52:
+   * Workflow capacity is a PostgreSQL lease rather than a process-local count.
+   * The project advisory lock serializes project then agent admission across
+   * engine processes; model work starts only after this short transaction ends.
+   */
+  async acquireWorkflowSessionCapacity(input) {
+    if (!this.asyncLayer) return "acquired";
+    const projectId = this.backendProjectId;
+    const now = /* @__PURE__ */ new Date();
+    const expiresAt = new Date(now.getTime() + (input.leaseDurationMs ?? 10 * 6e4)).toISOString();
+    return this.asyncLayer.transactionImmediate(async (tx) => {
+      await tx.execute(sql`SELECT pg_advisory_xact_lock(hashtext(${projectId}), hashtext('workflow-agent-capacity'))`);
+      await tx.delete(project_exports.workflowAgentCapacityLeases).where(and(
+        eq(project_exports.workflowAgentCapacityLeases.projectId, projectId),
+        lte(project_exports.workflowAgentCapacityLeases.expiresAt, now.toISOString())
+      ));
+      const existing = await tx.select({ attemptId: project_exports.workflowAgentCapacityLeases.attemptId }).from(project_exports.workflowAgentCapacityLeases).where(and(
+        eq(project_exports.workflowAgentCapacityLeases.projectId, projectId),
+        eq(project_exports.workflowAgentCapacityLeases.attemptId, input.attemptId)
+      )).limit(1);
+      if (existing[0]) return "acquired";
+      const projectCount = await tx.select({ count: sql`count(*)::int` }).from(project_exports.workflowAgentCapacityLeases).where(eq(project_exports.workflowAgentCapacityLeases.projectId, projectId));
+      if (input.maxProjectSessions !== void 0 && (projectCount[0]?.count ?? 0) >= input.maxProjectSessions) return "project-capacity";
+      const agentCount = await tx.select({ count: sql`count(*)::int` }).from(project_exports.workflowAgentCapacityLeases).where(and(
+        eq(project_exports.workflowAgentCapacityLeases.projectId, projectId),
+        eq(project_exports.workflowAgentCapacityLeases.agentId, input.agentId)
+      ));
+      if (input.maxAgentSessions !== void 0 && (agentCount[0]?.count ?? 0) >= input.maxAgentSessions) return "agent-capacity";
+      await tx.insert(project_exports.workflowAgentCapacityLeases).values({
+        projectId,
+        agentId: input.agentId,
+        attemptId: input.attemptId,
+        createdAt: now.toISOString(),
+        expiresAt
+      });
+      return "acquired";
+    });
+  }
+  /** Renew only the caller's project-scoped attempt; a reclaimed lease never resurrects. */
+  async renewWorkflowSessionCapacity(attemptId, leaseDurationMs = 10 * 6e4) {
+    if (!this.asyncLayer) return true;
+    const now = /* @__PURE__ */ new Date();
+    const result = await this.asyncLayer.db.update(project_exports.workflowAgentCapacityLeases).set({ expiresAt: new Date(now.getTime() + leaseDurationMs).toISOString() }).where(and(
+      eq(project_exports.workflowAgentCapacityLeases.projectId, this.backendProjectId),
+      eq(project_exports.workflowAgentCapacityLeases.attemptId, attemptId),
+      /*
+       * FNXC:WorkflowAgentRouting 2026-08-07-07:30:
+       * Renew a currently live lease only. An expired row may already have
+       * been reclaimed by another engine's admission transaction.
+       */
+      gt(project_exports.workflowAgentCapacityLeases.expiresAt, now.toISOString())
+    )).returning({ attemptId: project_exports.workflowAgentCapacityLeases.attemptId });
+    return result.length > 0;
+  }
+  /** Release is project-scoped and idempotent so cancellation and recovery may race safely. */
+  async releaseWorkflowSessionCapacity(attemptId) {
+    if (!this.asyncLayer) return;
+    await this.asyncLayer.db.delete(project_exports.workflowAgentCapacityLeases).where(and(
+      eq(project_exports.workflowAgentCapacityLeases.projectId, this.backendProjectId),
+      eq(project_exports.workflowAgentCapacityLeases.attemptId, attemptId)
+    ));
+  }
   get db() {
     throw new Error("SQLite Database is not available in backend mode (asyncLayer injected)");
   }
@@ -16500,7 +16737,7 @@ var AgentStore = class _AgentStore extends EventEmitter {
    */
   async init() {
     await mkdir(this.agentsDir, { recursive: true });
-    return;
+    await this.provisionBuiltinWorkflowRoleAgents();
   }
   /**
    * One-shot migration that re-points every non-ephemeral agent off the
@@ -16662,8 +16899,8 @@ var AgentStore = class _AgentStore extends EventEmitter {
    * @param name - Agent name to match exactly
    * @returns Matching non-ephemeral agent, or null when none exists
    */
-  async findAgentByName(name) {
-    const agents2 = await findAgentRowsByName(this.asyncLayer.db, name);
+  async findAgentByName(name, executor) {
+    const agents2 = await findAgentRowsByName(executor ?? this.asyncLayer.db, name);
     for (const agent of agents2) {
       if (!isEphemeralAgent(agent)) {
         return this.parseAgent(agent);
@@ -16698,18 +16935,16 @@ var AgentStore = class _AgentStore extends EventEmitter {
    * @returns The created agent
    * @throws Error if input is invalid or a duplicate non-ephemeral name exists
    */
-  async createAgent(input) {
+  async createAgent(input, executor) {
     if (!input.name?.trim()) {
       throw new Error("Agent name is required");
     }
-    if (!input.role) {
-      throw new Error("Agent role is required");
-    }
+    const roles = normalizeAgentRoles(input.roles, input.role);
     const normalizedName = input.name.trim();
     const metadata = input.metadata ?? {};
-    const ephemeral = isEphemeralAgent({ metadata, name: input.name, role: input.role, reportsTo: input.reportsTo });
+    const ephemeral = isEphemeralAgent({ metadata, name: input.name, role: roles[0], reportsTo: input.reportsTo });
     if (!ephemeral) {
-      const existing = await this.findAgentByName(normalizedName);
+      const existing = await this.findAgentByName(normalizedName, executor);
       if (existing) {
         throw new Error(`Agent with name "${normalizedName}" already exists (agentId: ${existing.id})`);
       }
@@ -16722,7 +16957,8 @@ var AgentStore = class _AgentStore extends EventEmitter {
     const agent = {
       id: agentId,
       name: normalizedName,
-      role: input.role,
+      roles,
+      role: roles[0],
       // Non-ephemeral agents start active so they immediately participate in
       // heartbeat scheduling; ephemeral/task-worker agents start idle and are
       // activated by the engine when work is assigned.
@@ -16744,7 +16980,7 @@ var AgentStore = class _AgentStore extends EventEmitter {
       ...input.bundleConfig && { bundleConfig: input.bundleConfig },
       ...resolvedHeartbeatProcedurePath && { heartbeatProcedurePath: resolvedHeartbeatProcedurePath }
     };
-    await this.writeAgent(agent);
+    await this.writeAgent(agent, executor);
     this.emit("agent:created", agent);
     return agent;
   }
@@ -17087,10 +17323,12 @@ var AgentStore = class _AgentStore extends EventEmitter {
       const beforeSnapshot = agentToConfigSnapshot(agent);
       const updatedAt = (/* @__PURE__ */ new Date()).toISOString();
       const normalizedUpdatedPermissionPolicy = "permissionPolicy" in updates && updates.permissionPolicy !== void 0 ? normalizeAgentPermissionPolicy(updates.permissionPolicy) : updates.permissionPolicy;
+      const roles = updates.roles !== void 0 || updates.role !== void 0 ? normalizeAgentRoles(updates.roles, updates.role) : agent.roles;
       const updated = {
         ...agent,
         name: nextName ?? agent.name,
-        role: updates.role ?? agent.role,
+        roles,
+        role: roles[0],
         metadata: updates.metadata !== void 0 ? updates.metadata : agent.metadata,
         updatedAt,
         ..."title" in updates && { title: updates.title },
@@ -17625,12 +17863,81 @@ var AgentStore = class _AgentStore extends EventEmitter {
    * @param filter - Optional filter criteria
    * @returns Array of agents
    */
-  async listAgents(filter) {
-    const agents2 = await listAgentRows(this.asyncLayer.db, {
-      state: filter?.state,
-      role: filter?.role
+  async listAgents(filter, executor) {
+    const agents2 = await listAgentRows(executor ?? this.asyncLayer.db, { state: filter?.state });
+    return agents2.map((a) => this.parseAgent(a)).filter((agent) => !filter?.role || agent.roles.includes(filter.role)).filter((agent) => filter?.includeEphemeral === true || !isEphemeralAgent(agent));
+  }
+  /**
+   * Idempotently seed the permanent owners that route built-in workflow stages.
+   * Matching operator-created agents are intentionally not reused: provenance
+   * makes upgrade repair deterministic while operators remain free to add pool
+   * members with the same tag.
+   */
+  async provisionBuiltinWorkflowRoleAgents() {
+    const provision = async (executor) => {
+      const existing = await this.listAgents({ includeEphemeral: true }, executor);
+      const supportedRoles = new Set(BUILTIN_WORKFLOW_ROLE_AGENT_DEFAULT_LIST.map(({ role }) => role));
+      const groups = /* @__PURE__ */ new Map();
+      for (const agent of existing) {
+        const role = agent.metadata?.workflowRole;
+        if (agent.metadata?.builtInWorkflowRole === true && typeof role === "string" && supportedRoles.has(role)) {
+          const group = groups.get(role) ?? [];
+          group.push(agent);
+          groups.set(role, group);
+        }
+      }
+      const winners = /* @__PURE__ */ new Map();
+      for (const [role, group] of groups) {
+        group.sort(compareBuiltinWorkflowOwnerAge);
+        winners.set(role, group[0]);
+        for (const loser of group.slice(1)) {
+          const { builtInWorkflowRole: _builtIn, workflowRole: _role, ...metadata } = loser.metadata;
+          await this.writeAgent({ ...loser, metadata, updatedAt: (/* @__PURE__ */ new Date()).toISOString() }, executor);
+        }
+      }
+      const result = [];
+      for (const definition of BUILTIN_WORKFLOW_ROLE_AGENT_DEFAULT_LIST) {
+        let agent = winners.get(definition.role);
+        if (!agent) {
+          agent = await this.createAgent({
+            name: definition.name,
+            roles: [definition.role],
+            title: definition.title,
+            metadata: { builtInWorkflowRole: true, workflowRole: definition.role },
+            runtimeConfig: { enabled: false },
+            instructionsText: definition.instructionsText,
+            soul: definition.soul,
+            bundleConfig: { ...BUILTIN_WORKFLOW_AGENT_BUNDLE_CONFIG, files: [...BUILTIN_WORKFLOW_AGENT_BUNDLE_CONFIG.files] }
+          }, executor);
+        } else {
+          const canonicalOrPartialBundle = isCanonicalOrPartialBuiltinWorkflowBundle(agent.bundleConfig);
+          const customInstructions = Boolean(agent.instructionsPath?.trim()) || agent.bundleConfig?.mode === "external" || agent.bundleConfig !== void 0 && !canonicalOrPartialBundle || Boolean(agent.instructionsText?.trim()) && agent.instructionsText !== definition.instructionsText;
+          const updates = {};
+          if (!customInstructions && !agent.instructionsText?.trim()) updates.instructionsText = definition.instructionsText;
+          if (!agent.soul?.trim()) updates.soul = definition.soul;
+          if (!customInstructions && !isCompleteBuiltinWorkflowBundle(agent.bundleConfig)) {
+            updates.bundleConfig = { ...BUILTIN_WORKFLOW_AGENT_BUNDLE_CONFIG, files: [...BUILTIN_WORKFLOW_AGENT_BUNDLE_CONFIG.files] };
+          }
+          if (Object.keys(updates).length > 0) {
+            agent = { ...agent, ...updates, updatedAt: (/* @__PURE__ */ new Date()).toISOString() };
+            await this.writeAgent(agent, executor);
+          }
+        }
+        result.push(agent);
+      }
+      return result;
+    };
+    if (!this.asyncLayer) {
+      const agents3 = await provision();
+      await Promise.all(agents3.map((agent) => this.materializeBuiltinWorkflowRoleBundle(agent)));
+      return agents3;
+    }
+    const agents2 = await this.asyncLayer.transactionImmediate(async (tx) => {
+      await tx.execute(sql`SELECT pg_advisory_xact_lock(hashtext(${this.backendProjectId}), hashtext('builtin-workflow-role-provisioning'))`);
+      return provision(tx);
     });
-    return agents2.map((a) => this.parseAgent(a)).filter((agent) => filter?.includeEphemeral === true || !isEphemeralAgent(agent));
+    await Promise.all(agents2.map((agent) => this.materializeBuiltinWorkflowRoleBundle(agent)));
+    return agents2;
   }
   /**
    * Create an API key for an agent.
@@ -18198,6 +18505,29 @@ var AgentStore = class _AgentStore extends EventEmitter {
     }
     return null;
   }
+  /** Seed only missing or blank default-owned mirror files after the provisioning transaction commits. */
+  async materializeBuiltinWorkflowRoleBundle(agent) {
+    return this.withLock(agent.id, async () => {
+      const role = agent.metadata?.workflowRole;
+      const definition = BUILTIN_WORKFLOW_ROLE_AGENT_DEFAULT_LIST.find((candidate) => candidate.role === role);
+      if (!definition || agent.metadata?.builtInWorkflowRole !== true) return;
+      const config2 = agent.bundleConfig;
+      if (!isCanonicalOrPartialBuiltinWorkflowBundle(config2)) return;
+      if (agent.instructionsPath?.trim() || agent.instructionsText?.trim() && agent.instructionsText !== definition.instructionsText) return;
+      const bundleDir = await this.resolveCompatibleBundleDir(agent.id, true);
+      await mkdir(bundleDir, { recursive: true });
+      for (const [file, content] of [["AGENTS.md", definition.instructionsText], ["soul.md", definition.soul]]) {
+        const path = join(bundleDir, file);
+        let current = "";
+        try {
+          current = await readFile(path, "utf-8");
+        } catch (error) {
+          if (error.code !== "ENOENT") throw error;
+        }
+        if (!current.trim()) await writeFile(path, content, "utf-8");
+      }
+    });
+  }
   getCanonicalBundleDir(agent) {
     return join(this.agentsDir, getCanonicalAgentInstructionsBundleDirName(agent.name, agent.id));
   }
@@ -18320,6 +18650,7 @@ var AgentStore = class _AgentStore extends EventEmitter {
       ...data,
       id: row.id,
       name: row.name,
+      roles: data.roles?.length ? data.roles : [row.role],
       role: row.role,
       state: row.state,
       taskId: row.taskId ?? void 0,
@@ -18353,7 +18684,8 @@ var AgentStore = class _AgentStore extends EventEmitter {
     return {
       id: data.id,
       name: data.name,
-      role: data.role,
+      roles: normalizeAgentRoles(data.roles, data.role),
+      role: normalizeAgentRoles(data.roles, data.role)[0],
       state: data.state,
       taskId: data.taskId,
       createdAt: data.createdAt,
@@ -18379,8 +18711,8 @@ var AgentStore = class _AgentStore extends EventEmitter {
       heartbeatProcedurePath: data.heartbeatProcedurePath
     };
   }
-  async writeAgent(agent) {
-    await writeAgent(this.asyncLayer.db, agent, this.asyncLayer.projectId);
+  async writeAgent(agent, executor) {
+    await writeAgent(executor ?? this.asyncLayer.db, agent, this.asyncLayer.projectId);
     return;
   }
   /**