@bastani/atomic 0.5.34 → 0.6.0

package/src/sdk/runtime/attached-footer.ts

@@ -9,7 +9,7 @@
  *
  * Resolves the CLI entrypoint relative to this module (runtime/ lives at
  * src/sdk/runtime/, so ../../cli.ts is the CLI). `process.argv[1]` points
- * at the orchestrator's executor-entry.ts when called from the executor,
+ * at the worker entrypoint when called from the orchestrator,
  * so it can't be used here.
  */
 

package/src/sdk/runtime/executor-env.ts

@@ -0,0 +1,45 @@
+/**
+ * Orchestrator environment variable validation — extracted into its own
+ * module so test files can import it directly without touching the
+ * executor.ts module (which is mocked in worker.test.ts and
+ * workflow-command.test.ts). Importing from here bypasses those mocks.
+ */
+
+import type { AgentType } from "../types.ts";
+import { isValidAgent } from "../../services/config/definitions.ts";
+
+/**
+ * Read and validate the required orchestrator env vars, throwing on the
+ * first missing or invalid value.
+ *
+ * Required vars: ATOMIC_WF_ID, ATOMIC_WF_TMUX, ATOMIC_WF_AGENT, ATOMIC_WF_CWD.
+ */
+export function validateOrchestratorEnv(): {
+  workflowRunId: string;
+  tmuxSessionName: string;
+  agent: AgentType;
+  cwd: string;
+} {
+  const requiredEnvVars = [
+    "ATOMIC_WF_ID",
+    "ATOMIC_WF_TMUX",
+    "ATOMIC_WF_AGENT",
+    "ATOMIC_WF_CWD",
+  ] as const;
+  for (const key of requiredEnvVars) {
+    if (process.env[key] === undefined) {
+      throw new Error(`Missing required environment variable: ${key}`);
+    }
+  }
+
+  const workflowRunId = process.env.ATOMIC_WF_ID!;
+  const tmuxSessionName = process.env.ATOMIC_WF_TMUX!;
+  const rawAgent = process.env.ATOMIC_WF_AGENT!;
+  if (!isValidAgent(rawAgent)) {
+    throw new Error(
+      `Invalid ATOMIC_WF_AGENT: "${rawAgent}". Expected one of: copilot, opencode, claude`,
+    );
+  }
+  const cwd = process.env.ATOMIC_WF_CWD!;
+  return { workflowRunId, tmuxSessionName, agent: rawAgent, cwd };
+}

package/src/sdk/runtime/executor.test.ts

@@ -12,6 +12,7 @@ import {
   shouldOverrideCopilotCliPath,
   discoverCopilotBinary,
   applyContainerEnvDefaults,
+  normalizeExternalCopilotOptions,
   type CopilotHILSessionSurface,
 } from "./executor.ts";
 import type { SavedMessage } from "../types.ts";
@@ -856,6 +857,42 @@ describe("watchCopilotSessionForElicitation", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Copilot SDK 0.3 external-server auth option normalization
+// ---------------------------------------------------------------------------
+
+describe("normalizeExternalCopilotOptions", () => {
+  test("moves client-level GitHub token to the session for cliUrl clients", () => {
+    const result = normalizeExternalCopilotOptions({
+      gitHubToken: "client-token",
+      logLevel: "error",
+    });
+
+    expect(result).toEqual({
+      clientOptions: { logLevel: "error" },
+      sessionGitHubToken: "client-token",
+    });
+  });
+
+  test("keeps an explicit session GitHub token when both levels are set", () => {
+    const result = normalizeExternalCopilotOptions(
+      { gitHubToken: "client-token" },
+      "session-token",
+    );
+
+    expect(result).toEqual({
+      clientOptions: {},
+      sessionGitHubToken: "session-token",
+    });
+  });
+
+  test("rejects useLoggedInUser because external Copilot servers own auth", () => {
+    expect(() =>
+      normalizeExternalCopilotOptions({ useLoggedInUser: false }),
+    ).toThrow("useLoggedInUser");
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Copilot CLI path discovery (Bun-without-node containers)
 // ---------------------------------------------------------------------------

package/src/sdk/runtime/executor.ts

@@ -2,19 +2,19 @@
  * Workflow runtime executor.
  *
  * Architecture:
- * 1. `executeWorkflow()` is called by the CLI command
- * 2. It creates a tmux session with an orchestrator pane that runs
- *    `bun run executor-entry.ts` (a thin wrapper that calls `runOrchestrator()`)
+ * 1. `executeWorkflow()` is called by the CLI command or worker
+ * 2. It creates a tmux session with an orchestrator pane that re-executes
+ *    the user's entrypoint file with `ATOMIC_ORCHESTRATOR_MODE=1`
  * 3. The CLI then attaches to the tmux session (user sees it live)
  * 4. The orchestrator pane calls `definition.run(workflowCtx)` — the
  *    user's callback uses `ctx.stage()` to spawn agent sessions
  *
- * The entry point is in executor-entry.ts (not this file) to avoid Bun's
- * dual-module-identity issue: Bun evaluates a file twice when it is both
- * the entry point and reached through package.json `exports` self-referencing.
+ * In the new model the user's own file (e.g. `src/worker.ts`) is re-executed
+ * with env vars (`ATOMIC_ORCHESTRATOR_MODE`, `ATOMIC_WF_KEY`) that signal
+ * re-entry. The worker detects those vars and calls `runOrchestrator(definition)`.
  */
 
-import { join, resolve } from "node:path";
+import { join } from "node:path";
 import { homedir } from "node:os";
 import { writeFile } from "node:fs/promises";
 import { statSync, accessSync, constants as fsConstants } from "node:fs";
@@ -36,7 +36,6 @@ import type {
   ProviderSession,
 } from "../types.ts";
 import {
-  isValidAgent,
   type ProviderOverrides,
 } from "../../services/config/definitions.ts";
 import { getProviderOverrides } from "../../services/config/atomic-config.ts";
@@ -48,7 +47,6 @@ import type { SessionMessage } from "@anthropic-ai/claude-agent-sdk";
 import * as tmux from "./tmux.ts";
 import { spawnMuxAttach } from "./tmux.ts";
 import { spawnAttachedFooter } from "./attached-footer.ts";
-import { WorkflowLoader } from "./loader.ts";
 import {
   clearClaudeSession,
   ClaudeClientWrapper,
@@ -133,8 +131,19 @@ export interface WorkflowRunOptions {
    * whether the workflow declares a schema. Empty record is valid.
    */
   inputs?: Record<string, string>;
-  /** Absolute path to the workflow's index.ts file (from discovery) */
-  workflowFile: string;
+  /**
+   * Absolute path to the user's entrypoint file (e.g. `src/worker.ts`).
+   * The launcher re-executes this file with `ATOMIC_ORCHESTRATOR_MODE=1`
+   * so the worker can detect re-entry and call `runOrchestrator()`.
+   * Defaults to `process.argv[1]` at the call site.
+   */
+  entrypointFile: string;
+  /**
+   * Registry key identifying this workflow, formatted as `"<agent>/<name>"`.
+   * Passed via `ATOMIC_WF_KEY` so the orchestrator can resolve the
+   * definition from the registry without a file-system scan.
+   */
+  workflowKey: string;
   /** Project root (defaults to cwd) */
   projectRoot?: string;
   /**
@@ -466,7 +475,8 @@ export async function executeWorkflow(
     definition,
     agent,
     inputs = {},
-    workflowFile,
+    entrypointFile,
+    workflowKey,
     projectRoot = process.cwd(),
     detach = false,
   } = options;
@@ -477,10 +487,8 @@ export async function executeWorkflow(
   await ensureDir(sessionsBaseDir);
 
   // Write a launcher script for the orchestrator pane.
-  // Points to executor-entry.ts (not executor.ts) to avoid Bun's
-  // dual-module-identity issue: entry points and package self-references
-  // are evaluated as separate module instances in Bun.
-  const thisFile = resolve(import.meta.dir, "executor-entry.ts");
+  // Re-executes the user's entrypoint file with ATOMIC_ORCHESTRATOR_MODE=1
+  // so the worker can detect re-entry and call runOrchestrator().
   const isWin = process.platform === "win32";
   const launcherExt = isWin ? "ps1" : "sh";
   const launcherPath = join(sessionsBaseDir, `orchestrator.${launcherExt}`);
@@ -500,9 +508,10 @@ export async function executeWorkflow(
         `$env:ATOMIC_WF_TMUX = "${escPwsh(tmuxSessionName)}"`,
         `$env:ATOMIC_WF_AGENT = "${escPwsh(agent)}"`,
         `$env:ATOMIC_WF_INPUTS = "${escPwsh(inputsB64)}"`,
-        `$env:ATOMIC_WF_FILE = "${escPwsh(workflowFile)}"`,
+        `$env:ATOMIC_ORCHESTRATOR_MODE = "1"`,
+        `$env:ATOMIC_WF_KEY = "${escPwsh(workflowKey)}"`,
         `$env:ATOMIC_WF_CWD = "${escPwsh(projectRoot)}"`,
-        `bun run "${escPwsh(thisFile)}" 2>"${escPwsh(logPath)}"`,
+        `bun run "${escPwsh(entrypointFile)}" 2>"${escPwsh(logPath)}"`,
       ].join("\n")
     : [
         "#!/bin/bash",
@@ -511,9 +520,10 @@ export async function executeWorkflow(
         `export ATOMIC_WF_TMUX="${escBash(tmuxSessionName)}"`,
         `export ATOMIC_WF_AGENT="${escBash(agent)}"`,
         `export ATOMIC_WF_INPUTS="${escBash(inputsB64)}"`,
-        `export ATOMIC_WF_FILE="${escBash(workflowFile)}"`,
+        `export ATOMIC_ORCHESTRATOR_MODE="1"`,
+        `export ATOMIC_WF_KEY="${escBash(workflowKey)}"`,
         `export ATOMIC_WF_CWD="${escBash(projectRoot)}"`,
-        `bun run "${escBash(thisFile)}" 2>"${escBash(logPath)}"`,
+        `bun run "${escBash(entrypointFile)}" 2>"${escBash(logPath)}"`,
       ].join("\n");
 
   await writeFile(launcherPath, launcherScript, { mode: 0o755 });
@@ -1204,6 +1214,48 @@ export function mergeExcludedTools(
   return merged;
 }
 
+type ExternalCopilotClientOptions = Omit<
+  StageClientOptions<"copilot">,
+  "gitHubToken" | "useLoggedInUser"
+>;
+
+interface ExternalCopilotOptions {
+  clientOptions: ExternalCopilotClientOptions;
+  sessionGitHubToken?: string;
+}
+
+/**
+ * Copilot SDK 0.3.0 rejects client-level auth options when connecting to an
+ * existing `cliUrl`. Visible stages use an already-running TUI server, so move
+ * token auth to the session-level option that 0.3.0 introduced for this case.
+ */
+export function normalizeExternalCopilotOptions(
+  clientOptions: StageClientOptions<"copilot">,
+  sessionGitHubToken?: string,
+): ExternalCopilotOptions {
+  const {
+    gitHubToken: clientGitHubToken,
+    useLoggedInUser,
+    ...externalClientOptions
+  } = clientOptions;
+
+  if (useLoggedInUser !== undefined) {
+    throw new Error(
+      "Copilot client option `useLoggedInUser` cannot be used for visible stages because they connect to an existing Copilot CLI server. Configure authentication on the server process instead.",
+    );
+  }
+
+  const normalized: ExternalCopilotOptions = {
+    clientOptions: externalClientOptions,
+  };
+  if (sessionGitHubToken !== undefined) {
+    normalized.sessionGitHubToken = sessionGitHubToken;
+  } else if (clientGitHubToken !== undefined) {
+    normalized.sessionGitHubToken = clientGitHubToken;
+  }
+  return normalized;
+}
+
 /**
  * Create the provider-specific client and session for a stage.
  * Called by the session runner after server readiness is confirmed.
@@ -1247,12 +1299,23 @@ async function initProviderClientAndSession<A extends AgentType>(
       // when the caller didn't supply their own env keeps the
       // SQLite `ExperimentalWarning` from leaking through the SDK's
       // `[CLI subprocess]` stderr forwarder.
-      const client = headless
-        ? new CopilotClient({
-            env: copilotSubprocessEnv(),
-            ...copilotClientOpts,
-          })
-        : new CopilotClient({ ...copilotClientOpts, cliUrl: serverUrl });
+      let externalCopilotOptions: ExternalCopilotOptions | undefined;
+      let client: InstanceType<typeof CopilotClient>;
+      if (headless) {
+        client = new CopilotClient({
+          env: copilotSubprocessEnv(),
+          ...copilotClientOpts,
+        });
+      } else {
+        externalCopilotOptions = normalizeExternalCopilotOptions(
+          copilotClientOpts,
+          copilotSessionOpts.gitHubToken,
+        );
+        client = new CopilotClient({
+          ...externalCopilotOptions.clientOptions,
+          cliUrl: serverUrl,
+        });
+      }
       await client.start();
       // In headless stages, add `ask_user` to the session's excludedTools so
       // the agent cannot call the interactive question tool — there is no
@@ -1260,6 +1323,9 @@ async function initProviderClientAndSession<A extends AgentType>(
       const sessionConfig = {
         onPermissionRequest: approveAll,
         ...copilotSessionOpts,
+        ...(externalCopilotOptions?.sessionGitHubToken !== undefined
+          ? { gitHubToken: externalCopilotOptions.sessionGitHubToken }
+          : {}),
         ...(headless
           ? {
               excludedTools: mergeExcludedTools(
@@ -1800,29 +1866,63 @@ function createSessionRunner(
 // Orchestrator logic — runs inside a tmux pane
 // ============================================================================
 
-export async function runOrchestrator(): Promise<void> {
-  const requiredEnvVars = [
-    "ATOMIC_WF_ID",
-    "ATOMIC_WF_TMUX",
-    "ATOMIC_WF_AGENT",
-    "ATOMIC_WF_FILE",
-    "ATOMIC_WF_CWD",
-  ] as const;
-  for (const key of requiredEnvVars) {
-    if (process.env[key] === undefined) {
-      throw new Error(`Missing required environment variable: ${key}`);
-    }
-  }
+/**
+ * Run the orchestrator inside a tmux pane.
+ *
+ * Called by the worker entrypoint when `ATOMIC_ORCHESTRATOR_MODE=1` is set.
+ * The `definition` parameter is resolved by the caller (the worker) from the
+ * registry using `ATOMIC_WF_KEY` — this function no longer performs any
+ * file-path import or workflow discovery.
+ *
+ * @param definition - Resolved workflow definition from the registry.
+ */
+export { validateOrchestratorEnv } from "./executor-env.ts";
+import { validateOrchestratorEnv } from "./executor-env.ts";
 
-  const workflowRunId = process.env.ATOMIC_WF_ID!;
-  const tmuxSessionName = process.env.ATOMIC_WF_TMUX!;
-  const rawAgent = process.env.ATOMIC_WF_AGENT!;
-  if (!isValidAgent(rawAgent)) {
+/**
+ * Orchestrator re-entry guard.
+ *
+ * When `executeWorkflow()` spawns a detached pane, it re-invokes the
+ * composition root with `ATOMIC_ORCHESTRATOR_MODE=1` +
+ * `ATOMIC_WF_KEY="<agent>/<name>"`. This helper detects that re-entry
+ * and hands off to `runOrchestrator()` with the resolved definition.
+ *
+ * Returns `true` when re-entry was handled (caller should stop normal
+ * CLI flow). Returns `false` when `ATOMIC_ORCHESTRATOR_MODE` is unset
+ * — the caller should proceed with argv parsing.
+ *
+ * The `resolve` callback lets embedded workers pass a trivial lookup
+ * (their single bound definition) while the dispatcher passes its
+ * registry. Throws on malformed or unknown keys so authoring mistakes
+ * surface loudly instead of silently hanging.
+ */
+export async function handleOrchestratorReEntry(
+  resolve: (name: string, agent: AgentType) => WorkflowDefinition | undefined,
+): Promise<boolean> {
+  if (process.env.ATOMIC_ORCHESTRATOR_MODE !== "1") {
+    return false;
+  }
+  const key = process.env.ATOMIC_WF_KEY ?? "";
+  const slashIdx = key.indexOf("/");
+  if (slashIdx < 0) {
     throw new Error(
-      `Invalid ATOMIC_WF_AGENT: "${rawAgent}". Expected one of: copilot, opencode, claude`,
+      `ATOMIC_ORCHESTRATOR_MODE=1 but ATOMIC_WF_KEY "${key}" is malformed — expected "<agent>/<name>"`,
     );
   }
-  const agent: AgentType = rawAgent;
+  const agent = key.slice(0, slashIdx) as AgentType;
+  const name = key.slice(slashIdx + 1);
+  const def = resolve(name, agent);
+  if (!def) {
+    throw new Error(`ATOMIC_WF_KEY "${key}" not found in registry`);
+  }
+  await runOrchestrator(def);
+  return true;
+}
+
+export async function runOrchestrator(
+  definition: WorkflowDefinition,
+): Promise<void> {
+  const { workflowRunId, tmuxSessionName, agent, cwd } = validateOrchestratorEnv();
   // ATOMIC_WF_INPUTS carries the full input payload. Free-form
   // workflows store their single positional prompt under the `prompt`
   // key so workflow authors always read it via `ctx.inputs.prompt`.
@@ -1832,8 +1932,6 @@ export async function runOrchestrator(): Promise<void> {
   // A bare prompt string is still useful for the panel header and the
   // session-dir metadata.json — both just want something displayable.
   const prompt = inputs.prompt ?? "";
-  const workflowFile = process.env.ATOMIC_WF_FILE!;
-  const cwd = process.env.ATOMIC_WF_CWD!;
 
   process.chdir(cwd);
 
@@ -1915,28 +2013,9 @@ export async function runOrchestrator(): Promise<void> {
   };
 
   try {
-    const plan: WorkflowLoader.Plan = {
-      name: workflowFile.split("/").at(-3) ?? "unknown",
-      agent,
-      path: workflowFile,
-      source: "local",
-    };
-
-    const loaded = await WorkflowLoader.loadWorkflow(plan, {
-      warn(warnings) {
-        for (const w of warnings) {
-          console.warn(`⚠ [${w.rule}] ${w.message}`);
-        }
-      },
-    });
-    if (!loaded.ok) {
-      throw new Error(loaded.message);
-    }
-    const definition = loaded.value.definition;
-
     // Parse integer inputs to numbers so `ctx.inputs.<name>` matches the
-    // declared type. Do this after loading (when the schema is known) and
-    // mutate shared.inputs so per-stage SessionContexts see the same shape.
+    // declared type. Mutate shared.inputs so per-stage SessionContexts see
+    // the same shape.
     shared.inputs = coerceInputsBySchema(inputs, definition.inputs);
 
     await Bun.write(

package/src/sdk/types.ts

@@ -412,7 +412,7 @@ export interface WorkflowOptions<
    *
    * When set, the CLI refuses to load the workflow on an older install
    * and surfaces an actionable "update required" entry in the picker
-   * and `atomic workflow -l` output instead of silently dropping it.
+   * and `atomic workflow list` output instead of silently dropping it.
    *
    * Leave unset (the default) to opt out entirely — the workflow will
    * be treated as compatible with every CLI version. Use this when you
@@ -425,6 +425,159 @@ export interface WorkflowOptions<
   minSDKVersion?: string;
 }
 
+// ─── Registry + WorkflowCli types ───────────────────────────────────────────
+
+/**
+ * Structural constraint for workflows accepted by `Registry.register()`.
+ *
+ * Uses `run: (...args: never[]) => Promise<void>` instead of the full
+ * `WorkflowDefinition<A, I>` constraint to avoid contravariance failures.
+ * A narrowly-typed `run(ctx: WorkflowContext<"claude">) => void` is not
+ * assignable to `run(ctx: WorkflowContext<AgentType>) => void` under
+ * `--strictFunctionTypes` (contravariant parameter position). Using
+ * `(...args: never[]) => Promise<void>` sidesteps this: any callable is
+ * assignable to a function that takes `never` args. Type narrowing on the
+ * accumulating `T` generic is still preserved via `W["agent"]`/`W["name"]`.
+ */
+export type RegistrableWorkflow = {
+  readonly __brand: "WorkflowDefinition";
+  readonly agent: AgentType;
+  readonly name: string;
+  readonly description: string;
+  readonly inputs: readonly WorkflowInput[];
+  readonly minSDKVersion: string | null;
+  readonly run: (...args: never[]) => Promise<void>;
+};
+
+/**
+ * Immutable, chainable registry of compiled workflow definitions.
+ *
+ * The generic parameter `T` accumulates the registered set as a
+ * `Record<"${agent}/${name}", WorkflowDefinition>` intersection, giving
+ * `get()` a typed return without casting.
+ */
+export type Registry<
+  T extends Record<string, WorkflowDefinition> = Record<string, WorkflowDefinition>,
+> = {
+  /**
+   * Register a workflow definition. Returns a new Registry with the
+   * definition added. Throws if the same `${agent}/${name}` key is
+   * already registered.
+   */
+  register<W extends RegistrableWorkflow>(
+    wf: W,
+  ): Registry<T & Record<`${W["agent"]}/${W["name"]}`, W>>;
+
+  /**
+   * Retrieve a registered definition by its composite key.
+   * Compile-time typed based on the accumulated registry type.
+   */
+  get<K extends keyof T>(key: K): T[K];
+
+  /** Return true if a workflow with the given composite key is registered. */
+  has(key: string): boolean;
+
+  /** Return all registered definitions as a readonly array. */
+  list(): readonly WorkflowDefinition[];
+
+  /**
+   * Resolve a workflow by name + agent. Composes the composite key
+   * internally. Returns `undefined` when not found.
+   */
+  resolve(name: string, agent: AgentType): WorkflowDefinition | undefined;
+};
+
+/**
+ * Argv control for `WorkflowCli.run`.
+ *
+ * - `undefined` — parse `process.argv` (default).
+ * - `string[]` — parse this explicit argv list (tests, embedding).
+ * - `false` — skip parsing; use `inputs` / `name` / `agent` as provided.
+ */
+export type ArgvMode = string[] | false;
+
+/** Options for constructing a WorkflowCli via `createWorkflowCli()`. */
+export interface CreateWorkflowCliOptions {
+  /** Programmatic inputs. CLI flags override these. */
+  inputs?: Record<string, string>;
+  /**
+   * Absolute path to the composition root file. The executor re-executes
+   * this path with `ATOMIC_ORCHESTRATOR_MODE=1` when detach is requested,
+   * so re-entry lands on the module that wired the dispatcher. Defaults
+   * to `process.argv[1]` — override when your composition root isn't
+   * argv[1] (test harnesses, bundled CLIs, embedded programs).
+   */
+  entry?: string;
+  /**
+   * Hook to attach sibling commands to the standalone `run()` CLI. The
+   * callback runs once against the Commander program `run()` built
+   * internally. Not used by the `toCommand` adapter — if you're embedding,
+   * add your siblings to the parent directly.
+   */
+  extend?: (program: import("@commander-js/extra-typings").Command) => void;
+  /**
+   * When `true` (the default), the generated CLI auto-registers the
+   * session + status management subcommands — `session list`,
+   * `session connect`, `session kill`, and `status` — so SDK users get
+   * the same monitoring UX as `atomic workflow …` without needing the
+   * global `atomic` binary.
+   *
+   * Every session spawned by the SDK lives on the shared `atomic` tmux
+   * socket, so these commands are pure pass-throughs to the same
+   * implementations the global CLI uses; there's no divergence. Set to
+   * `false` only when you want a minimal CLI (e.g. programmatic invocation
+   * or embedding under a parent Commander program where the parent owns
+   * session management).
+   *
+   * The `session` and `status` names are reserved — workflow inputs
+   * declared with those names will throw at `defineWorkflow` time to
+   * avoid flag collisions.
+   */
+  includeManagementCommands?: boolean;
+}
+
+/**
+ * A CLI program that resolves `--name` + `--agent` from argv and runs the
+ * matching workflow from a registry. Used by multi-workflow CLIs (e.g.
+ * the internal `atomic workflow` command) and single-workflow entry points.
+ *
+ * Framework-agnostic by design. To embed under a parent CLI, use the
+ * `toCommand` adapter in `@bastani/atomic/workflows/commander`.
+ */
+export interface WorkflowCli<
+  T extends Record<string, WorkflowDefinition> = Record<string, WorkflowDefinition>,
+> {
+  /** Registry the CLI was constructed with. */
+  readonly registry: Registry<T>;
+  /**
+   * Absolute path the executor re-execs on `--detach`. Defaults to
+   * `process.argv[1]`; override via `createWorkflowCli(reg, { entry })`.
+   */
+  readonly entry: string;
+  /**
+   * Input defaults supplied at construction. The adapter reads these so
+   * CLI-built Commands merge them identically to `run()`.
+   */
+  readonly defaults: Record<string, string> | undefined;
+  /**
+   * Run the workflow CLI.
+   *
+   * - Default (`argv` unset): parses `process.argv` with `-n/--name`,
+   *   `-a/--agent`, and the per-input union across the registry;
+   *   `inputs`/`name`/`agent` layer in as defaults.
+   * - `argv: [...]`: parses the given argv list the same way.
+   * - `argv: false`: skip parsing; `name` and `agent` are required and
+   *   `inputs` are used as-is.
+   */
+  run(options?: {
+    name?: string;
+    agent?: AgentType;
+    inputs?: Record<string, string>;
+    argv?: ArgvMode;
+    detach?: boolean;
+  }): Promise<void>;
+}
+
 /**
  * A compiled workflow definition — the sealed output of defineWorkflow().compile().
  */
@@ -434,14 +587,26 @@ export interface WorkflowDefinition<
 > {
   readonly __brand: "WorkflowDefinition";
   readonly name: string;
+  /** The agent this workflow targets. Set via `.for(agent)` in the builder. */
+  readonly agent: A;
   readonly description: string;
-  /** Declared input schema — empty array for free-form workflows. */
-  readonly inputs: readonly WorkflowInput[];
+  /**
+   * Declared input schema — empty tuple for free-form workflows.
+   * Typed as the builder-supplied `I` so consumers (e.g.
+   * `createWorkflowCli(def)`) can derive the narrow `InputsOf<I>` shape
+   * without carrying a second generic parameter.
+   */
+  readonly inputs: I;
   /**
    * Minimum Atomic SDK version required. `null` when the workflow
    * declared no requirement — treated as compatible with every CLI.
    */
   readonly minSDKVersion: string | null;
   /** The workflow's entry point. Called by the executor with a WorkflowContext. */
-  readonly run: (ctx: WorkflowContext<A, I>) => Promise<void>;
+  // Method signature (not a property) so TypeScript treats `run` as bivariant
+  // under --strictFunctionTypes — this allows a WorkflowDefinition<"claude">
+  // to be assigned to WorkflowDefinition<AgentType> even though `agent` is
+  // narrowed. Property function signatures would be contravariant and reject
+  // the assignment. See: https://www.typescriptlang.org/docs/handbook/2/functions.html
+  run(ctx: WorkflowContext<A, I>): Promise<void>;
 }