@llm4ts/runner 2.7.2 → 2.9.0

package/src/ExecutorRoster.ts

@@ -0,0 +1,318 @@
+// Loading the executor roster (ADR 0019): the user's file, the repository's
+// override, the per-run choice (`LLM4TS_ROSTER`, `LLM4TS_EXECUTORS`), and the
+// mapping from an executor to the connector config the registry resolves.
+// Harness knowledge lives here, beside the connector presets; the roster
+// itself (`@llm4ts/flow/Roster`) knows only ids, roles and slots.
+import { homedir } from "node:os"
+import { join } from "node:path"
+import * as Clock from "effect/Clock"
+import * as Duration from "effect/Duration"
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import {
+  ApiConnectorConfig,
+  CliConnectorConfig,
+  type ConnectorConfig
+} from "@llm4ts/core/ConnectorConfig"
+import { RosterInvalid, type FlowError } from "@llm4ts/flow/FlowError"
+import type { PlainFileStoreShape } from "@llm4ts/flow/Persistence"
+import {
+  Exclusion,
+  RosterDocument,
+  coderSlotsOf,
+  describeExclusion,
+  hasRole,
+  makeRosterStateStore,
+  mergeRosterDocuments,
+  narrowRoster,
+  parseDuration,
+  rolesOf,
+  rosterViolations,
+  slotsOf,
+  type ExecutorSpec
+} from "@llm4ts/flow/Roster"
+import { apiPresetFor, asReadOnly, coderFor, withEnvironment, withModel } from "./Connectors.ts"
+
+type Environment = Readonly<Record<string, string | undefined>>
+
+const home = (environment: Environment): string => environment.HOME ?? homedir()
+
+/** `${XDG_CONFIG_HOME:-~/.config}/llm4ts/roster.json`. */
+export const userRosterPath = (environment: Environment): string =>
+  join(environment.XDG_CONFIG_HOME ?? join(home(environment), ".config"), "llm4ts", "roster.json")
+
+/** `<repo>/.llm4ts/roster.json`: overrides the user's entries by id. */
+export const repoRosterPath = (workDir: string): string => join(workDir, ".llm4ts", "roster.json")
+
+/** `${XDG_STATE_HOME:-~/.local/state}/llm4ts/roster-state.json`: exclusions that outlive a run. */
+export const rosterStatePath = (environment: Environment): string =>
+  join(
+    environment.XDG_STATE_HOME ?? join(home(environment), ".local", "state"),
+    "llm4ts",
+    "roster-state.json"
+  )
+
+const reference = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g
+
+/** `${VAR}` references resolved from the environment; the names of missing ones. */
+export const substituteEnvironment = (
+  values: Readonly<Record<string, string>>,
+  environment: Environment
+): {
+  readonly values: Readonly<Record<string, string>>
+  readonly missing: ReadonlyArray<string>
+} => {
+  const missing: Array<string> = []
+  const resolved: Record<string, string> = {}
+  for (const [key, value] of Object.entries(values)) {
+    resolved[key] = value.replace(reference, (_match, name: string) => {
+      const found = environment[name]
+      if (found === undefined) {
+        missing.push(name)
+        return ""
+      }
+      return found
+    })
+  }
+  return { values: resolved, missing: [...new Set(missing)] }
+}
+
+/** Whether a harness name is an API provider (reasoning roles only). */
+export const isApiHarness = (harness: string): boolean =>
+  coderFor(harness) === undefined && apiPresetFor(harness) !== undefined
+
+/**
+ * The connector config an executor runs with: its harness preset, model,
+ * flags, endpoint and environment, read-only for a reasoning role.
+ */
+export const executorConfig = (
+  spec: ExecutorSpec,
+  readOnly: boolean,
+  environment: Environment
+): ConnectorConfig | undefined => {
+  const cli = coderFor(spec.harness)
+  if (cli !== undefined) {
+    const modelled = spec.model === undefined ? cli : withModel(cli, spec.model)
+    const flagged =
+      spec.flags === undefined
+        ? modelled
+        : CliConnectorConfig.make({ ...modelled, flags: { ...modelled.flags, ...spec.flags } })
+    const withEnv =
+      spec.env === undefined
+        ? flagged
+        : withEnvironment(flagged, substituteEnvironment(spec.env, environment).values)
+    return readOnly ? asReadOnly(withEnv) : withEnv
+  }
+  const api = apiPresetFor(spec.harness)
+  if (api === undefined) {
+    return undefined
+  }
+  const modelled = spec.model === undefined ? api : withModel(api, spec.model)
+  return spec.baseUrl === undefined
+    ? modelled
+    : ApiConnectorConfig.make({ ...modelled, baseUrl: spec.baseUrl })
+}
+
+/** The flow-level violations plus what needs the harness table and the environment. */
+export const rosterLoadViolations = (
+  document: RosterDocument,
+  environment: Environment
+): ReadonlyArray<string> => {
+  const violations = [...rosterViolations(document)]
+  for (const spec of document.executors) {
+    const where = `executor '${spec.id}'`
+    if (coderFor(spec.harness) === undefined && apiPresetFor(spec.harness) === undefined) {
+      violations.push(`${where} has an unknown harness '${spec.harness}'`)
+    } else if (isApiHarness(spec.harness) && hasRole(spec, "coder")) {
+      violations.push(
+        `${where} is an API provider ('${spec.harness}'): it may reason, but coding needs a CLI harness`
+      )
+    }
+    const missing = substituteEnvironment(spec.env ?? {}, environment).missing
+    if (missing.length > 0) {
+      violations.push(`${where} references unset variable(s) ${missing.join(", ")}`)
+    }
+  }
+  return violations
+}
+
+const parseRoster = (path: string, text: string): Effect.Effect<RosterDocument, RosterInvalid> =>
+  Effect.try({
+    try: (): unknown => JSON.parse(text),
+    catch: (error) =>
+      RosterInvalid.make({
+        path,
+        violations: [`not JSON: ${error instanceof Error ? error.message : String(error)}`]
+      })
+  }).pipe(
+    Effect.flatMap((json) =>
+      Schema.decodeUnknownEffect(RosterDocument)(json).pipe(
+        Effect.mapError((error) => RosterInvalid.make({ path, violations: [error.message] }))
+      )
+    )
+  )
+
+const readRoster = (
+  files: PlainFileStoreShape,
+  path: string
+): Effect.Effect<RosterDocument | undefined, FlowError> =>
+  Effect.flatMap(files.read(path), (text) =>
+    text === undefined ? Effect.succeed(undefined) : parseRoster(path, text)
+  )
+
+export interface RosterSource {
+  readonly files: PlainFileStoreShape
+  readonly environment: Environment
+  readonly workDir: string
+}
+
+/**
+ * The roster in force for a run, or `undefined` for today's one executor per
+ * seat: `LLM4TS_ROSTER=none` ignores rosters, `LLM4TS_ROSTER=<path>` uses that
+ * file alone, otherwise the user's file with the repository's over it.
+ * `LLM4TS_EXECUTORS=a,b` narrows the result to those ids.
+ */
+export const loadRosterDocument = Effect.fn("@llm4ts/runner/ExecutorRoster.load")(function* (
+  source: RosterSource
+): Effect.fn.Return<RosterDocument | undefined, FlowError> {
+  const chosen = source.environment.LLM4TS_ROSTER?.trim()
+  if (chosen === "none") {
+    return undefined
+  }
+  const loaded = yield* chosen !== undefined && chosen.length > 0
+    ? Effect.flatMap(readRoster(source.files, chosen), (document) =>
+        document === undefined
+          ? Effect.fail(RosterInvalid.make({ path: chosen, violations: ["no roster file there"] }))
+          : Effect.succeed({ document, where: chosen })
+      )
+    : Effect.gen(function* () {
+        const user = userRosterPath(source.environment)
+        const repo = repoRosterPath(source.workDir)
+        const userDocument = yield* readRoster(source.files, user)
+        const repoDocument = yield* readRoster(source.files, repo)
+        if (userDocument === undefined && repoDocument === undefined) {
+          return undefined
+        }
+        const where = [
+          userDocument === undefined ? undefined : user,
+          repoDocument === undefined ? undefined : repo
+        ]
+          .filter((path): path is string => path !== undefined)
+          .join(" + ")
+        return { document: mergeRosterDocuments(userDocument, repoDocument), where }
+      })
+  if (loaded === undefined) {
+    return undefined
+  }
+  const { document, where } = loaded
+  const ids = (source.environment.LLM4TS_EXECUTORS ?? "")
+    .split(",")
+    .map((id) => id.trim())
+    .filter((id) => id.length > 0)
+  const unknown = ids.filter((id) => !document.executors.some((spec) => spec.id === id))
+  const narrowed = narrowRoster(document, ids)
+  const violations = [
+    ...rosterLoadViolations(narrowed, source.environment),
+    ...unknown.map((id) => `LLM4TS_EXECUTORS names '${id}', which the roster does not have`),
+    ...(narrowed.executors.length === 0 ? ["no executor left to run with"] : [])
+  ]
+  if (violations.length > 0) {
+    return yield* RosterInvalid.make({ path: where, violations })
+  }
+  return narrowed
+})
+
+/** Whether `url` answers 2xx within five seconds: a roster executor's health check. */
+export const httpProbe = (url: string): Effect.Effect<boolean> =>
+  Effect.tryPromise(() => fetch(url, { signal: AbortSignal.timeout(5_000) })).pipe(
+    Effect.map((response) => response.ok),
+    Effect.catch(() => Effect.succeed(false))
+  )
+
+// ---- `llm4ts roster` -------------------------------------------------------------
+
+export interface RosterReport {
+  readonly document: RosterDocument | undefined
+  readonly exclusions: ReadonlyArray<Exclusion>
+  readonly statePath: string
+}
+
+/** The roster in force here and the exclusions persisted for it. */
+export const rosterReport = Effect.fn("@llm4ts/runner/ExecutorRoster.report")(function* (
+  source: RosterSource
+): Effect.fn.Return<RosterReport, FlowError> {
+  const document = yield* loadRosterDocument(source)
+  const statePath = rosterStatePath(source.environment)
+  const exclusions = yield* makeRosterStateStore(source.files, statePath).load
+  return { document, exclusions, statePath }
+})
+
+const priorityText = (spec: ExecutorSpec): string => {
+  const priority = spec.priority
+  if (priority === undefined) {
+    return "priority 1"
+  }
+  if (typeof priority === "number") {
+    return `priority ${priority}`
+  }
+  return `priority ${Object.entries(priority)
+    .map(([role, value]) => `${role} ${value}`)
+    .join(", ")}`
+}
+
+export const renderRosterReport = (report: RosterReport): string => {
+  if (report.document === undefined) {
+    return [
+      "no roster: every run uses one executor per seat (LLM4TS_CODER and the flow's defaults).",
+      "Write ~/.config/llm4ts/roster.json (or <repo>/.llm4ts/roster.json) to pool executors."
+    ].join("\n")
+  }
+  const lines = [`executors (${report.document.executors.length}):`]
+  for (const spec of report.document.executors) {
+    const exclusion = report.exclusions.find((candidate) => candidate.id === spec.id)
+    const slots = slotsOf(spec)
+    const coders = hasRole(spec, "coder") ? `, ${coderSlotsOf(spec)} for coding` : ""
+    lines.push(
+      `- ${spec.id}: ${spec.harness}${spec.model === undefined ? "" : ` ${spec.model}`} · ${rolesOf(spec).join(", ")} · ${slots} slot(s)${coders} · ${priorityText(spec)}`,
+      `  ${exclusion === undefined ? "in the round" : `out ${describeExclusion(exclusion)}`}`
+    )
+  }
+  lines.push(`state: ${report.statePath}`)
+  return lines.join("\n")
+}
+
+/** Takes an executor out of every run's pick-up round, for a while or until resumed. */
+export const pauseExecutor = Effect.fn("@llm4ts/runner/ExecutorRoster.pause")(function* (
+  source: RosterSource,
+  id: string,
+  duration: string | undefined
+): Effect.fn.Return<Exclusion, FlowError> {
+  const document = yield* loadRosterDocument(source)
+  if (document === undefined || !document.executors.some((spec) => spec.id === id)) {
+    return yield* RosterInvalid.make({ violations: [`no executor '${id}' in the roster`] })
+  }
+  const span = duration === undefined ? undefined : parseDuration(duration)
+  if (duration !== undefined && span === undefined) {
+    return yield* RosterInvalid.make({ violations: [`cannot read the duration '${duration}'`] })
+  }
+  const now = yield* Clock.currentTimeMillis
+  const exclusion = Exclusion.make({
+    id,
+    kind: "manual",
+    reason: "paused by the operator",
+    ...(span === undefined ? {} : { until: now + Duration.toMillis(span) })
+  })
+  yield* makeRosterStateStore(source.files, rosterStatePath(source.environment)).save(
+    [id],
+    [exclusion]
+  )
+  return exclusion
+})
+
+/** Puts an executor back in the round, whatever took it out. */
+export const resumeExecutor = Effect.fn("@llm4ts/runner/ExecutorRoster.resume")(function* (
+  source: RosterSource,
+  id: string
+): Effect.fn.Return<void, FlowError> {
+  yield* makeRosterStateStore(source.files, rosterStatePath(source.environment)).save([id], [])
+})

package/src/FlowRunner.ts

@@ -13,6 +13,7 @@ import { makeTypeSafeJudgment } from "@llm4ts/core/judgment/TypeSafeJudgment"
 import * as Redacted from "effect/Redacted"
 import type { LlmServiceShape } from "@llm4ts/core/LlmService"
 import type { ConnectorCapabilities, TokenUsage } from "@llm4ts/core/Models"
+import { ConnectorCapabilities as ConnectorCapabilitiesClass } from "@llm4ts/core/Models"
 import type { ProcessExecutorShape } from "@llm4ts/core/ProcessExecutor"
 import type { TemporaryFilesShape } from "@llm4ts/core/TemporaryFiles"
 import type { GeminiCliExecutorShape } from "@llm4ts/core/providers/GeminiCliProvider"
@@ -35,7 +36,12 @@ import {
   type CostBudget
 } from "@llm4ts/flow/CostLedger"
 import { estimatedUsageOptionsFromEnv, makeEstimatedUsageMeter } from "@llm4ts/flow/EstimatedUsage"
-import { FlowLlmError, describeFlowError, type FlowError } from "@llm4ts/flow/FlowError"
+import {
+  FlowLlmError,
+  RosterInvalid,
+  describeFlowError,
+  type FlowError
+} from "@llm4ts/flow/FlowError"
 import {
   defaultDrainTimeout,
   FlowEvents,
@@ -45,13 +51,35 @@ import {
   makeFlowEventHub,
   type FlowEventHub
 } from "@llm4ts/flow/FlowEvents"
-import { FlowContext, type FlowContextShape } from "@llm4ts/flow/FlowContext"
+import { FlowContext, type ContextOptions, type FlowContextShape } from "@llm4ts/flow/FlowContext"
 import { makeFlowRecorder } from "@llm4ts/flow/FlowRecorder"
 import { makeJudgmentLog, type JudgmentLogShape } from "@llm4ts/flow/JudgmentLog"
 import { makeGitHubTool } from "@llm4ts/flow/GitHubTool"
 import { makeGitTool } from "@llm4ts/flow/GitTool"
 import type { PlainFileStoreShape } from "@llm4ts/flow/Persistence"
 import { makeTransientRetry } from "@llm4ts/flow/TransientRetry"
+import {
+  Exclusion,
+  makeRoster,
+  makeRosterStateStore,
+  priorityOf,
+  rolesOf,
+  type ExecutorSpec,
+  type Role,
+  type RosterDocument,
+  type RosterShape
+} from "@llm4ts/flow/Roster"
+import {
+  makeHeldCoder,
+  rosterSeat,
+  type HeldCoder,
+  type RosterSeat,
+  type RosterView,
+  type SeatSource
+} from "@llm4ts/flow/RosterSeats"
+import * as Semaphore from "effect/Semaphore"
+import * as ScopeModule from "effect/Scope"
+import { executorConfig, httpProbe, loadRosterDocument, rosterStatePath } from "./ExecutorRoster.ts"
 import { nodeHttpClient } from "./NodeHttpClient.ts"
 import { nodeGeminiCliExecutor } from "./NodeGeminiCliExecutor.ts"
 import { nodePlainFileStore } from "./NodePlainFileStore.ts"
@@ -158,10 +186,19 @@ export interface FlowRunnerOptions {
    * nothing (see the connector capability matrix).
    */
   readonly budget?: CostBudget
+  /**
+   * The executor roster (ADR 0019): every seat is then served from it and
+   * the coder/reasoning/reviewer configs above are ignored. Omitted, the
+   * runner loads one (`LLM4TS_ROSTER`, the user's and the repository's
+   * roster files); `"none"` runs with one executor per seat.
+   */
+  readonly roster?: RosterDocument | "none"
 }
 
 export interface FlowRunnerBundle {
   readonly context: FlowContextShape
+  /** The executor roster in force (ADR 0019), when the run has one. */
+  readonly roster?: RosterDocument
   readonly events: FlowEventHub
   /** The run's cost tracker, already subscribed to `events`. */
   readonly tracker: CostTracker
@@ -430,6 +467,222 @@ export const makeFlowRunnerContext = Effect.fn("@llm4ts/runner/FlowRunner.makeCo
           }
         : {})
     })
+  /**
+   * One look at every executor before the first lease: a health URL that
+   * does not answer waits in the round for its engine; a harness that cannot
+   * start (not installed, not signed in) sits the run out.
+   */
+  const probeExecutors = (
+    roster: RosterShape,
+    seatFor: (
+      executor: ExecutorSpec,
+      role: Role,
+      workDir: string
+    ) => Effect.Effect<RosterSeat, FlowError>,
+    workDir: string
+  ): Effect.Effect<void> =>
+    Effect.forEach(
+      roster.executors,
+      (executor) =>
+        Effect.gen(function* () {
+          if (executor.health !== undefined) {
+            if (!(yield* httpProbe(executor.health))) {
+              yield* roster.exclude(
+                Exclusion.make({
+                  id: executor.id,
+                  kind: "health",
+                  until: yield* Clock.currentTimeMillis,
+                  reason: `its health check ${executor.health} does not answer`
+                })
+              )
+            }
+            return
+          }
+          const role = rolesOf(executor)[0] ?? "coder"
+          const seat = yield* Effect.result(seatFor(executor, role, workDir))
+          if (seat._tag === "Failure") {
+            yield* roster.exclude(
+              Exclusion.make({
+                id: executor.id,
+                kind: "run",
+                reason: `could not start: ${describeFlowError(seat.failure)}`
+              })
+            )
+            return
+          }
+          if (!(yield* seat.success.isAvailable)) {
+            yield* roster.exclude(
+              Exclusion.make({
+                id: executor.id,
+                kind: "run",
+                reason: `its harness '${executor.harness}' is not available (not installed, or not signed in)`
+              })
+            )
+          }
+        }),
+      { discard: true, concurrency: "unbounded" }
+    )
+
+  /**
+   * Every seat from the roster (ADR 0019): a lazily held coder at the root,
+   * an eagerly held one per `contextFor` (a story waits there for a slot),
+   * and reasoning seats leased per call, independent of the coder.
+   */
+  const rosterContext = Effect.fn("@llm4ts/runner/FlowRunner.rosterContext")(function* (
+    document: RosterDocument
+  ): Effect.fn.Return<FlowContextShape, FlowError, Scope.Scope> {
+    const runScope = yield* Effect.scope
+    const roster = yield* makeRoster({
+      executors: document.executors,
+      events,
+      state: makeRosterStateStore(dependencies.files, rosterStatePath(runEnvironment)),
+      probe: httpProbe
+    })
+    const seatCache = new Map<string, RosterSeat>()
+    const cacheLock = yield* Semaphore.make(1)
+    const seatFor = (
+      executor: ExecutorSpec,
+      role: Role,
+      workDir: string
+    ): Effect.Effect<RosterSeat, FlowError> =>
+      cacheLock.withPermit(
+        Effect.gen(function* () {
+          const readOnly = role !== "coder"
+          const key = `${executor.id}\u0000${readOnly ? "ro" : "rw"}\u0000${workDir}`
+          const cached = seatCache.get(key)
+          if (cached !== undefined) {
+            return cached
+          }
+          const configuration = executorConfig(executor, readOnly, runEnvironment)
+          if (configuration === undefined) {
+            return yield* RosterInvalid.make({
+              violations: [`executor '${executor.id}' has an unknown harness '${executor.harness}'`]
+            })
+          }
+          const seat: RosterSeat = yield* resolveSeat(
+            prepareConnector(bridged(configuration), workDir, runEnvironment)
+          ).pipe(ScopeModule.provide(runScope))
+          seatCache.set(key, seat)
+          return seat
+        })
+      )
+    const source: SeatSource = { seatFor }
+    yield* probeExecutors(roster, seatFor, options.workDir)
+
+    const judgmentConfig =
+      options.judgment ??
+      document.executors
+        .filter((spec) => rolesOf(spec).includes("judge"))
+        .flatMap((spec) => {
+          const configuration = executorConfig(spec, true, runEnvironment)
+          return configuration === undefined ? [] : [configuration]
+        })[0] ??
+      reasoning
+    const coderCapabilities = (workDir: string, held: HeldCoder) =>
+      Effect.gen(function* () {
+        const current = yield* held.lease
+        const first =
+          current ??
+          [...document.executors]
+            .filter((spec) => rolesOf(spec).includes("coder"))
+            .sort((left, right) => priorityOf(left, "coder") - priorityOf(right, "coder"))[0]
+        if (first === undefined) {
+          return ConnectorCapabilitiesClass.make({})
+        }
+        return yield* Effect.map(Effect.result(seatFor(first, "coder", workDir)), (result) =>
+          result._tag === "Success"
+            ? result.success.capabilities
+            : ConnectorCapabilitiesClass.make({})
+        )
+      })
+    const viewFor = (held: HeldCoder, workDir: string, label: string): RosterView => ({
+      forRole: (role) =>
+        rosterSeat(roster, source, role, workDir, {
+          events,
+          avoid: Effect.map(held.executor, (id) => (id === undefined ? [] : [id])),
+          borrow: held.lease,
+          label
+        }),
+      available: roster.available,
+      slots: roster.slots,
+      executor: held.executor,
+      history: held.history
+    })
+    const contextIn = (
+      workDir: string,
+      held: HeldCoder,
+      label: string,
+      rebind: boolean
+    ): Effect.Effect<FlowContextShape, FlowError> =>
+      Effect.gen(function* () {
+        const view = viewFor(held, workDir, label)
+        const judgmentSeat =
+          options.judgment === undefined
+            ? view.forRole("judge")
+            : yield* resolveSeat(
+                prepareConnector(bridged(options.judgment), workDir, runEnvironment)
+              ).pipe(ScopeModule.provide(runScope))
+        const judgment = yield* judgmentFor(judgmentSeat, judgmentConfig, runEnvironment)
+        return FlowContext.of({
+          reasoning: view.forRole(rebind ? "planner" : "reviewer"),
+          coder: held.service,
+          judgment,
+          git: makeGitTool(dependencies.process, workDir, events),
+          hosting: makeGitHubTool(dependencies.process, workDir, events),
+          events,
+          reviewers: [view.forRole("reviewer")],
+          coderCapabilities: yield* coderCapabilities(workDir, held),
+          userPrompt: options.userPrompt,
+          workDir,
+          workspace: options.workspace,
+          roster: view,
+          ...(rebind
+            ? {
+                contextFor: (directory: string, contextOptions?: ContextOptions) =>
+                  Effect.gen(function* () {
+                    const label = contextOptions?.label ?? directory
+                    const storyCoder = yield* makeHeldCoder(roster, source, directory, {
+                      events,
+                      eager: true,
+                      label,
+                      ...(contextOptions?.prefer === undefined
+                        ? {}
+                        : { prefer: contextOptions.prefer })
+                    })
+                    return yield* contextIn(directory, storyCoder, label, false)
+                  })
+              }
+            : {})
+        })
+      })
+    const rootCoder = yield* makeHeldCoder(roster, source, options.workDir, {
+      events,
+      eager: false,
+      label: "the run"
+    })
+    return yield* contextIn(options.workDir, rootCoder, "the run", true)
+  })
+
+  const rosterDocument =
+    options.roster === "none"
+      ? undefined
+      : (options.roster ??
+        (yield* loadRosterDocument({
+          files: dependencies.files,
+          environment: runEnvironment,
+          workDir: options.workDir
+        })))
+  if (rosterDocument !== undefined) {
+    const context = yield* rosterContext(rosterDocument)
+    return {
+      events,
+      tracker,
+      runId,
+      roster: rosterDocument,
+      ...(judgmentLog === undefined ? {} : { judgmentLog }),
+      context
+    }
+  }
   const seats = yield* seatsFor(options.workDir)
   return {
     events,
@@ -440,6 +693,10 @@ export const makeFlowRunnerContext = Effect.fn("@llm4ts/runner/FlowRunner.makeCo
   }
 })
 
+/** `claude (coder·reviewer·judge ×3)` — how the run header names an executor. */
+const describeExecutor = (spec: ExecutorSpec): string =>
+  `${spec.id} (${rolesOf(spec).join("·")} ×${spec.slots ?? 1})`
+
 export const runWithBundle = Effect.fn("@llm4ts/runner/FlowRunner.runWithBundle")(function* <
   A,
   E,
@@ -468,11 +725,16 @@ export const runWithBundle = Effect.fn("@llm4ts/runner/FlowRunner.runWithBundle"
   })
   if (verbosity !== "Quiet") {
     const reviewers = options.reviewers ?? []
-    const seats = [
-      `coder ${describeSeat(options.coder)}`,
-      `reasoning ${describeSeat(defaultReasoningConfig(options.coder, options.reasoning))}`,
-      ...(reviewers.length === 0 ? [] : [`reviewers ${reviewers.map(describeSeat).join(", ")}`])
-    ].join(" · ")
+    const seats =
+      bundle.roster === undefined
+        ? [
+            `coder ${describeSeat(options.coder)}`,
+            `reasoning ${describeSeat(defaultReasoningConfig(options.coder, options.reasoning))}`,
+            ...(reviewers.length === 0
+              ? []
+              : [`reviewers ${reviewers.map(describeSeat).join(", ")}`])
+          ].join(" · ")
+        : `executors ${bundle.roster.executors.map(describeExecutor).join(", ")} (roster in force: the flow's own seat choices are not used)`
     yield* surface.log(palette.info(`${seats} · ${options.workDir}`))
     if (tracePath !== undefined) {
       yield* surface.log(