@cordfuse/crosstalkd 7.0.0-alpha.1

package/src/transport.ts

@@ -0,0 +1,236 @@
+// Git transport layer. The dispatcher's commits contain ONLY data/ —
+// machine-local state lives in the state dir (state.ts), so there is
+// nothing to exclude, untrack, or heal. Push rejection means another
+// machine won the race: pull --rebase and retry at the call site.
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
+import { join } from 'path';
+import { spawnSync } from 'child_process';
+import { parseFrontmatter } from './frontmatter.js';
+import { logError } from './state.js';
+
+export interface ChannelMessage {
+  relPath: string;
+  fullPath: string;
+  data: Record<string, unknown>;
+  body: string;
+}
+
+export interface GitResult {
+  ok: boolean;
+  error?: string;
+}
+
+export interface GitPushResult {
+  ok: boolean;
+  committed: boolean;
+  pushed: boolean;
+  error?: string;
+}
+
+function captureGit(cwd: string, args: string[]): { status: number; stdout: string; stderr: string } {
+  const r = spawnSync('git', args, { cwd, encoding: 'utf-8' });
+  return { status: r.status ?? 1, stdout: r.stdout ?? '', stderr: r.stderr ?? '' };
+}
+
+// Detect and abort an interrupted rebase/merge left by a killed process.
+// Returns true if recovery was performed.
+export function recoverInterruptedGit(transportRoot: string): boolean {
+  const halfStates: { dir: string; abortArgs: string[] }[] = [
+    { dir: '.git/rebase-merge', abortArgs: ['rebase', '--abort'] },
+    { dir: '.git/rebase-apply', abortArgs: ['rebase', '--abort'] },
+    { dir: '.git/MERGE_HEAD', abortArgs: ['merge', '--abort'] },
+    { dir: '.git/CHERRY_PICK_HEAD', abortArgs: ['cherry-pick', '--abort'] },
+  ];
+  for (const { dir, abortArgs } of halfStates) {
+    if (existsSync(join(transportRoot, dir))) {
+      const r = captureGit(transportRoot, abortArgs);
+      logError(
+        transportRoot,
+        `recovered from interrupted git state at ${dir} via 'git ${abortArgs.join(' ')}' (exit=${r.status})`,
+      );
+      return true;
+    }
+  }
+  return false;
+}
+
+// The commit cursors anchor to. Prefer the origin tip: origin history is
+// append-only, so a cursor pointing there can never be orphaned by a local
+// `pull --rebase` rewriting unpushed commits. HEAD is the fallback for
+// transports without a remote.
+export function cursorBaseline(transportRoot: string): string | null {
+  for (const ref of ['origin/HEAD', 'origin/main', 'HEAD']) {
+    const r = captureGit(transportRoot, ['rev-parse', ref]);
+    if (r.status === 0) return r.stdout.trim();
+  }
+  return null;
+}
+
+// Repo-relative paths of message files added between `sinceCommit` and
+// HEAD. Returns null when the commit is unknown to this clone (state dir
+// copied across transports, history rewritten) — caller falls back to a
+// full channel scan.
+export function newFilesSince(transportRoot: string, sinceCommit: string): string[] | null {
+  const r = captureGit(transportRoot, [
+    'diff', '--name-only', '--diff-filter=A', `${sinceCommit}..HEAD`, '--', 'data/channels/',
+  ]);
+  if (r.status !== 0) return null;
+  return r.stdout.split('\n').filter(Boolean);
+}
+
+export function gitPull(transportRoot: string): GitResult {
+  recoverInterruptedGit(transportRoot);
+  const fetch = captureGit(transportRoot, ['fetch', 'origin', '--quiet']);
+  if (fetch.status !== 0) {
+    // No origin remote configured → not an error. Single-machine and
+    // local-only transports are valid; the dispatcher just operates on
+    // local commits.
+    const stderr = fetch.stderr.trim();
+    if (stderr.includes("does not appear to be a git repository") ||
+        stderr.includes("Could not read from remote") ||
+        stderr.includes("origin") && stderr.includes("does not appear")) {
+      return { ok: true };
+    }
+    return { ok: false, error: (fetch.stderr || fetch.stdout).trim().slice(0, 500) };
+  }
+  const rebase = captureGit(transportRoot, ['rebase', 'origin/main']);
+  if (rebase.status !== 0) {
+    // No origin/main (single-machine, no remote) → not an error.
+    if (rebase.stderr.includes('unknown revision') || rebase.stderr.includes('not a valid object name')) {
+      return { ok: true };
+    }
+    return { ok: false, error: (rebase.stderr || rebase.stdout).trim().slice(0, 500) };
+  }
+  return { ok: true };
+}
+
+// Stage data/ only, commit, push. On push rejection, one pull --rebase +
+// re-push — collision-free filenames make the rebase trivially clean.
+// In single-machine transports with no remote, the push step is a no-op
+// (gracefully — git push fails fast on "No configured push destination",
+// which we treat as success since the commit is already local).
+export function gitCommitAndPush(transportRoot: string, message: string): GitPushResult {
+  const status = captureGit(transportRoot, ['status', '--porcelain', '--', 'data/']);
+  if (status.status !== 0) {
+    return { ok: false, committed: false, pushed: false, error: status.stderr.trim().slice(0, 500) };
+  }
+  if (!status.stdout.trim()) {
+    return { ok: true, committed: false, pushed: false };
+  }
+
+  const add = captureGit(transportRoot, ['add', '--', 'data/']);
+  if (add.status !== 0) {
+    return { ok: false, committed: false, pushed: false, error: add.stderr.trim().slice(0, 500) };
+  }
+
+  const commit = captureGit(transportRoot, ['commit', '-m', message, '--', 'data/']);
+  if (commit.status !== 0) {
+    const noop = commit.stdout.includes('nothing to commit') ||
+                 commit.stderr.includes('nothing to commit');
+    if (noop) return { ok: true, committed: false, pushed: false };
+    return { ok: false, committed: false, pushed: false, error: commit.stderr.trim().slice(0, 500) };
+  }
+
+  // Push rejection is NORMAL under concurrent writers — git is the
+  // arbiter and collision-free filenames make every rebase clean. Retry
+  // with jitter; many writers racing one origin converge within a few
+  // rounds. v6 used turnq as an advisory lock to reduce churn; v7 dropped
+  // it — rebase-retry is the correctness mechanism, turnq was overhead.
+  let push = captureGit(transportRoot, ['push', '--quiet']);
+  if (push.status !== 0) {
+    // No remote configured → push fails with "No configured push destination".
+    // Treat as success: commits stay local, which is the intended state
+    // for single-machine transports.
+    if (push.stderr.includes('No configured push destination') ||
+        push.stderr.includes("does not appear to be a git repository")) {
+      return { ok: true, committed: true, pushed: false };
+    }
+  }
+  for (let attempt = 0; push.status !== 0 && attempt < 5; attempt++) {
+    spawnSync('sleep', [(0.05 + Math.random() * 0.3 * (attempt + 1)).toFixed(2)]);
+    const pull = gitPull(transportRoot);
+    if (!pull.ok) continue;
+    push = captureGit(transportRoot, ['push', '--quiet']);
+  }
+  if (push.status !== 0) {
+    return {
+      ok: false,
+      committed: true,
+      pushed: false,
+      error: (push.stderr || push.stdout).trim().slice(0, 500),
+    };
+  }
+  return { ok: true, committed: true, pushed: true };
+}
+
+export function discoverChannels(transportRoot: string): string[] {
+  const channelsDir = join(transportRoot, 'data', 'channels');
+  if (!existsSync(channelsDir)) return [];
+  let entries: string[];
+  try {
+    entries = readdirSync(channelsDir);
+  } catch (err) {
+    logError(transportRoot, `discoverChannels readdir failed on ${channelsDir}: ${(err as Error).message}`);
+    return [];
+  }
+  return entries.filter((name) => {
+    try {
+      return statSync(join(channelsDir, name)).isDirectory();
+    } catch {
+      return false;
+    }
+  });
+}
+
+// v7 frontmatter contract (see transport/CROSSTALK.md §Messages):
+//   required: from (string), to (string), timestamp (string)
+//   optional: re, as, type ('workflow' only), failed, error, child_channel
+// v6 required `type: text` on every message; v7 omits `type:` on regular
+// messages. Readers must ignore UNKNOWN fields, but known fields with
+// invalid values are protocol violations and rejected at parse time.
+// This catches LLM models that revert to v6 muscle memory (writing
+// `type: text` in hand-crafted frontmatter) — a real failure mode
+// surfaced by the S10 fan-out workflow test.
+function isValidMessageFrontmatter(data: Record<string, unknown>): boolean {
+  if (typeof data['from'] !== 'string') return false;
+  if (typeof data['to'] !== 'string' && !Array.isArray(data['to'])) return false;
+  if (typeof data['timestamp'] !== 'string') return false;
+  // `type:` is optional; only 'workflow' is valid in v7. Reject v6's
+  // `type: text` and any other invalid value.
+  if (data['type'] !== undefined && data['type'] !== 'workflow') return false;
+  return true;
+}
+
+export function listChannelMessages(transportRoot: string, channelUuid: string): ChannelMessage[] {
+  const channelDir = join(transportRoot, 'data', 'channels', channelUuid);
+  if (!existsSync(channelDir)) return [];
+  const results: ChannelMessage[] = [];
+  const walk = (dir: string, prefix: string): void => {
+    for (const entry of readdirSync(dir)) {
+      const full = join(dir, entry);
+      const rel = prefix ? `${prefix}/${entry}` : entry;
+      let stat;
+      try { stat = statSync(full); } catch { continue; }
+      if (stat.isDirectory()) {
+        walk(full, rel);
+      } else if (entry.endsWith('.md') && entry !== 'CHANNEL.md') {
+        const raw = readFileSync(full, 'utf-8');
+        let parsed;
+        try {
+          parsed = parseFrontmatter(raw);
+        } catch (err) {
+          logError(transportRoot, `frontmatter parse failed in ${channelUuid}/${rel}: ${(err as Error).message}`);
+          continue;
+        }
+        if (!isValidMessageFrontmatter(parsed.data)) {
+          logError(transportRoot, `invalid message frontmatter in ${channelUuid}/${rel}: missing required field(s) (from, to, timestamp)`);
+          continue;
+        }
+        results.push({ relPath: rel, fullPath: full, data: parsed.data, body: parsed.body });
+      }
+    }
+  };
+  walk(channelDir, '');
+  return results.sort((a, b) => a.relPath.localeCompare(b.relPath));
+}

package/src/workflow.ts

@@ -0,0 +1,458 @@
+// workflow.ts — runtime workflow executor.
+//
+// A workflow marker is a `type: workflow` message addressed to the reserved
+// recipient `workflow`. The runtime processes it directly: no model wakes
+// for it via the activation loop. The persona-orchestrator pattern from
+// pre-alpha v7 is gone — workflows are now compile-pass + deterministic
+// runtime execution, so every supported agent CLI works regardless of
+// model's instruction-following discipline.
+//
+// One phase advances per dispatcher tick. State is derived from files
+// each tick — no in-memory workflow registry, no recovery logic needed
+// across dispatcher restarts.
+//
+//   1. compile     — invoke the first claimed model with COMPILE_PROMPT
+//                    and the workflow body. Parse JSON plan. Save to
+//                    data/channels/<child>/PLAN.json, or fail the workflow.
+//   2. fanout      — write `plan.fanout.count` sub-primitives into the
+//                    child channel addressed to `plan.fanout.to`.
+//   3. synthesize  — once all fanout replies are in, write one synthesis
+//                    sub-primitive into the child channel with body =
+//                    plan.synthesize.body + the concatenated reply bodies.
+//   4. route       — once the synthesis reply lands, write a final reply
+//                    in the PARENT channel addressed to the workflow
+//                    marker's `from:`, re:-linked to the marker. Drop a
+//                    COMPLETE side file so future ticks skip this marker.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { now, messageFilename } from './filenames.js';
+import { serializeFrontmatter } from './frontmatter.js';
+import { invokeModelCli } from './invoke.js';
+import { listChannelMessages, type ChannelMessage } from './transport.js';
+import { logError } from './state.js';
+import { dispatchersForModel } from './dispatchers.js';
+import type { ModelEntry } from './models.js';
+
+export const WORKFLOW_RECIPIENT = 'workflow';
+
+export interface WorkflowPlan {
+  fanout: { to: string; count: number; body: string };
+  synthesize: { to: string; body: string };
+}
+
+const COMPILE_PROMPT = [
+  'Compile the workflow markdown document below into a single JSON object',
+  'with this exact shape:',
+  '',
+  '{"fanout":{"to":"<model-name>","count":<integer 1-10>,"body":"<task>"},',
+  ' "synthesize":{"to":"<model-name>","body":"<instruction>"}}',
+  '',
+  'Field meaning:',
+  '  fanout.to        the model name (from data/models.yaml) to fan out to',
+  '  fanout.count     how many parallel workers, integer 1-10',
+  '  fanout.body      the task each fanout worker performs',
+  '  synthesize.to    the model name that picks/merges the fanout replies',
+  '  synthesize.body  the instruction the synthesizer follows',
+  '',
+  'Output ONLY the JSON object. No prose, no markdown fences, no explanation.',
+  'The workflow document follows:',
+  '',
+].join('\n');
+
+function channelDir(transportRoot: string, channelUuid: string): string {
+  return join(transportRoot, 'data', 'channels', channelUuid);
+}
+
+function planPath(transportRoot: string, childUuid: string): string {
+  return join(channelDir(transportRoot, childUuid), 'PLAN.json');
+}
+
+function completePath(transportRoot: string, childUuid: string): string {
+  return join(channelDir(transportRoot, childUuid), 'COMPLETE');
+}
+
+export function validatePlan(p: unknown): p is WorkflowPlan {
+  if (typeof p !== 'object' || p == null) return false;
+  const x = p as Record<string, unknown>;
+  const f = x['fanout'] as Record<string, unknown> | undefined;
+  const s = x['synthesize'] as Record<string, unknown> | undefined;
+  if (!f || !s) return false;
+  if (typeof f['to'] !== 'string' || f['to'].length === 0) return false;
+  const c = f['count'];
+  if (typeof c !== 'number' || !Number.isInteger(c) || c < 1 || c > 10) return false;
+  if (typeof f['body'] !== 'string') return false;
+  if (typeof s['to'] !== 'string' || s['to'].length === 0) return false;
+  if (typeof s['body'] !== 'string') return false;
+  return true;
+}
+
+function loadPlan(transportRoot: string, childUuid: string): WorkflowPlan | null {
+  const p = planPath(transportRoot, childUuid);
+  if (!existsSync(p)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(p, 'utf-8')) as unknown;
+    return validatePlan(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+// Models occasionally wrap JSON in markdown fences or add a sentence before
+// the object despite the prompt's "JSON only" instruction. Extract the first
+// balanced {...} block as a fallback.
+export function extractPlanFromOutput(stdout: string): WorkflowPlan | null {
+  const trimmed = stdout.trim();
+  const tryParse = (s: string): WorkflowPlan | null => {
+    try {
+      const parsed = JSON.parse(s) as unknown;
+      return validatePlan(parsed) ? parsed : null;
+    } catch {
+      return null;
+    }
+  };
+  const whole = tryParse(trimmed);
+  if (whole) return whole;
+  const start = trimmed.indexOf('{');
+  const end = trimmed.lastIndexOf('}');
+  if (start === -1 || end === -1 || end <= start) return null;
+  return tryParse(trimmed.slice(start, end + 1));
+}
+
+export interface WorkflowMarker {
+  parentChannelUuid: string;
+  childChannelUuid: string;
+  markerRelPath: string;
+  markerFrom: string;
+  body: string;
+  // When set, only the dispatcher whose alias matches progresses this
+  // workflow's phases. Markers without dispatch_host fall back to
+  // race-based progression (acceptable for single-host transports).
+  dispatchHost?: string;
+}
+
+export function findOpenWorkflows(
+  transportRoot: string,
+  channels: string[],
+  alias?: string,
+): WorkflowMarker[] {
+  const out: WorkflowMarker[] = [];
+  for (const parentUuid of channels) {
+    const messages = listChannelMessages(transportRoot, parentUuid);
+    for (const m of messages) {
+      if (m.data['type'] !== 'workflow') continue;
+      const childUuid = m.data['child_channel'];
+      if (typeof childUuid !== 'string') continue;
+      if (existsSync(completePath(transportRoot, childUuid))) continue;
+      const dispatchHost = typeof m.data['dispatch_host'] === 'string'
+        ? (m.data['dispatch_host'] as string)
+        : undefined;
+      // Ownership filter: when the marker pins a dispatch_host, only that
+      // dispatcher progresses it. Other dispatchers see the marker (it's a
+      // normal message) but skip it here, leaving the workflow's runtime
+      // work to its owner.
+      if (dispatchHost && alias && dispatchHost !== alias) continue;
+      const from = typeof m.data['from'] === 'string' ? (m.data['from'] as string) : 'unknown';
+      out.push({
+        parentChannelUuid: parentUuid,
+        childChannelUuid: childUuid,
+        markerRelPath: m.relPath,
+        markerFrom: from,
+        body: m.body,
+        dispatchHost,
+      });
+    }
+  }
+  return out;
+}
+
+function senderOf(msg: ChannelMessage): string {
+  return typeof msg.data['from'] === 'string' ? (msg.data['from'] as string) : 'unknown';
+}
+
+function workflowDispatches(
+  transportRoot: string,
+  childUuid: string,
+  alias: string,
+  phase: 'fanout' | 'synthesize',
+): ChannelMessage[] {
+  const fromName = `workflow@${alias}`;
+  return listChannelMessages(transportRoot, childUuid).filter(
+    (m) => senderOf(m) === fromName && m.data['workflow_phase'] === phase,
+  );
+}
+
+function repliesTo(
+  transportRoot: string,
+  childUuid: string,
+  targetRelPaths: string[],
+): ChannelMessage[] {
+  const targetSet = new Set(targetRelPaths);
+  return listChannelMessages(transportRoot, childUuid).filter((m) => {
+    const re = m.data['re'];
+    if (typeof re === 'string') return targetSet.has(re);
+    if (Array.isArray(re)) return re.some((r) => typeof r === 'string' && targetSet.has(r));
+    return false;
+  });
+}
+
+interface WriteOpts {
+  transportRoot: string;
+  channelUuid: string;
+  from: string;
+  to: string;
+  body: string;
+  workflowPhase?: 'fanout' | 'synthesize';
+  re?: string;
+  failed?: { error: string };
+}
+
+function writeRuntimeMessage(opts: WriteOpts): string {
+  const ts = now();
+  const dir = join(channelDir(opts.transportRoot, opts.channelUuid), ts.pathDate);
+  mkdirSync(dir, { recursive: true });
+  const fm: Record<string, unknown> = {
+    from: opts.from,
+    to: opts.to,
+    timestamp: ts.iso,
+  };
+  if (opts.re) fm['re'] = opts.re;
+  if (opts.workflowPhase) fm['workflow_phase'] = opts.workflowPhase;
+  if (opts.failed) {
+    fm['failed'] = true;
+    fm['error'] = opts.failed.error.slice(0, 2000);
+  }
+  const filename = messageFilename(ts);
+  writeFileSync(join(dir, filename), serializeFrontmatter(fm, opts.body));
+  return join(ts.pathDate, filename);
+}
+
+function markComplete(transportRoot: string, childUuid: string): void {
+  writeFileSync(completePath(transportRoot, childUuid), new Date().toISOString() + '\n');
+}
+
+function failWorkflow(
+  transportRoot: string,
+  marker: WorkflowMarker,
+  alias: string,
+  error: string,
+): void {
+  writeRuntimeMessage({
+    transportRoot,
+    channelUuid: marker.parentChannelUuid,
+    from: `workflow@${alias}`,
+    to: marker.markerFrom,
+    body: error,
+    re: marker.markerRelPath,
+    failed: { error },
+  });
+  markComplete(transportRoot, marker.childChannelUuid);
+}
+
+export interface WorkflowTickContext {
+  transportRoot: string;
+  alias: string;
+  claimed: Map<string, ModelEntry>;
+  log: (event: string, fields?: Record<string, unknown>) => void;
+}
+
+export async function workflowTick(
+  ctx: WorkflowTickContext,
+  channels: string[],
+): Promise<boolean> {
+  const open = findOpenWorkflows(ctx.transportRoot, channels, ctx.alias);
+  if (open.length === 0) return false;
+  let progressed = false;
+  for (const marker of open) {
+    try {
+      const did = await advanceOne(ctx, marker);
+      if (did) progressed = true;
+    } catch (err) {
+      const msg = (err as Error).message;
+      logError(ctx.transportRoot, `workflow ${marker.markerRelPath} crashed: ${msg}`);
+      ctx.log('workflow_crash', { marker: marker.markerRelPath, error: msg.slice(0, 200) });
+      failWorkflow(ctx.transportRoot, marker, ctx.alias, `runtime error: ${msg.slice(0, 500)}`);
+      progressed = true;
+    }
+  }
+  return progressed;
+}
+
+async function advanceOne(ctx: WorkflowTickContext, marker: WorkflowMarker): Promise<boolean> {
+  const { transportRoot, alias, claimed } = ctx;
+  const fromIdentity = `workflow@${alias}`;
+
+  // Phase 1: compile.
+  let plan = loadPlan(transportRoot, marker.childChannelUuid);
+  if (!plan) {
+    const firstClaimed = claimed.values().next().value as ModelEntry | undefined;
+    if (!firstClaimed) {
+      failWorkflow(transportRoot, marker, alias, 'no claimed model available to compile the workflow');
+      ctx.log('workflow_compile_no_model', { marker: marker.markerRelPath });
+      return true;
+    }
+    ctx.log('workflow_compile_start', {
+      marker: marker.markerRelPath,
+      compile_model: firstClaimed.name,
+    });
+    const result = await invokeModelCli(firstClaimed, COMPILE_PROMPT, marker.body, {});
+    if (result.status !== 0) {
+      failWorkflow(transportRoot, marker, alias,
+        `compile model exit=${result.status}: ${result.stderr.slice(0, 500)}`);
+      ctx.log('workflow_compile_failed', { marker: marker.markerRelPath, exit: result.status });
+      return true;
+    }
+    const parsed = extractPlanFromOutput(result.stdout);
+    if (!parsed) {
+      failWorkflow(transportRoot, marker, alias,
+        `could not parse workflow prose. Compiler returned:\n${result.stdout.slice(0, 800)}`);
+      ctx.log('workflow_compile_invalid', { marker: marker.markerRelPath });
+      return true;
+    }
+    // Fail-fast if the compiled plan addresses a model this dispatcher
+    // doesn't claim. The alternative is silently hanging on un-deliverable
+    // sub-primitives.
+    if (!claimed.has(parsed.fanout.to)) {
+      failWorkflow(transportRoot, marker, alias,
+        `compiled plan addresses model '${parsed.fanout.to}' for fanout — not claimed on this dispatcher`);
+      return true;
+    }
+    if (!claimed.has(parsed.synthesize.to)) {
+      failWorkflow(transportRoot, marker, alias,
+        `compiled plan addresses model '${parsed.synthesize.to}' for synthesize — not claimed on this dispatcher`);
+      return true;
+    }
+    writeFileSync(planPath(transportRoot, marker.childChannelUuid), JSON.stringify(parsed, null, 2) + '\n');
+    plan = parsed;
+    ctx.log('workflow_compiled', {
+      marker: marker.markerRelPath,
+      fanout: `${plan.fanout.to}x${plan.fanout.count}`,
+      synthesize: plan.synthesize.to,
+    });
+    return true;
+  }
+
+  // Phase 2: fanout dispatch.
+  //
+  // Distribution: read the dispatcher registry to find every dispatcher
+  // claiming the fanout model. Round-robin the N sub-primitives across
+  // them, scoping each as `to: <model>@<alias>`. Without this, bare
+  // `to: <model>` dispatches get claimed by EVERY dispatcher (at-least-
+  // once activation), turning a fan-out into N× duplicated work for 1×
+  // throughput — defeating the multi-host value prop entirely.
+  //
+  // Fallback: if the registry is empty (single-host case with no
+  // dispatcher publishing, or a transient race between dispatcher start
+  // and workflow dispatch), use the bare recipient. Single-host: only
+  // one dispatcher claims anyway, so bare is safe. Empty registry on
+  // multi-host: degrade to current duplicate-work behavior with a logged
+  // warning rather than failing the workflow.
+  const fanouts = workflowDispatches(transportRoot, marker.childChannelUuid, alias, 'fanout');
+  if (fanouts.length === 0) {
+    const candidates = dispatchersForModel(transportRoot, plan.fanout.to);
+    const distribution = candidates.length === 0 ? null : candidates;
+    if (distribution === null) {
+      ctx.log('workflow_fanout_no_registry_fallback', {
+        marker: marker.markerRelPath,
+        model: plan.fanout.to,
+      });
+    }
+    for (let i = 0; i < plan.fanout.count; i++) {
+      const to = distribution === null
+        ? plan.fanout.to
+        : `${plan.fanout.to}@${distribution[i % distribution.length]}`;
+      writeRuntimeMessage({
+        transportRoot,
+        channelUuid: marker.childChannelUuid,
+        from: fromIdentity,
+        to,
+        body: plan.fanout.body,
+        workflowPhase: 'fanout',
+      });
+    }
+    ctx.log('workflow_fanout_dispatched', {
+      marker: marker.markerRelPath,
+      count: plan.fanout.count,
+      to: plan.fanout.to,
+      dispatchers: distribution ?? 'bare',
+    });
+    return true;
+  }
+
+  // Phase 3: wait for fanout replies. Failed replies count toward the total
+  // so we don't stall on individual worker failures — the synthesizer sees
+  // them as FAILED candidates and decides.
+  const fanoutRelPaths = fanouts.map((m) => m.relPath);
+  const fanoutReplies = repliesTo(transportRoot, marker.childChannelUuid, fanoutRelPaths);
+  if (fanoutReplies.length < plan.fanout.count) {
+    return false;
+  }
+
+  // Phase 4: synthesize dispatch.
+  //
+  // Pin to one specific dispatcher so we don't duplicate the synthesis
+  // (which costs another model call and emits another routed reply).
+  // Pick deterministically — first alias in sorted-claim order — so the
+  // assignment is reproducible. Falls back to bare on empty registry,
+  // accepting the duplication risk (already documented for fanout above).
+  const synthesizes = workflowDispatches(transportRoot, marker.childChannelUuid, alias, 'synthesize');
+  if (synthesizes.length === 0) {
+    const synthCandidates = dispatchersForModel(transportRoot, plan.synthesize.to);
+    const synthTo = synthCandidates.length === 0
+      ? plan.synthesize.to
+      : `${plan.synthesize.to}@${synthCandidates[0]}`;
+    const candidatesText = fanoutReplies
+      .slice()
+      .sort((a, b) => a.relPath.localeCompare(b.relPath))
+      .map((m, i) => {
+        const failed = m.data['failed'] === true ? ' (FAILED)' : '';
+        return `--- candidate ${i + 1}${failed} ---\n${m.body}`;
+      })
+      .join('\n\n');
+    const synthBody = `${plan.synthesize.body}\n\n${candidatesText}`;
+    writeRuntimeMessage({
+      transportRoot,
+      channelUuid: marker.childChannelUuid,
+      from: fromIdentity,
+      to: synthTo,
+      body: synthBody,
+      workflowPhase: 'synthesize',
+    });
+    ctx.log('workflow_synthesize_dispatched', {
+      marker: marker.markerRelPath,
+      to: synthTo,
+      candidates: fanoutReplies.length,
+    });
+    return true;
+  }
+
+  // Phase 5: wait for synthesis reply.
+  const synthRelPaths = synthesizes.map((m) => m.relPath);
+  const synthReplies = repliesTo(transportRoot, marker.childChannelUuid, synthRelPaths);
+  if (synthReplies.length === 0) return false;
+
+  // Phase 6: route final reply back to the operator who launched the workflow.
+  const finalSource = synthReplies
+    .slice()
+    .sort((a, b) => a.relPath.localeCompare(b.relPath))[0]!;
+  const finalFailed = finalSource.data['failed'] === true;
+  writeRuntimeMessage({
+    transportRoot,
+    channelUuid: marker.parentChannelUuid,
+    from: fromIdentity,
+    to: marker.markerFrom,
+    body: finalSource.body,
+    re: marker.markerRelPath,
+    failed: finalFailed
+      ? { error: typeof finalSource.data['error'] === 'string'
+          ? (finalSource.data['error'] as string)
+          : 'synthesize failed' }
+      : undefined,
+  });
+  markComplete(transportRoot, marker.childChannelUuid);
+  ctx.log('workflow_complete', {
+    marker: marker.markerRelPath,
+    final_failed: finalFailed,
+  });
+  return true;
+}