@bastani/atomic 0.6.4 → 0.6.5

package/src/sdk/primitives/sessions.ts

@@ -0,0 +1,328 @@
+/**
+ * Session-management primitives.
+ *
+ * Thin wrappers around the tmux runtime utilities and the on-disk
+ * `~/.atomic/sessions/<workflowRunId>/` layout. Consumers (atomic CLI,
+ * third-party CLIs, embedding TUIs) call these instead of touching tmux
+ * commands or the status-writer schema directly.
+ */
+
+import { join } from "node:path";
+import { homedir } from "node:os";
+import {
+  attachSession as tmuxAttach,
+  detachClients as tmuxDetachClients,
+  isTmuxInstalled,
+  killSession,
+  listSessions as listAllTmuxSessions,
+  nextWindow as tmuxNextWindow,
+  previousWindow as tmuxPreviousWindow,
+  selectWindow as tmuxSelectWindow,
+  type SessionType,
+  type TmuxSession,
+} from "../runtime/tmux.ts";
+import {
+  readSnapshot,
+  workflowRunIdFromTmuxName,
+  type WorkflowStatusSnapshot,
+} from "../runtime/status-writer.ts";
+import { MissingDependencyError, SessionNotFoundError } from "../errors.ts";
+import type { AgentType, SavedMessage } from "../types.ts";
+
+/** Scope filter for session listings — chat sessions, workflow sessions, or both. */
+export type SessionScope = "chat" | "workflow" | "all";
+
+/** Single session entry returned by `listSessions` / `getSession`. */
+export interface SessionInfo {
+  /** Tmux session name (e.g. `atomic-wf-claude-ralph-a1b2c3d4`). */
+  id: string;
+  /** Session type derived from the name prefix. */
+  type?: SessionType;
+  /** Agent backend that owns this session. */
+  agent?: string;
+  /** ISO 8601 creation timestamp. */
+  created: string;
+  /** Whether a tmux client is currently attached. */
+  attached: boolean;
+}
+
+/** Status snapshot persisted by the orchestrator at `~/.atomic/sessions/<id>/status.json`. */
+export type StatusSnapshot = WorkflowStatusSnapshot;
+
+/** Options for filtering `listSessions()`. */
+export interface ListSessionsOptions {
+  /** Restrict to one or more agent backends. */
+  agent?: AgentType | readonly AgentType[];
+  /** Restrict by session kind. Defaults to `"all"`. */
+  scope?: SessionScope;
+}
+
+/**
+ * Injectable dependencies for the session primitives.
+ *
+ * Defaults wire through to the real tmux/status-writer implementations.
+ * Tests pass in mocks; embedding consumers can override the base directory
+ * or swap the tmux backend (e.g. for psmux on Windows) without monkey-
+ * patching the underlying modules.
+ */
+export interface SessionPrimitiveDeps {
+  isTmuxInstalled: () => boolean;
+  listAllTmuxSessions: () => readonly TmuxSession[];
+  killSession: (id: string) => void;
+  attachSession: (id: string) => void;
+  detachClients: (id: string) => void;
+  nextWindow: (id: string) => void;
+  previousWindow: (id: string) => void;
+  /** `target` is a tmux window target like `<session>:<index>`. */
+  selectWindow: (target: string) => void;
+  readSnapshot: typeof readSnapshot;
+  /** Base directory for session artefacts. Defaults to `~/.atomic/sessions`. */
+  sessionsBaseDir: string;
+}
+
+/** Default deps object — wires through to the real implementations. */
+const defaultDeps: SessionPrimitiveDeps = {
+  isTmuxInstalled,
+  listAllTmuxSessions,
+  killSession,
+  attachSession: tmuxAttach,
+  detachClients: tmuxDetachClients,
+  nextWindow: tmuxNextWindow,
+  previousWindow: tmuxPreviousWindow,
+  selectWindow: tmuxSelectWindow,
+  readSnapshot,
+  sessionsBaseDir: join(homedir(), ".atomic", "sessions"),
+};
+
+/** Convert a TmuxSession into the consumer-facing SessionInfo shape. */
+function toSessionInfo(s: TmuxSession): SessionInfo {
+  return {
+    id: s.name,
+    type: s.type,
+    agent: s.agent,
+    created: s.created,
+    attached: s.attached,
+  };
+}
+
+/** Filter sessions by scope. */
+function filterByScope(
+  sessions: readonly TmuxSession[],
+  scope: SessionScope,
+): TmuxSession[] {
+  if (scope === "all") return [...sessions];
+  return sessions.filter((s) => s.type === scope);
+}
+
+/** Filter sessions by an allow-list of agent backends. */
+function filterByAgents(
+  sessions: readonly TmuxSession[],
+  agents: readonly AgentType[],
+): TmuxSession[] {
+  if (agents.length === 0) return [...sessions];
+  const allowed = new Set<string>(agents);
+  return sessions.filter((s) => s.agent !== undefined && allowed.has(s.agent));
+}
+
+/**
+ * List atomic-managed tmux sessions on the shared `atomic` socket.
+ *
+ * Returns an empty array when tmux is not installed or the server has no
+ * sessions — never throws on the cold-start path.
+ */
+export function listSessions(
+  options: ListSessionsOptions = {},
+  deps: SessionPrimitiveDeps = defaultDeps,
+): SessionInfo[] {
+  if (!deps.isTmuxInstalled()) return [];
+  const scope = options.scope ?? "all";
+  const agents: readonly AgentType[] = options.agent === undefined
+    ? []
+    : Array.isArray(options.agent)
+      ? (options.agent as readonly AgentType[])
+      : [options.agent as AgentType];
+
+  const all = deps.listAllTmuxSessions();
+  const scoped = filterByScope(all, scope);
+  const filtered = filterByAgents(scoped, agents);
+  return filtered.map(toSessionInfo);
+}
+
+/** Look up a single session by id. Returns `undefined` when not found. */
+export function getSession(
+  id: string,
+  deps: SessionPrimitiveDeps = defaultDeps,
+): SessionInfo | undefined {
+  if (!deps.isTmuxInstalled()) return undefined;
+  const match = deps.listAllTmuxSessions().find((s) => s.name === id);
+  return match ? toSessionInfo(match) : undefined;
+}
+
+/**
+ * Stop a running session. Best-effort: if the session is already gone
+ * the underlying `tmux kill-session` is a no-op-equivalent.
+ */
+export async function stopSession(
+  id: string,
+  deps: SessionPrimitiveDeps = defaultDeps,
+): Promise<void> {
+  if (!deps.isTmuxInstalled()) return;
+  try {
+    deps.killSession(id);
+  } catch {
+    // tmux returns non-zero when the session has already been torn down —
+    // surface that as a successful stop rather than a hard failure.
+  }
+}
+
+/**
+ * Attach to a running session interactively. Only valid when the host
+ * process has a TTY — otherwise the underlying tmux invocation will
+ * complain that it can't take over the terminal.
+ */
+export async function attachSession(
+  id: string,
+  deps: SessionPrimitiveDeps = defaultDeps,
+): Promise<void> {
+  if (!deps.isTmuxInstalled()) {
+    throw new MissingDependencyError("tmux");
+  }
+  deps.attachSession(id);
+}
+
+/**
+ * Validate that tmux is installed and the session id exists on the
+ * atomic socket. Shared preamble for the navigation primitives.
+ */
+function ensureSession(id: string, deps: SessionPrimitiveDeps): void {
+  if (!deps.isTmuxInstalled()) {
+    throw new MissingDependencyError("tmux");
+  }
+  const session = deps.listAllTmuxSessions().find((s) => s.name === id);
+  if (!session) {
+    throw new SessionNotFoundError(id);
+  }
+}
+
+/**
+ * Move the session's current-window pointer to the next window.
+ * Mirrors the `Ctrl+\` keybinding bound inside an attached client.
+ *
+ * Pure navigation: never attaches. An already-attached client sees the
+ * change live; if no client is watching, the session's current-window
+ * pointer is updated silently and a subsequent `attachSession` will
+ * land on the new window. Compose `nextWindow(id)` + `attachSession(id)`
+ * if you want navigate-then-attach.
+ */
+export async function nextWindow(
+  id: string,
+  deps: SessionPrimitiveDeps = defaultDeps,
+): Promise<void> {
+  ensureSession(id, deps);
+  deps.nextWindow(id);
+}
+
+/**
+ * Move the session's current-window pointer to the previous window.
+ * Symmetrical counterpart to {@link nextWindow} — also pure navigation.
+ */
+export async function previousWindow(
+  id: string,
+  deps: SessionPrimitiveDeps = defaultDeps,
+): Promise<void> {
+  ensureSession(id, deps);
+  deps.previousWindow(id);
+}
+
+/**
+ * Jump to the orchestrator window (window 0) of the target session.
+ * Mirrors the `Ctrl+G` keybinding bound inside an attached client.
+ *
+ * For workflow sessions, window 0 hosts the orchestrator graph view;
+ * for chat sessions, window 0 is the agent pane. Pure navigation —
+ * never attaches.
+ */
+export async function gotoOrchestrator(
+  id: string,
+  deps: SessionPrimitiveDeps = defaultDeps,
+): Promise<void> {
+  ensureSession(id, deps);
+  deps.selectWindow(`${id}:0`);
+}
+
+/**
+ * Detach every client currently attached to a session. The session
+ * itself keeps running in the background — re-attach with
+ * {@link attachSession} or `tmux -L atomic attach -t <id>`.
+ *
+ * Best-effort, idempotent: returns silently when tmux is missing, the
+ * session is already gone, or no clients are attached.
+ */
+export async function detachSession(
+  id: string,
+  deps: SessionPrimitiveDeps = defaultDeps,
+): Promise<void> {
+  if (!deps.isTmuxInstalled()) return;
+  try {
+    deps.detachClients(id);
+  } catch {
+    // tmux returns non-zero when the session is gone or no clients are
+    // attached — surface that as a successful detach rather than a hard
+    // failure, matching `stopSession`'s best-effort semantics.
+  }
+}
+
+/**
+ * Read the on-disk status snapshot for a workflow session. Returns
+ * `null` when the orchestrator hasn't written one yet (the workflow
+ * is still very early) or when the directory doesn't exist.
+ */
+export async function getSessionStatus(
+  id: string,
+  deps: SessionPrimitiveDeps = defaultDeps,
+): Promise<StatusSnapshot | null> {
+  const runId = workflowRunIdFromTmuxName(id);
+  if (!runId) return null;
+  return await deps.readSnapshot(join(deps.sessionsBaseDir, runId));
+}
+
+/**
+ * Read the saved native-message transcript for a single session inside
+ * a workflow run. `id` is the tmux session id (`atomic-wf-...`); the
+ * `sessionName` is the `name` passed to `ctx.stage({ name })` whose
+ * messages were saved via `s.save(...)`.
+ *
+ * Returns an empty array when no transcript was persisted (e.g. the
+ * workflow chose not to call `s.save`).
+ */
+export async function getSessionTranscript(
+  id: string,
+  sessionName: string,
+  deps: SessionPrimitiveDeps = defaultDeps,
+): Promise<SavedMessage[]> {
+  const runId = workflowRunIdFromTmuxName(id);
+  if (!runId) return [];
+  const file = Bun.file(
+    join(deps.sessionsBaseDir, runId, sessionName, "messages.json"),
+  );
+  if (!(await file.exists())) return [];
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(await file.text());
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(parsed)) return [];
+  return parsed.filter(isSavedMessage);
+}
+
+/** Runtime guard for deserialised SavedMessage objects. */
+function isSavedMessage(value: unknown): value is SavedMessage {
+  if (!value || typeof value !== "object") return false;
+  const v = value as Record<string, unknown>;
+  return (
+    v.provider === "claude" ||
+    v.provider === "copilot" ||
+    v.provider === "opencode"
+  );
+}

package/src/sdk/runtime/executor.ts

@@ -2,16 +2,20 @@
  * Workflow runtime executor.
  *
  * Architecture:
- * 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`
+ * 1. `executeWorkflow()` is called by the CLI command (e.g. atomic) or by
+ *    the SDK's `runWorkflow()` primitive
+ * 2. It creates a tmux session with an orchestrator pane that runs the
+ *    SDK-owned `orchestrator-entry.ts` with three positional args:
+ *    `<workflowSource> <agent> <inputsB64>`
  * 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
+ * 4. The orchestrator pane imports the workflow module by `source`,
+ *    calls `runOrchestrator(definition, inputs)`, which then calls
+ *    `definition.run(workflowCtx)` — the user's callback uses
+ *    `ctx.stage()` to spawn agent sessions
  *
- * 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)`.
+ * The dev's CLI is never re-imported. The SDK orchestrator entry script
+ * is the only re-exec target, so there is no orchestrator-mode env var
+ * re-entry signal and no boilerplate in user code.
  */
 
 import { join } from "node:path";
@@ -132,19 +136,6 @@ export interface WorkflowRunOptions {
    * whether the workflow declares a schema. Empty record is valid.
    */
   inputs?: Record<string, 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;
   /**
@@ -402,33 +393,6 @@ export function escPwsh(s: string): string {
     .replace(/\r/g, "`r");
 }
 
-/**
- * Decode the ATOMIC_WF_INPUTS env var (base64-encoded JSON) into a
- * `Record<string, string>`. Returns an empty record when the variable
- * is missing, malformed, or does not decode to a string-map object —
- * structured inputs are optional, so a corrupt payload must never
- * prevent free-form workflows from running.
- */
-export function parseInputsEnv(
-  raw: string | undefined,
-): Record<string, string> {
-  if (!raw) return {};
-  try {
-    const decoded = Buffer.from(raw, "base64").toString("utf-8");
-    const parsed: unknown = JSON.parse(decoded);
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-      return {};
-    }
-    const out: Record<string, string> = {};
-    for (const [k, v] of Object.entries(parsed)) {
-      if (typeof v === "string") out[k] = v;
-    }
-    return out;
-  } catch {
-    return {};
-  }
-}
-
 /**
  * Coerce raw string inputs to their declared runtime types. Integer inputs
  * become `number`; every other declared type passes through as `string`.
@@ -471,13 +435,11 @@ export function coerceInputsBySchema(
  */
 export async function executeWorkflow(
   options: WorkflowRunOptions,
-): Promise<void> {
+): Promise<{ id: string; tmuxSessionName: string }> {
   const {
     definition,
     agent,
     inputs = {},
-    entrypointFile,
-    workflowKey,
     projectRoot = process.cwd(),
     detach = false,
   } = options;
@@ -501,8 +463,9 @@ export async function executeWorkflow(
   await ensureDir(sessionsBaseDir);
 
   // Write a launcher script for the orchestrator pane.
-  // Re-executes the user's entrypoint file with ATOMIC_ORCHESTRATOR_MODE=1
-  // so the worker can detect re-entry and call runOrchestrator().
+  // Runs the SDK-owned orchestrator entry script with positional args:
+  //   bun <orchestrator-entry.ts> <workflowSource> <agent> <inputsB64>
+  // The dev's own CLI is never re-execed.
   const isWin = process.platform === "win32";
   const launcherExt = isWin ? "ps1" : "sh";
   const launcherPath = join(sessionsBaseDir, `orchestrator.${launcherExt}`);
@@ -515,17 +478,18 @@ export async function executeWorkflow(
   // read the user's prompt via `ctx.inputs.prompt`.
   const inputsB64 = Buffer.from(JSON.stringify(inputs)).toString("base64");
 
+  // Resolve the SDK's orchestrator entry script (sibling of this file).
+  const orchestratorEntry = join(import.meta.dir, "orchestrator-entry.ts");
+  const workflowSource = definition.source;
+
   const launcherScript = isWin
     ? [
         `Set-Location "${escPwsh(projectRoot)}"`,
         `$env:ATOMIC_WF_ID = "${escPwsh(workflowRunId)}"`,
         `$env:ATOMIC_WF_TMUX = "${escPwsh(tmuxSessionName)}"`,
         `$env:ATOMIC_WF_AGENT = "${escPwsh(agent)}"`,
-        `$env:ATOMIC_WF_INPUTS = "${escPwsh(inputsB64)}"`,
-        `$env:ATOMIC_ORCHESTRATOR_MODE = "1"`,
-        `$env:ATOMIC_WF_KEY = "${escPwsh(workflowKey)}"`,
         `$env:ATOMIC_WF_CWD = "${escPwsh(projectRoot)}"`,
-        `bun run "${escPwsh(entrypointFile)}" 2>"${escPwsh(logPath)}"`,
+        `bun run "${escPwsh(orchestratorEntry)}" "${escPwsh(workflowSource)}" "${escPwsh(agent)}" "${escPwsh(inputsB64)}" 2>"${escPwsh(logPath)}"`,
       ].join("\n")
     : [
         "#!/bin/bash",
@@ -533,11 +497,8 @@ export async function executeWorkflow(
         `export ATOMIC_WF_ID="${escBash(workflowRunId)}"`,
         `export ATOMIC_WF_TMUX="${escBash(tmuxSessionName)}"`,
         `export ATOMIC_WF_AGENT="${escBash(agent)}"`,
-        `export ATOMIC_WF_INPUTS="${escBash(inputsB64)}"`,
-        `export ATOMIC_ORCHESTRATOR_MODE="1"`,
-        `export ATOMIC_WF_KEY="${escBash(workflowKey)}"`,
         `export ATOMIC_WF_CWD="${escBash(projectRoot)}"`,
-        `bun run "${escBash(entrypointFile)}" 2>"${escBash(logPath)}"`,
+        `bun run "${escBash(orchestratorEntry)}" "${escBash(workflowSource)}" "${escBash(agent)}" "${escBash(inputsB64)}" 2>"${escBash(logPath)}"`,
       ].join("\n");
 
   await writeFile(launcherPath, launcherScript, { mode: 0o755 });
@@ -553,7 +514,7 @@ export async function executeWorkflow(
     // new-session -d). Print connection hints and return so the caller
     // can exit cleanly without blocking on the orchestrator.
     printDetachedBanner(tmuxSessionName);
-    return;
+    return { id: workflowRunId, tmuxSessionName };
   }
 
   if (tmux.isInsideAtomicSocket()) {
@@ -567,6 +528,8 @@ export async function executeWorkflow(
     const attachProc = spawnMuxAttach(tmuxSessionName);
     await attachProc.exited;
   }
+
+  return { id: workflowRunId, tmuxSessionName };
 }
 
 /**
@@ -1906,71 +1869,29 @@ function createSessionRunner(
 // Orchestrator logic — runs inside a tmux pane
 // ============================================================================
 
-/**
- * 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";
 
 /**
- * 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.
+ * Run the orchestrator for a compiled workflow 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.
+ * Called by the SDK's `orchestrator-entry.ts` after it imports the
+ * workflow module by `source` and decodes the inputs payload from argv.
+ * The runtime environment (`ATOMIC_WF_ID`, `ATOMIC_WF_TMUX`,
+ * `ATOMIC_WF_AGENT`, `ATOMIC_WF_CWD`) is set by the launcher script that
+ * `executeWorkflow()` writes — those vars describe *where* this
+ * orchestrator is running, not what to do.
  */
-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(
-      `ATOMIC_ORCHESTRATOR_MODE=1 but ATOMIC_WF_KEY "${key}" is malformed — expected "<agent>/<name>"`,
-    );
-  }
-  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,
+  inputs: Record<string, string> = {},
 ): 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`.
-  // An unset, missing, or malformed payload falls back to an empty
-  // record so `ctx.inputs.prompt` gracefully becomes `undefined`.
-  const inputs = parseInputsEnv(process.env.ATOMIC_WF_INPUTS);
   // A bare prompt string is still useful for the panel header and the
   // session-dir metadata.json — both just want something displayable.
+  // Free-form workflows store their single positional prompt under the
+  // `prompt` key so workflow authors always read it via
+  // `ctx.inputs.prompt`.
   const prompt = inputs.prompt ?? "";
 
   process.chdir(cwd);

package/src/sdk/runtime/orchestrator-entry.ts

@@ -0,0 +1,110 @@
+#!/usr/bin/env bun
+/**
+ * SDK-owned orchestrator entry script.
+ *
+ * Run as the tmux pane command for every workflow spawned by `runWorkflow`.
+ * Reads the workflow source path, agent, and base64-encoded inputs from
+ * positional argv, imports the workflow module, validates the default
+ * export, and hands off to `runOrchestrator()`.
+ *
+ * Argv layout (after `bun <this-file>`):
+ *   argv[2] = absolute path to the workflow's source file
+ *             (the `source` field from `defineWorkflow({ source: ... })`)
+ *   argv[3] = agent — one of "claude" | "copilot" | "opencode"
+ *   argv[4] = base64-encoded JSON record of structured inputs
+ *
+ * The dev's CLI never re-imports its own argv[1] — there's no
+ * `ATOMIC_ORCHESTRATOR_MODE` env var, no `handleOrchestratorReentry()`,
+ * no boilerplate. This file is the only re-exec target.
+ *
+ * The remaining ATOMIC_WF_* env vars (ID, TMUX, AGENT, CWD) are still set
+ * by the launcher script written by `executeWorkflow()` — they describe
+ * the runtime environment (which tmux session, which workflow run id,
+ * etc.) rather than acting as a re-entry signal.
+ */
+
+import { runOrchestrator } from "./executor.ts";
+import type { AgentType, WorkflowDefinition } from "../types.ts";
+import { isValidAgent } from "../../services/config/definitions.ts";
+import { InvalidWorkflowError } from "../errors.ts";
+
+/** Runtime guard for the imported module's default export. */
+function isWorkflowDefinition(value: unknown): value is WorkflowDefinition {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { __brand?: unknown }).__brand === "WorkflowDefinition"
+  );
+}
+
+/** Decode the base64 inputs payload into a string-keyed record. */
+function decodeInputs(b64: string): Record<string, string> {
+  if (b64 === "") return {};
+  let decoded: string;
+  try {
+    decoded = Buffer.from(b64, "base64").toString("utf-8");
+  } catch {
+    return {};
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(decoded);
+  } catch {
+    return {};
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return {};
+  }
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(parsed)) {
+    if (typeof v === "string") out[k] = v;
+  }
+  return out;
+}
+
+async function main(): Promise<void> {
+  const sourcePath = process.argv[2];
+  const agentRaw = process.argv[3];
+  const inputsB64 = process.argv[4] ?? "";
+
+  if (!sourcePath || !agentRaw) {
+    throw new Error(
+      "[atomic/orchestrator-entry] Missing positional arguments. " +
+        "Expected: <workflowSource> <agent> <inputsB64>",
+    );
+  }
+
+  if (!isValidAgent(agentRaw)) {
+    throw new Error(
+      `[atomic/orchestrator-entry] Invalid agent "${agentRaw}". ` +
+        `Expected one of: claude, copilot, opencode.`,
+    );
+  }
+  const agent: AgentType = agentRaw;
+
+  // Import the workflow module by its source path. The dev's `defineWorkflow`
+  // call passed `source: import.meta.path`, so this is the same path the SDK
+  // captured at build time.
+  const mod: unknown = await import(sourcePath);
+  const def = (mod as { default?: unknown }).default;
+
+  if (!isWorkflowDefinition(def)) {
+    throw new InvalidWorkflowError(sourcePath);
+  }
+
+  if (def.agent !== agent) {
+    throw new Error(
+      `[atomic/orchestrator-entry] Workflow at "${sourcePath}" targets ` +
+        `agent "${def.agent}" but the orchestrator was started for agent ` +
+        `"${agent}". This usually means the wrong workflow file was passed ` +
+        `to runWorkflow().`,
+    );
+  }
+
+  const inputs = decodeInputs(inputsB64);
+  await runOrchestrator(def, inputs);
+}
+
+if (import.meta.main) {
+  await main();
+}