@signalridge/pi-workflows 1.3.2 → 1.5.0

package/src/orchestrator.ts

@@ -0,0 +1,478 @@
+/**
+ * Named, deterministic task-graph orchestration for workflow scripts.
+ *
+ * The script runtime deliberately keeps model/session policy in pi-subagents;
+ * this module only schedules script callbacks. Tasks are executed in stable
+ * declaration-order layers: all tasks whose dependencies completed form one
+ * barrier, and the next layer is discovered only after that barrier settles.
+ * That makes dynamic graphs replayable even when child agents finish in a
+ * different order.
+ */
+
+export const MAX_ORCHESTRATION_TASKS = 128;
+export const MAX_ORCHESTRATION_TASK_ID = 128;
+export const MAX_ORCHESTRATION_PHASE = 512;
+export const MAX_ORCHESTRATION_DESCRIPTION = 2_000;
+export const MAX_ORCHESTRATION_RETRIES = 3;
+
+export type OrchestrationErrorPolicy = "skip-dependents" | "continue" | "fail-fast";
+export type OrchestrationTaskStatus = "pending" | "running" | "completed" | "failed" | "skipped";
+export type OrchestrationTaskTerminalStatus = Exclude<OrchestrationTaskStatus, "pending" | "running">;
+
+export interface OrchestrationTaskContext {
+  readonly id: string;
+  /** One-based attempt number for this task callback. */
+  readonly attempt: number;
+  /** Completed values plus null for failed/skipped dependencies. */
+  readonly results: Readonly<Record<string, unknown>>;
+  /** A detached status snapshot for every declared task. */
+  readonly statuses: Readonly<Record<string, OrchestrationTaskStatus>>;
+}
+
+export interface OrchestrationTask {
+  readonly id: string;
+  readonly dependsOn: readonly string[];
+  readonly phase?: string;
+  readonly description?: string;
+  readonly retries: number;
+  readonly run: (context: OrchestrationTaskContext) => unknown | Promise<unknown>;
+}
+
+export interface OrchestrationOptions {
+  readonly onError: OrchestrationErrorPolicy;
+}
+
+export interface OrchestrationTaskResult {
+  readonly id: string;
+  readonly status: OrchestrationTaskTerminalStatus;
+  /** Failed and skipped tasks expose null so downstream JSON is stable. */
+  readonly value: unknown;
+  readonly attempts: number;
+  readonly error?: string;
+}
+
+export interface OrchestrationResult {
+  /** Every task id appears once; failed/skipped values are null. */
+  readonly results: Record<string, unknown>;
+  /** Every task id appears once in declaration order. */
+  readonly tasks: Record<string, OrchestrationTaskResult>;
+}
+
+export interface OrchestrationTaskEvent {
+  readonly type: "task";
+  readonly [key: string]: unknown;
+  readonly stage: "start" | "retry" | "end" | "skip";
+  readonly taskId: string;
+  readonly phase?: string;
+  readonly attempt: number;
+  readonly status?: OrchestrationTaskTerminalStatus;
+  readonly error?: string;
+}
+
+export interface OrchestrationHooks {
+  /** Throw when the enclosing workflow has been cancelled. */
+  readonly throwIfAborted?: () => void;
+  /** Return true for infrastructure/fatal errors that must escape the graph. */
+  readonly isFatal?: (error: unknown) => boolean;
+  /** Render ordinary task failures into bounded diagnostics. */
+  readonly formatError?: (error: unknown) => string;
+  /** Observe task transitions; listener failures never affect scheduling. */
+  readonly onEvent?: (event: OrchestrationTaskEvent) => void;
+}
+
+interface RawRecord {
+  readonly [key: string]: unknown;
+}
+
+interface MutableTaskResult {
+  readonly id: string;
+  status: OrchestrationTaskStatus;
+  value: unknown;
+  attempts: number;
+  error?: string;
+  errorValue?: unknown;
+}
+
+function isRecord(value: unknown): value is RawRecord {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readBoundedString(value: unknown, label: string, limit: number): string {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new TypeError(`${label} must be a non-empty string`);
+  }
+  const normalized = value.trim();
+  if (normalized.length > limit) throw new TypeError(`${label} exceeds ${limit} characters`);
+  return normalized;
+}
+
+function readDependencies(raw: RawRecord, label: string): string[] {
+  const hasCamel = Object.hasOwn(raw, "dependsOn");
+  const hasSnake = Object.hasOwn(raw, "depends_on");
+  if (hasCamel && hasSnake) throw new TypeError(`${label} cannot contain both dependsOn and depends_on`);
+  const value = hasCamel ? raw.dependsOn : hasSnake ? raw.depends_on : undefined;
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) throw new TypeError(`${label}.dependsOn must be an array`);
+  const dependencies: string[] = [];
+  for (const [index, dependency] of value.entries()) {
+    const normalized = readBoundedString(dependency, `${label}.dependsOn[${index}]`, MAX_ORCHESTRATION_TASK_ID);
+    if (dependencies.includes(normalized)) throw new TypeError(`${label}.dependsOn repeats "${normalized}"`);
+    dependencies.push(normalized);
+  }
+  return dependencies;
+}
+
+function readRetries(value: unknown, label: string): number {
+  if (value === undefined) return 0;
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 0 || value > MAX_ORCHESTRATION_RETRIES) {
+    throw new TypeError(`${label}.retries must be an integer from 0 to ${MAX_ORCHESTRATION_RETRIES}`);
+  }
+  return value;
+}
+
+function assertKnownKeys(raw: RawRecord, label: string): void {
+  const allowed = new Set(["id", "dependsOn", "depends_on", "phase", "description", "retries", "run"]);
+  for (const key of Object.keys(raw)) {
+    if (!allowed.has(key)) throw new TypeError(`${label} contains unsupported field "${key}"`);
+  }
+}
+
+/** Validate and normalize a runtime task list without executing callbacks. */
+export function normalizeOrchestration(
+  rawTasks: unknown,
+  rawOptions: unknown = undefined,
+): { tasks: OrchestrationTask[]; options: OrchestrationOptions } {
+  if (!Array.isArray(rawTasks)) throw new TypeError("orchestrate() expects an array of task objects");
+  if (rawTasks.length > MAX_ORCHESTRATION_TASKS) {
+    throw new TypeError(`orchestrate() accepts at most ${MAX_ORCHESTRATION_TASKS} tasks`);
+  }
+
+  const tasks: OrchestrationTask[] = [];
+  const ids = new Set<string>();
+  for (const [index, rawValue] of rawTasks.entries()) {
+    const label = `orchestrate() task[${index}]`;
+    if (!isRecord(rawValue)) throw new TypeError(`${label} must be an object`);
+    assertKnownKeys(rawValue, label);
+    const id = readBoundedString(rawValue.id, `${label}.id`, MAX_ORCHESTRATION_TASK_ID);
+    if (id === "__proto__" || id === "constructor" || id === "prototype") {
+      throw new TypeError(`${label}.id uses a reserved key name`);
+    }
+    if (ids.has(id)) throw new TypeError(`orchestrate() contains duplicate task id "${id}"`);
+    ids.add(id);
+
+    if (typeof rawValue.run !== "function") throw new TypeError(`${label}.run must be a function`);
+    const dependsOn = readDependencies(rawValue, label);
+    const phase =
+      rawValue.phase === undefined
+        ? undefined
+        : readBoundedString(rawValue.phase, `${label}.phase`, MAX_ORCHESTRATION_PHASE);
+    const description =
+      rawValue.description === undefined
+        ? undefined
+        : readBoundedString(rawValue.description, `${label}.description`, MAX_ORCHESTRATION_DESCRIPTION);
+    tasks.push({
+      id,
+      dependsOn,
+      ...(phase === undefined ? {} : { phase }),
+      ...(description === undefined ? {} : { description }),
+      retries: readRetries(rawValue.retries, label),
+      run: rawValue.run as OrchestrationTask["run"],
+    });
+  }
+
+  const taskIds = new Set(tasks.map((task) => task.id));
+  for (const task of tasks) {
+    for (const dependency of task.dependsOn) {
+      if (!taskIds.has(dependency)) {
+        throw new TypeError(`orchestrate() task "${task.id}" depends on unknown task "${dependency}"`);
+      }
+      if (dependency === task.id) throw new TypeError(`orchestrate() task "${task.id}" cannot depend on itself`);
+    }
+  }
+  assertAcyclic(tasks);
+
+  let onError: OrchestrationErrorPolicy = "skip-dependents";
+  if (rawOptions !== undefined) {
+    if (!isRecord(rawOptions)) throw new TypeError("orchestrate() options must be an object");
+    for (const key of Object.keys(rawOptions)) {
+      if (key !== "onError") throw new TypeError(`orchestrate() options contains unsupported field "${key}"`);
+    }
+    if (rawOptions.onError !== undefined) {
+      if (
+        rawOptions.onError !== "skip-dependents" &&
+        rawOptions.onError !== "continue" &&
+        rawOptions.onError !== "fail-fast"
+      ) {
+        throw new TypeError('orchestrate() options.onError must be "skip-dependents", "continue", or "fail-fast"');
+      }
+      onError = rawOptions.onError;
+    }
+  }
+  return { tasks, options: { onError } };
+}
+
+function assertAcyclic(tasks: readonly OrchestrationTask[]): void {
+  const indegree = new Map<string, number>();
+  const dependents = new Map<string, string[]>();
+  for (const task of tasks) {
+    indegree.set(task.id, task.dependsOn.length);
+    for (const dependency of task.dependsOn) {
+      const list = dependents.get(dependency) ?? [];
+      list.push(task.id);
+      dependents.set(dependency, list);
+    }
+  }
+  const queue = tasks.filter((task) => indegree.get(task.id) === 0).map((task) => task.id);
+  let visited = 0;
+  for (let cursor = 0; cursor < queue.length; cursor += 1) {
+    const id = queue[cursor];
+    visited += 1;
+    for (const dependent of dependents.get(id) ?? []) {
+      const next = (indegree.get(dependent) ?? 0) - 1;
+      indegree.set(dependent, next);
+      if (next === 0) queue.push(dependent);
+    }
+  }
+  if (visited !== tasks.length) throw new TypeError("orchestrate() task dependencies contain a cycle");
+}
+
+function terminal(status: OrchestrationTaskStatus | undefined): status is OrchestrationTaskTerminalStatus {
+  return status === "completed" || status === "failed" || status === "skipped";
+}
+
+function defaultFormatError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function emit(hooks: OrchestrationHooks, event: OrchestrationTaskEvent): void {
+  try {
+    hooks.onEvent?.(event);
+  } catch {
+    // Observers are not part of execution correctness.
+  }
+}
+
+function snapshotContext(
+  task: OrchestrationTask,
+  attempt: number,
+  values: Record<string, unknown>,
+  statuses: Record<string, OrchestrationTaskStatus>,
+): OrchestrationTaskContext {
+  let detachedResults: Record<string, unknown>;
+  try {
+    detachedResults = structuredClone(values);
+  } catch (error: unknown) {
+    throw new TypeError(
+      `orchestrate() task "${task.id}" results cannot be detached: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  return Object.freeze({
+    id: task.id,
+    attempt,
+    results: Object.freeze(detachedResults),
+    statuses: Object.freeze({ ...statuses }),
+  });
+}
+
+/** Execute normalized tasks in deterministic dependency layers. */
+export async function executeOrchestration(
+  tasks: readonly OrchestrationTask[],
+  options: OrchestrationOptions = { onError: "skip-dependents" },
+  hooks: OrchestrationHooks = {},
+): Promise<OrchestrationResult> {
+  if (tasks.length > MAX_ORCHESTRATION_TASKS) {
+    throw new TypeError(`orchestrate() accepts at most ${MAX_ORCHESTRATION_TASKS} tasks`);
+  }
+  const pending = new Set(tasks.map((task) => task.id));
+  const values: Record<string, unknown> = {};
+  const statuses: Record<string, OrchestrationTaskStatus> = {};
+  const records = new Map<string, MutableTaskResult>();
+  for (const task of tasks) {
+    statuses[task.id] = "pending";
+    // Keep pending tasks out of callback snapshots. The final `results` map is
+    // filled separately so callers still receive one stable key per task.
+    records.set(task.id, { id: task.id, status: "pending", value: null, attempts: 0 });
+  }
+
+  const markSkipped = (task: OrchestrationTask, reason: string): void => {
+    const record = records.get(task.id);
+    if (!record || !pending.has(task.id)) return;
+    pending.delete(task.id);
+    record.status = "skipped";
+    record.value = null;
+    record.error = reason;
+    statuses[task.id] = "skipped";
+    values[task.id] = null;
+    emit(hooks, {
+      type: "task",
+      stage: "skip",
+      taskId: task.id,
+      ...(task.phase ? { phase: task.phase } : {}),
+      attempt: 0,
+      status: "skipped",
+      error: reason,
+    });
+  };
+
+  while (pending.size > 0) {
+    hooks.throwIfAborted?.();
+
+    if (options.onError !== "continue") {
+      let propagatedSkip: boolean;
+      do {
+        propagatedSkip = false;
+        for (const task of tasks) {
+          if (!pending.has(task.id)) continue;
+          const failedDependency = task.dependsOn.find((dependency) => {
+            const status = statuses[dependency];
+            return status === "failed" || status === "skipped";
+          });
+          if (failedDependency !== undefined) {
+            markSkipped(task, `dependency "${failedDependency}" did not complete`);
+            propagatedSkip = true;
+          }
+        }
+      } while (propagatedSkip);
+      if (pending.size === 0) break;
+    }
+
+    const ready = tasks.filter((task) => {
+      if (!pending.has(task.id)) return false;
+      return task.dependsOn.every((dependency) => {
+        const status = statuses[dependency];
+        return options.onError === "continue" ? terminal(status) : status === "completed";
+      });
+    });
+    if (ready.length === 0) {
+      throw new Error("orchestrate() could not make progress; check task dependencies and failure policy");
+    }
+
+    for (const task of ready) {
+      const record = records.get(task.id);
+      if (!record) continue;
+      record.status = "running";
+      statuses[task.id] = "running";
+      emit(hooks, {
+        type: "task",
+        stage: "start",
+        taskId: task.id,
+        ...(task.phase ? { phase: task.phase } : {}),
+        attempt: 1,
+      });
+    }
+
+    const outcomes = await Promise.all(
+      ready.map(async (task): Promise<{ task: OrchestrationTask; fatal?: { error: unknown } }> => {
+        const record = records.get(task.id);
+        if (!record) return { task };
+        for (let attempt = 1; attempt <= task.retries + 1; attempt += 1) {
+          record.attempts = attempt;
+          try {
+            hooks.throwIfAborted?.();
+            const value = await task.run(snapshotContext(task, attempt, values, statuses));
+            hooks.throwIfAborted?.();
+            pending.delete(task.id);
+            record.status = "completed";
+            record.value = value === undefined ? null : value;
+            statuses[task.id] = "completed";
+            values[task.id] = record.value;
+            emit(hooks, {
+              type: "task",
+              stage: "end",
+              taskId: task.id,
+              ...(task.phase ? { phase: task.phase } : {}),
+              attempt,
+              status: "completed",
+            });
+            return { task };
+          } catch (error: unknown) {
+            const fatal = hooks.isFatal?.(error) ?? false;
+            const message = (hooks.formatError ?? defaultFormatError)(error);
+            record.error = message;
+            record.errorValue = error;
+            if (fatal) {
+              pending.delete(task.id);
+              record.status = "failed";
+              record.value = null;
+              statuses[task.id] = "failed";
+              values[task.id] = null;
+              emit(hooks, {
+                type: "task",
+                stage: "end",
+                taskId: task.id,
+                ...(task.phase ? { phase: task.phase } : {}),
+                attempt,
+                status: "failed",
+                error: message,
+              });
+              return { task, fatal: { error } };
+            }
+            if (attempt <= task.retries) {
+              emit(hooks, {
+                type: "task",
+                stage: "retry",
+                taskId: task.id,
+                ...(task.phase ? { phase: task.phase } : {}),
+                attempt,
+                error: message,
+              });
+              continue;
+            }
+            pending.delete(task.id);
+            record.status = "failed";
+            record.value = null;
+            statuses[task.id] = "failed";
+            values[task.id] = null;
+            emit(hooks, {
+              type: "task",
+              stage: "end",
+              taskId: task.id,
+              ...(task.phase ? { phase: task.phase } : {}),
+              attempt,
+              status: "failed",
+              error: message,
+            });
+            return { task };
+          }
+        }
+        return { task };
+      }),
+    );
+
+    const fatal = outcomes.find((outcome) => outcome.fatal !== undefined)?.fatal;
+    if (fatal) throw fatal.error;
+    if (options.onError === "fail-fast") {
+      const failed = ready.find((task) => records.get(task.id)?.status === "failed");
+      if (failed) {
+        const record = records.get(failed.id);
+        throw record?.errorValue ?? new Error(record?.error ?? `orchestrate() task "${failed.id}" failed`);
+      }
+    }
+  }
+
+  const taskResults: Record<string, OrchestrationTaskResult> = {};
+  for (const task of tasks) {
+    const record = records.get(task.id);
+    if (!record || !terminal(record.status)) continue;
+    taskResults[task.id] = {
+      id: task.id,
+      status: record.status,
+      value: record.value,
+      attempts: record.attempts,
+      ...(record.error === undefined ? {} : { error: record.error }),
+    };
+  }
+  const outputResults: Record<string, unknown> = {};
+  for (const task of tasks) outputResults[task.id] = values[task.id] ?? null;
+  return { results: outputResults, tasks: taskResults };
+}
+
+/** Validate and execute a runtime task list in one call. */
+export async function runOrchestration(
+  rawTasks: unknown,
+  rawOptions: unknown,
+  hooks: OrchestrationHooks = {},
+): Promise<OrchestrationResult> {
+  const normalized = normalizeOrchestration(rawTasks, rawOptions);
+  return executeOrchestration(normalized.tasks, normalized.options, hooks);
+}

package/src/rpc-client.ts

@@ -1,15 +1,14 @@
 import { randomUUID } from "node:crypto";
 import type {
+  ManagedRoutingPolicy,
   ManagedSpawnResponse as ProtocolManagedSpawnResponse,
   ManagedTerminalSnapshot as ProtocolManagedTerminalSnapshot,
-  WorkflowTier,
 } from "@signalridge/pi-subagents-protocol";
 import {
   PROTOCOL_VERSION,
   parseManagedSpawnResponse,
   parseProtocolPing,
   requiredCapabilitiesMatch,
-  workflowTierCapabilityMatch,
 } from "@signalridge/pi-subagents-protocol";
 import type { WorkflowOwner } from "./journal.js";
 
@@ -18,11 +17,8 @@ export interface DispatchTask {
   subagent_type: string;
   prompt: string;
   description: string;
-  tier?: WorkflowTier;
-  /** Exact provider/model reference; resolution remains inside pi-subagents. */
-  model?: string;
-  /** Optional thinking suffix/override resolved by pi-subagents. */
-  thinking?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | "off";
+  /** Agent-tier key, from the host's own catalogue. The only model policy here. */
+  tier?: string;
   /** Per-call worktree request owned by pi-subagents. */
   isolation?: "worktree";
   /** Forwarded toolset hint (e.g. "web-research") for pi-subagents to augment tools. */
@@ -105,9 +101,11 @@ function callRpc<T>(
 
 export const REQUIRED_SUBAGENTS_PROTOCOL = PROTOCOL_VERSION;
 export const PROTOCOL_DIAGNOSTIC =
-  "@signalridge/pi-workflows requires @signalridge/pi-subagents protocol v3 with managedSpawn, lifecycleOwner, ownedStop, ownedQuiescence, workflowTiers, and managedPolicy capabilities. " +
+  `@signalridge/pi-workflows requires @signalridge/pi-subagents protocol v${PROTOCOL_VERSION} with managedSpawn, lifecycleOwner, ownedStop, childContext, ownedQuiescence, agentTiers, and managedPolicy, plus its Agent-tier routing policy. ` +
   "Install @signalridge/pi-subagents and @signalridge/pi-workflows exactly once; Pi loads both from their configured pi.extensions manifests.";
 
+const CAPABILITY_DIAGNOSTIC = `subagents protocol v${PROTOCOL_VERSION} is required, with every capability and an Agent-tier routing policy`;
+
 export const CHILD_CONTEXT_QUERY_TIMEOUT_MS = 250;
 
 /**
@@ -169,7 +167,17 @@ export function queryChildSessionContextImmediate(events: WorkflowEventBus): boo
 }
 
 /** Verify the separately configured pi-subagents package before workflow execution. */
-export async function checkManagedSpawnProtocol(events: WorkflowEventBus, signal?: AbortSignal): Promise<void> {
+export interface ManagedProtocolCheck {
+  /** The host's Agent-tier catalogue, as of this check. */
+  routingPolicy: ManagedRoutingPolicy;
+  /** Whole-catalogue identity; used only where a per-tier identity cannot be. */
+  routingPolicyFingerprint: string;
+}
+
+export async function checkManagedSpawnProtocol(
+  events: WorkflowEventBus,
+  signal?: AbortSignal,
+): Promise<ManagedProtocolCheck> {
   const id = requestId();
   const reply = await new Promise<unknown>((resolve, reject) => {
     const replyChannel = `subagents:rpc:ping:reply:${id}`;
@@ -228,57 +236,40 @@ export async function checkManagedSpawnProtocol(events: WorkflowEventBus, signal
   let ping: ReturnType<typeof parseProtocolPing>;
   try {
     ping = parseProtocolPing(reply);
-  } catch {
-    if (
-      !isRecord(reply) ||
-      typeof reply.version !== "number" ||
-      !isRecord(reply.capabilities) ||
-      reply.version < REQUIRED_SUBAGENTS_PROTOCOL ||
-      reply.capabilities.managedSpawn !== true ||
-      reply.capabilities.lifecycleOwner !== true ||
-      reply.capabilities.ownedStop !== true ||
-      reply.capabilities.ownedQuiescence !== true ||
-      reply.capabilities.managedPolicy !== true
-    ) {
-      throw new Error(
-        `subagents protocol v${REQUIRED_SUBAGENTS_PROTOCOL} with managed spawning, owned stop, owned quiescence, and managed policy capabilities is required`,
-      );
+  } catch (error: unknown) {
+    // Anything shaped like a ping is a peer that is present but not v4-complete,
+    // and the actionable answer is the same in every such case: install a
+    // matching pair. A reply that is not a ping at all gets its own message,
+    // because "upgrade the peer" would be the wrong thing to go do.
+    if (!isRecord(reply) || typeof reply.version !== "number") {
+      throw new Error("subagents protocol ping did not return a valid version/capability envelope");
     }
-    throw new Error("subagents protocol ping did not return a valid version/capability envelope");
+    throw new Error(`${CAPABILITY_DIAGNOSTIC} (${error instanceof Error ? error.message : String(error)})`);
   }
+  // Every v4 capability is required, so one check covers them all. The parser
+  // has already rejected a ping without a well-formed routing policy.
   if (ping.version < REQUIRED_SUBAGENTS_PROTOCOL || !requiredCapabilitiesMatch(ping.capabilities)) {
-    throw new Error(
-      `subagents protocol v${REQUIRED_SUBAGENTS_PROTOCOL} with managed spawning, owned stop, and owned quiescence capability is required`,
-    );
-  }
-  if (!workflowTierCapabilityMatch(ping.capabilities)) {
-    throw new Error("subagents workflow tier capability is required before tiered managed spawning");
-  }
-  if (ping.capabilities.managedPolicy !== true) {
-    throw new Error("subagents managed policy capability is required before policy-bearing managed spawning");
+    throw new Error(CAPABILITY_DIAGNOSTIC);
   }
+  return {
+    routingPolicy: ping.routingPolicy.policy,
+    routingPolicyFingerprint: ping.routingPolicy.fingerprint,
+  };
 }
 
 export type ManagedTerminalSnapshot = ProtocolManagedTerminalSnapshot;
 export type ManagedSpawnResponse = ProtocolManagedSpawnResponse;
 
 export interface ManagedSpawnClient {
-  /** String remains accepted for deterministic legacy fixtures; protocol v3 returns ManagedSpawnResponse. */
-  /**
-   * The fourth argument is the current attempt for protocol-v3 clients. The
-   * optional fifth argument is retained only for old in-process test/fixture
-   * clients that used the former context, attemptId shape; it is never a
-   * runtime context and is not sent over RPC.
-   */
+  /** Managed spawn returns a structured response. */
   spawn(
     task: DispatchTask,
     runId: string,
     nodeId: string,
     attemptId?: string,
-    legacyAttemptId?: string,
     signal?: AbortSignal,
   ): Promise<ManagedSpawnResponse | string>;
-  /** Unscoped v2 stop, retained for existing callers. */
+  /** Unscoped stop for non-managed callers. */
   stop(agentId: string): Promise<void>;
   /** Owner-scoped v3 stop used by workflow lifecycle operations. */
   stopOwned?(agentId: string, owner: WorkflowOwner): Promise<void>;
@@ -290,8 +281,8 @@ export interface ManagedSpawnClient {
     timeoutMs?: number,
     owners?: WorkflowOwner[],
   ): Promise<{ settled: boolean; pending: string[] }>;
-  /** Optional startup capability check; workflow execution remains event-bus-only. */
-  checkProtocol?: () => Promise<void>;
+  /** Fresh capability and routing-policy check; workflow execution remains event-bus-only. */
+  checkProtocol?: () => Promise<ManagedProtocolCheck>;
 }
 
 /** Event-bus-only client for the additive pi-subagents managed protocol. */
@@ -320,7 +311,7 @@ export function createManagedSpawnClient(
      * error for the same key with a different fingerprint. Same key + same
      * fingerprint still reuses the persisted tombstone (per-call cache).
      */
-    async spawn(task, runId, nodeId, attemptId, _legacyAttemptId, signal) {
+    async spawn(task, runId, nodeId, attemptId, signal) {
       const effectiveAttemptId = attemptId ?? `attempt-1`;
       const spawnKey = `${runId}/${nodeId}/${effectiveAttemptId}`;
       const requestSignal =
@@ -339,8 +330,6 @@ export function createManagedSpawnClient(
             ...(task.toolset === undefined ? {} : { toolset: task.toolset }),
             ...(task.thread === undefined ? {} : { thread: task.thread }),
             ...(task.excludeTools === undefined ? {} : { excludeTools: task.excludeTools }),
-            ...(task.model === undefined ? {} : { model: task.model }),
-            ...(task.thinking === undefined ? {} : { thinking: task.thinking }),
             ...(task.isolation === undefined ? {} : { isolation: task.isolation }),
             owner: { extension: "pi-workflows", runId, nodeId, attemptId: effectiveAttemptId },
           },