@bastani/atomic 0.5.3 → 0.5.4-0

package/README.md

@@ -167,11 +167,16 @@ export default defineWorkflow<"claude">({
   description: "Research -> Implement -> Review",
 })
   .run(async (ctx) => {
+    // Free-form workflows receive their positional prompt under
+    // `ctx.inputs.prompt`. Destructure it once so every stage below
+    // can close over a bare string.
+    const prompt = ctx.inputs.prompt ?? "";
+
     const research = await ctx.stage(
       { name: "research", description: "Analyze the codebase" },
       {}, {},
       async (s) => {
-        await s.session.query(`/research-codebase ${s.userPrompt}`);
+        await s.session.query(`/research-codebase ${prompt}`);
         s.save(s.sessionId);
       },
     );
@@ -250,11 +255,13 @@ export default defineWorkflow<"claude">({
   description: "Two-session pipeline: describe -> summarize",
 })
   .run(async (ctx) => {
+    const prompt = ctx.inputs.prompt ?? "";
+
     const describe = await ctx.stage(
       { name: "describe", description: "Ask Claude to describe the project" },
       {}, {},
       async (s) => {
-        await s.session.query(s.userPrompt);
+        await s.session.query(prompt);
         s.save(s.sessionId);
       },
     );
@@ -287,10 +294,12 @@ export default defineWorkflow<"claude">({
   description: "describe -> [summarize-a, summarize-b] -> merge",
 })
   .run(async (ctx) => {
+    const prompt = ctx.inputs.prompt ?? "";
+
     const describe = await ctx.stage(
       { name: "describe" }, {}, {},
       async (s) => {
-        await s.session.query(s.userPrompt);
+        await s.session.query(prompt);
         s.save(s.sessionId);
       },
     );
@@ -322,6 +331,71 @@ export default defineWorkflow<"claude">({
 
 </details>
 
+<details>
+<summary>Example: Structured-input workflow (declared schema + CLI flag validation)</summary>
+
+Declare an `inputs` array on `defineWorkflow` and the CLI materialises one `--<field>=<value>` flag per entry. Required fields, enum membership, and unknown-flag rejection are all validated before any tmux session is spawned. The interactive picker (`atomic workflow -a <agent>`) renders the same schema as a form.
+
+```ts
+// .atomic/workflows/gen-spec/claude/index.ts
+import { defineWorkflow } from "@bastani/atomic/workflows";
+
+export default defineWorkflow<"claude">({
+  name: "gen-spec",
+  description: "Convert a research doc into an execution spec",
+  inputs: [
+    {
+      name: "research_doc",
+      type: "string",
+      required: true,
+      description: "path to the research doc",
+      placeholder: "research/docs/2026-04-11-auth.md",
+    },
+    {
+      name: "focus",
+      type: "enum",
+      required: true,
+      description: "how aggressively to scope the spec",
+      values: ["minimal", "standard", "exhaustive"],
+      default: "standard",
+    },
+    {
+      name: "notes",
+      type: "text",
+      description: "extra guidance for the spec writer (optional)",
+    },
+  ],
+})
+  .run(async (ctx) => {
+    // Read each declared field by name.
+    const { research_doc, focus } = ctx.inputs;
+    const notes = ctx.inputs.notes ?? "";
+
+    await ctx.stage({ name: "write-spec" }, {}, {}, async (s) => {
+      await s.session.query(
+        `Read ${research_doc} and produce a ${focus} spec.` +
+          (notes ? `\n\nExtra guidance:\n${notes}` : ""),
+      );
+      s.save(s.sessionId);
+    });
+  })
+  .compile();
+```
+
+Run it either way:
+
+```bash
+# Named + flags (scriptable; CI-friendly)
+atomic workflow -n gen-spec -a claude \
+  --research_doc=research/docs/2026-04-11-auth.md \
+  --focus=standard
+
+# Picker (fuzzy-search the workflow list, then fill the form)
+atomic workflow -a claude
+```
+
+</details>
+
 **Key capabilities:**
 
 | Capability                   | Description                                                                          |
@@ -330,6 +404,8 @@ export default defineWorkflow<"claude">({
 | **Native TypeScript control flow** | Use `for`, `if/else`, `Promise.all()`, `try/catch` — no framework DSL needed |
 | **Session return values**    | Session callbacks can return data: `const h = await ctx.stage(...); h.result`      |
 | **Transcript passing**       | Access prior session output via handle (`s.transcript(handle)`) or name (`s.transcript("name")`) |
+| **Declared input schemas**   | Add an `inputs: [...]` array to `defineWorkflow()` and the CLI materialises `--<field>=<value>` flags with built-in validation (required fields, enum membership, unknown flags) |
+| **Interactive picker**       | `atomic workflow -a <agent>` launches a fuzzy-searchable picker that renders each workflow's input schema as a form — no flag-memorisation required |
 | **Nested sub-sessions**      | Call `s.stage()` inside a session callback to spawn child sessions — visible as nested nodes in the graph |
 | **Auto-inferred graph**      | Graph topology auto-inferred from `await`/`Promise.all` patterns — no annotations needed               |
 | **Provider-agnostic**        | Write raw SDK code for Claude, Copilot, or OpenCode inside each session callback     |
@@ -368,7 +444,7 @@ Use your workflow-creator skill to create a workflow that plans, implements, and
 
 | Property                | Type                      | Description                                                    |
 | ----------------------- | ------------------------- | -------------------------------------------------------------- |
-| `ctx.userPrompt`        | `string`                  | Original user prompt from the CLI invocation                   |
+| `ctx.inputs`            | `Record<string, string>`  | Structured inputs for this run. Free-form workflows store their positional prompt under `ctx.inputs.prompt`; workflows with a declared `inputs` schema store one key per declared field |
 | `ctx.agent`             | `AgentType`               | Which agent is running (`"claude"`, `"copilot"`, `"opencode"`) |
 | `ctx.stage(opts, clientOpts, sessionOpts, fn)` | `Promise<SessionHandle<T>>` | Spawn a session — returns handle with `name`, `id`, `result` |
 | `ctx.transcript(ref)`   | `Promise<Transcript>`     | Get a completed session's transcript (`{ path, content }`)     |
@@ -380,7 +456,7 @@ Use your workflow-creator skill to create a workflow that plans, implements, and
 | ----------------------- | ------------------------- | -------------------------------------------------------------- |
 | `s.client`              | `ProviderClient<A>`       | Pre-created SDK client (auto-managed by runtime)               |
 | `s.session`             | `ProviderSession<A>`      | Pre-created provider session (auto-managed by runtime)         |
-| `s.userPrompt`          | `string`                  | Original user prompt from the CLI invocation                   |
+| `s.inputs`              | `Record<string, string>`  | Same inputs record as `ctx.inputs`, forwarded into every stage so session callbacks can read values without closing over the outer `ctx` |
 | `s.agent`               | `AgentType`               | Which agent is running                                         |
 | `s.paneId`              | `string`                  | tmux pane ID for this session                                  |
 | `s.sessionId`           | `string`                  | Session UUID                                                   |
@@ -750,12 +826,35 @@ atomic chat -a claude --verbose              # Forward --verbose to claude
 
 #### `atomic workflow` Flags
 
-| Flag                 | Description                                                         |
-| -------------------- | ------------------------------------------------------------------- |
-| `-n, --name <name>`  | Workflow name (matches directory under `.atomic/workflows/<name>/`) |
-| `-a, --agent <name>` | Agent: `claude`, `opencode`, `copilot`                              |
-| `-l, --list`         | List available workflows                                            |
-| `[prompt...]`        | Prompt for the workflow                                             |
+| Flag                       | Description                                                         |
+| -------------------------- | ------------------------------------------------------------------- |
+| `-n, --name <name>`        | Workflow name (matches directory under `.atomic/workflows/<name>/`) |
+| `-a, --agent <name>`       | Agent: `claude`, `opencode`, `copilot`                              |
+| `-l, --list`               | List available workflows, grouped by source                         |
+| `--<field>=<value>`        | Structured input for workflows that declare an `inputs` schema (also accepts `--<field> <value>`) |
+| `[prompt...]`               | Positional prompt for free-form workflows (rejected on workflows with a declared schema) |
+
+The workflow command supports four invocation shapes:
+
+```bash
+# 1. List every workflow available to you, grouped by source
+atomic workflow -l
+
+# 2. Launch the interactive picker for an agent (no -n) — fuzzy-search
+#    the list, fill the form rendered from the workflow's declared inputs,
+#    and confirm with y/n
+atomic workflow -a claude
+
+# 3. Run a free-form workflow with a positional prompt
+atomic workflow -n ralph -a claude "build a REST API for user management"
+
+# 4. Run a structured-input workflow with one --<field> flag per declared input
+atomic workflow -n gen-spec -a claude \
+  --research_doc=research/docs/2026-04-11-auth.md \
+  --focus=standard
+```
+
+Workflows that declare an `inputs: WorkflowInput[]` schema get CLI flag validation for free — missing required fields and invalid enum values are rejected before any tmux session is spawned, with error messages that spell out the expected flag set. Workflows that don't declare a schema still accept a single positional prompt, which the runtime stores under `ctx.inputs.prompt`. **Builtin workflows (like `ralph`) are reserved names** — a local or global workflow with the same name will not shadow a builtin at resolution time.
 
 ### Atomic-Provided Skills (invokable from any agent chat)
 

package/dist/{chunk-mn870nrv.js → chunk-xkxndz5g.js}

@@ -1,5 +1,22 @@
 // @bun
 // src/sdk/define-workflow.ts
+function validateWorkflowInput(input, workflowName) {
+  if (!input.name || input.name.trim() === "") {
+    throw new Error(`Workflow "${workflowName}" has an input with an empty name.`);
+  }
+  if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(input.name)) {
+    throw new Error(`Workflow "${workflowName}" input "${input.name}" has an invalid ` + `name \u2014 must start with a letter and contain only letters, ` + `digits, underscores, and dashes (so it can be used as a ` + `\`--${input.name}\` CLI flag).`);
+  }
+  if (input.type === "enum") {
+    if (!Array.isArray(input.values) || input.values.length === 0) {
+      throw new Error(`Workflow "${workflowName}" input "${input.name}" is an enum but ` + `declares no \`values\`.`);
+    }
+    if (input.default !== undefined && !input.values.includes(input.default)) {
+      throw new Error(`Workflow "${workflowName}" input "${input.name}" has a default ` + `"${input.default}" that is not one of its declared values: ` + `${input.values.join(", ")}.`);
+    }
+  }
+}
+
 class WorkflowBuilder {
   __brand = "WorkflowBuilder";
   options;
@@ -22,10 +39,21 @@ class WorkflowBuilder {
       throw new Error(`Workflow "${this.options.name}" has no run callback. ` + `Add a .run(async (ctx) => { ... }) call before .compile().`);
     }
     const runFn = this.runFn;
+    const declaredInputs = this.options.inputs ?? [];
+    const seen = new Set;
+    for (const input of declaredInputs) {
+      validateWorkflowInput(input, this.options.name);
+      if (seen.has(input.name)) {
+        throw new Error(`Workflow "${this.options.name}" has duplicate input name "${input.name}".`);
+      }
+      seen.add(input.name);
+    }
+    const inputs = Object.freeze(declaredInputs.map((i) => Object.freeze({ ...i })));
     return {
       __brand: "WorkflowDefinition",
       name: this.options.name,
       description: this.options.description ?? "",
+      inputs,
       run: runFn
     };
   }
@@ -37,133 +65,6 @@ function defineWorkflow(options) {
   return new WorkflowBuilder(options);
 }
 
-// src/sdk/runtime/discovery.ts
-import { join } from "path";
-import { readdir, writeFile } from "fs/promises";
-import { existsSync, readdirSync } from "fs";
-import { homedir } from "os";
-import ignore from "ignore";
-function getLocalWorkflowsDir(projectRoot) {
-  return join(projectRoot, ".atomic", "workflows");
-}
-function getGlobalWorkflowsDir() {
-  return join(homedir(), ".atomic", "workflows");
-}
-var AGENTS = ["copilot", "opencode", "claude"];
-var AGENT_SET = new Set(AGENTS);
-var WORKFLOWS_GITIGNORE = [
-  "node_modules/",
-  "dist/",
-  "build/",
-  "coverage/",
-  ".cache/",
-  "*.log",
-  "*.tsbuildinfo",
-  ""
-].join(`
-`);
-async function loadWorkflowsGitignore(workflowsDir) {
-  const gitignorePath = join(workflowsDir, ".gitignore");
-  let content;
-  try {
-    content = await Bun.file(gitignorePath).text();
-  } catch {
-    await writeFile(gitignorePath, WORKFLOWS_GITIGNORE);
-    content = WORKFLOWS_GITIGNORE;
-  }
-  return ignore().add(content);
-}
-async function discoverFromBaseDir(baseDir, source, agentFilter) {
-  const workflows = [];
-  const agents = agentFilter ? [agentFilter] : AGENTS;
-  const agentNames = new Set(agents);
-  let workflowEntries;
-  try {
-    workflowEntries = await readdir(baseDir, { withFileTypes: true });
-  } catch {
-    return workflows;
-  }
-  const ig = await loadWorkflowsGitignore(baseDir);
-  for (const wfEntry of workflowEntries) {
-    if (!wfEntry.isDirectory())
-      continue;
-    if (wfEntry.name.startsWith("."))
-      continue;
-    if (AGENT_SET.has(wfEntry.name))
-      continue;
-    if (ig.ignores(wfEntry.name + "/"))
-      continue;
-    const workflowDir = join(baseDir, wfEntry.name);
-    let agentEntries;
-    try {
-      agentEntries = await readdir(workflowDir, { withFileTypes: true });
-    } catch {
-      continue;
-    }
-    for (const agentEntry of agentEntries) {
-      if (!agentEntry.isDirectory())
-        continue;
-      if (!agentNames.has(agentEntry.name))
-        continue;
-      const indexPath = join(workflowDir, agentEntry.name, "index.ts");
-      const file = Bun.file(indexPath);
-      if (await file.exists()) {
-        workflows.push({
-          name: wfEntry.name,
-          agent: agentEntry.name,
-          path: indexPath,
-          source
-        });
-      }
-    }
-  }
-  return workflows;
-}
-var BUILTIN_WORKFLOWS_DIR = join(Bun.fileURLToPath(new URL("../workflows/builtin", import.meta.url)));
-function discoverBuiltinWorkflows(agentFilter) {
-  const results = [];
-  const agents = agentFilter ? [agentFilter] : AGENTS;
-  let workflowNames;
-  try {
-    workflowNames = readdirSync(BUILTIN_WORKFLOWS_DIR, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
-  } catch {
-    return results;
-  }
-  for (const name of workflowNames) {
-    for (const agent of agents) {
-      const indexPath = join(BUILTIN_WORKFLOWS_DIR, name, agent, "index.ts");
-      if (existsSync(indexPath)) {
-        results.push({ name, agent, path: indexPath, source: "builtin" });
-      }
-    }
-  }
-  return results;
-}
-async function discoverWorkflows(projectRoot = process.cwd(), agentFilter) {
-  const localDir = getLocalWorkflowsDir(projectRoot);
-  const globalDir = getGlobalWorkflowsDir();
-  const builtinResults = discoverBuiltinWorkflows(agentFilter);
-  const [globalResults, localResults] = await Promise.all([
-    discoverFromBaseDir(globalDir, "global", agentFilter),
-    discoverFromBaseDir(localDir, "local", agentFilter)
-  ]);
-  const byKey = new Map;
-  for (const wf of builtinResults) {
-    byKey.set(`${wf.agent}/${wf.name}`, wf);
-  }
-  for (const wf of globalResults) {
-    byKey.set(`${wf.agent}/${wf.name}`, wf);
-  }
-  for (const wf of localResults) {
-    byKey.set(`${wf.agent}/${wf.name}`, wf);
-  }
-  return Array.from(byKey.values());
-}
-async function findWorkflow(name, agent, projectRoot = process.cwd()) {
-  const all = await discoverWorkflows(projectRoot, agent);
-  return all.find((w) => w.name === name) ?? null;
-}
-
 // src/sdk/providers/copilot.ts
 function validateCopilotWorkflow(source) {
   const warnings = [];
@@ -201,6 +102,9 @@ function validateOpenCodeWorkflow(source) {
 }
 
 // src/sdk/runtime/tmux.ts
+import { join } from "path";
+var SOCKET_NAME = "atomic";
+var CONFIG_PATH = join(import.meta.dir, "tmux.conf");
 var resolvedMuxBinary;
 function getMuxBinary() {
   if (resolvedMuxBinary !== undefined)
@@ -232,8 +136,9 @@ function tmuxRun(args) {
   if (!binary) {
     return { ok: false, stderr: "No terminal multiplexer (tmux/psmux) found on PATH" };
   }
+  const fullArgs = ["-f", CONFIG_PATH, "-L", SOCKET_NAME, ...args];
   const result = Bun.spawnSync({
-    cmd: [binary, ...args],
+    cmd: [binary, ...fullArgs],
     stdout: "pipe",
     stderr: "pipe"
   });
@@ -363,15 +268,8 @@ function killWindow(sessionName, windowName) {
   } catch {}
 }
 function sessionExists(sessionName) {
-  const binary = getMuxBinary();
-  if (!binary)
-    return false;
-  const result = Bun.spawnSync({
-    cmd: [binary, "has-session", "-t", sessionName],
-    stdout: "pipe",
-    stderr: "pipe"
-  });
-  return result.success;
+  const result = tmuxRun(["has-session", "-t", sessionName]);
+  return result.ok;
 }
 function attachSession(sessionName) {
   const binary = getMuxBinary();
@@ -379,7 +277,7 @@ function attachSession(sessionName) {
     throw new Error("No terminal multiplexer (tmux/psmux) found on PATH");
   }
   const proc = Bun.spawnSync({
-    cmd: [binary, "attach-session", "-t", sessionName],
+    cmd: [binary, "-f", CONFIG_PATH, "-L", SOCKET_NAME, "attach-session", "-t", sessionName],
     stdin: "inherit",
     stdout: "inherit",
     stderr: "pipe"
@@ -389,6 +287,13 @@ function attachSession(sessionName) {
     throw new Error(`Failed to attach to session: ${sessionName}${stderr ? ` (${stderr})` : ""}`);
   }
 }
+function spawnMuxAttach(sessionName) {
+  const binary = getMuxBinary();
+  if (!binary) {
+    throw new Error("No terminal multiplexer (tmux/psmux) found on PATH");
+  }
+  return Bun.spawn([binary, "-f", CONFIG_PATH, "-L", SOCKET_NAME, "attach-session", "-t", sessionName], { stdio: ["inherit", "inherit", "inherit"] });
+}
 function switchClient(sessionName) {
   tmuxExec(["switch-client", "-t", sessionName]);
 }
@@ -741,8 +646,156 @@ var WorkflowLoader;
   WorkflowLoader.loadWorkflow = loadWorkflow;
 })(WorkflowLoader ||= {});
 
+// src/sdk/runtime/discovery.ts
+import { join as join2 } from "path";
+import { readdir, writeFile } from "fs/promises";
+import { existsSync, readdirSync } from "fs";
+import { homedir } from "os";
+import ignore from "ignore";
+function getLocalWorkflowsDir(projectRoot) {
+  return join2(projectRoot, ".atomic", "workflows");
+}
+function getGlobalWorkflowsDir() {
+  return join2(homedir(), ".atomic", "workflows");
+}
+var AGENTS = ["copilot", "opencode", "claude"];
+var AGENT_SET = new Set(AGENTS);
+var WORKFLOWS_GITIGNORE = [
+  "node_modules/",
+  "dist/",
+  "build/",
+  "coverage/",
+  ".cache/",
+  "*.log",
+  "*.tsbuildinfo",
+  ""
+].join(`
+`);
+async function loadWorkflowsGitignore(workflowsDir) {
+  const gitignorePath = join2(workflowsDir, ".gitignore");
+  let content;
+  try {
+    content = await Bun.file(gitignorePath).text();
+  } catch {
+    await writeFile(gitignorePath, WORKFLOWS_GITIGNORE);
+    content = WORKFLOWS_GITIGNORE;
+  }
+  return ignore().add(content);
+}
+async function discoverFromBaseDir(baseDir, source, agentFilter) {
+  const workflows = [];
+  const agents = agentFilter ? [agentFilter] : AGENTS;
+  const agentNames = new Set(agents);
+  let workflowEntries;
+  try {
+    workflowEntries = await readdir(baseDir, { withFileTypes: true });
+  } catch {
+    return workflows;
+  }
+  const ig = await loadWorkflowsGitignore(baseDir);
+  for (const wfEntry of workflowEntries) {
+    if (!wfEntry.isDirectory())
+      continue;
+    if (wfEntry.name.startsWith("."))
+      continue;
+    if (AGENT_SET.has(wfEntry.name))
+      continue;
+    if (ig.ignores(wfEntry.name + "/"))
+      continue;
+    const workflowDir = join2(baseDir, wfEntry.name);
+    let agentEntries;
+    try {
+      agentEntries = await readdir(workflowDir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const agentEntry of agentEntries) {
+      if (!agentEntry.isDirectory())
+        continue;
+      if (!agentNames.has(agentEntry.name))
+        continue;
+      const indexPath = join2(workflowDir, agentEntry.name, "index.ts");
+      const file = Bun.file(indexPath);
+      if (await file.exists()) {
+        workflows.push({
+          name: wfEntry.name,
+          agent: agentEntry.name,
+          path: indexPath,
+          source
+        });
+      }
+    }
+  }
+  return workflows;
+}
+var BUILTIN_WORKFLOWS_DIR = join2(Bun.fileURLToPath(new URL("../workflows/builtin", import.meta.url)));
+function discoverBuiltinWorkflows(agentFilter) {
+  const results = [];
+  const agents = agentFilter ? [agentFilter] : AGENTS;
+  let workflowNames;
+  try {
+    workflowNames = readdirSync(BUILTIN_WORKFLOWS_DIR, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
+  } catch {
+    return results;
+  }
+  for (const name of workflowNames) {
+    for (const agent of agents) {
+      const indexPath = join2(BUILTIN_WORKFLOWS_DIR, name, agent, "index.ts");
+      if (existsSync(indexPath)) {
+        results.push({ name, agent, path: indexPath, source: "builtin" });
+      }
+    }
+  }
+  return results;
+}
+async function discoverWorkflows(projectRoot = process.cwd(), agentFilter, options = {}) {
+  const { merge = true } = options;
+  const localDir = getLocalWorkflowsDir(projectRoot);
+  const globalDir = getGlobalWorkflowsDir();
+  const allBuiltins = discoverBuiltinWorkflows();
+  const reservedNames = new Set(allBuiltins.map((w) => w.name));
+  const builtinResults = agentFilter ? allBuiltins.filter((w) => w.agent === agentFilter) : allBuiltins;
+  const [globalResults, localResults] = await Promise.all([
+    discoverFromBaseDir(globalDir, "global", agentFilter),
+    discoverFromBaseDir(localDir, "local", agentFilter)
+  ]);
+  const filteredGlobal = globalResults.filter((w) => !reservedNames.has(w.name));
+  const filteredLocal = localResults.filter((w) => !reservedNames.has(w.name));
+  if (!merge) {
+    return [...filteredGlobal, ...filteredLocal, ...builtinResults];
+  }
+  const byKey = new Map;
+  for (const wf of filteredGlobal) {
+    byKey.set(`${wf.agent}/${wf.name}`, wf);
+  }
+  for (const wf of filteredLocal) {
+    byKey.set(`${wf.agent}/${wf.name}`, wf);
+  }
+  for (const wf of builtinResults) {
+    byKey.set(`${wf.agent}/${wf.name}`, wf);
+  }
+  return Array.from(byKey.values());
+}
+async function findWorkflow(name, agent, projectRoot = process.cwd()) {
+  const all = await discoverWorkflows(projectRoot, agent);
+  return all.find((w) => w.name === name) ?? null;
+}
+async function loadWorkflowsMetadata(discovered) {
+  const results = await Promise.all(discovered.map(async (wf) => {
+    const loaded = await WorkflowLoader.loadWorkflow(wf);
+    if (!loaded.ok)
+      return null;
+    return {
+      ...wf,
+      description: loaded.value.definition.description,
+      inputs: loaded.value.definition.inputs
+    };
+  }));
+  return results.filter((r) => r !== null);
+}
+
 // src/sdk/runtime/executor.ts
-import { join as join2, resolve } from "path";
+import { join as join3, resolve } from "path";
 import { homedir as homedir2 } from "os";
 import { mkdir, writeFile as writeFile2, readFile } from "fs/promises";
 
@@ -915,7 +968,7 @@ function generateId() {
   return crypto.randomUUID().slice(0, 8);
 }
 function getSessionsBaseDir() {
-  return join2(homedir2(), ".atomic", "sessions");
+  return join3(homedir2(), ".atomic", "sessions");
 }
 async function ensureDir(dir) {
   await mkdir(dir, { recursive: true });
@@ -930,25 +983,26 @@ async function executeWorkflow(options) {
   const {
     definition,
     agent,
-    prompt,
+    inputs = {},
     workflowFile,
     projectRoot = process.cwd()
   } = options;
   const workflowRunId = generateId();
   const tmuxSessionName = `atomic-wf-${definition.name}-${workflowRunId}`;
-  const sessionsBaseDir = join2(getSessionsBaseDir(), workflowRunId);
+  const sessionsBaseDir = join3(getSessionsBaseDir(), workflowRunId);
   await ensureDir(sessionsBaseDir);
   const thisFile = resolve(import.meta.dir, "executor-entry.ts");
   const isWin = process.platform === "win32";
   const launcherExt = isWin ? "ps1" : "sh";
-  const launcherPath = join2(sessionsBaseDir, `orchestrator.${launcherExt}`);
-  const logPath = join2(sessionsBaseDir, "orchestrator.log");
+  const launcherPath = join3(sessionsBaseDir, `orchestrator.${launcherExt}`);
+  const logPath = join3(sessionsBaseDir, "orchestrator.log");
+  const inputsB64 = Buffer.from(JSON.stringify(inputs)).toString("base64");
   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_PROMPT = "${escPwsh(Buffer.from(prompt).toString("base64"))}"`,
+    `$env:ATOMIC_WF_INPUTS = "${escPwsh(inputsB64)}"`,
     `$env:ATOMIC_WF_FILE = "${escPwsh(workflowFile)}"`,
     `$env:ATOMIC_WF_CWD = "${escPwsh(projectRoot)}"`,
     `bun run "${escPwsh(thisFile)}" 2>"${escPwsh(logPath)}"`
@@ -959,24 +1013,29 @@ async function executeWorkflow(options) {
     `export ATOMIC_WF_ID="${escBash(workflowRunId)}"`,
     `export ATOMIC_WF_TMUX="${escBash(tmuxSessionName)}"`,
     `export ATOMIC_WF_AGENT="${escBash(agent)}"`,
-    `export ATOMIC_WF_PROMPT="${escBash(Buffer.from(prompt).toString("base64"))}"`,
+    `export ATOMIC_WF_INPUTS="${escBash(inputsB64)}"`,
     `export ATOMIC_WF_FILE="${escBash(workflowFile)}"`,
     `export ATOMIC_WF_CWD="${escBash(projectRoot)}"`,
     `bun run "${escBash(thisFile)}" 2>"${escBash(logPath)}"`
   ].join(`
 `);
   await writeFile2(launcherPath, launcherScript, { mode: 493 });
-  const shellCmd = isWin ? `pwsh -NoProfile -File "${escPwsh(launcherPath)}"` : `bash "${escBash(launcherPath)}"`;
-  createSession(tmuxSessionName, shellCmd, "orchestrator");
+  console.log(`[atomic] Session: ${tmuxSessionName} (FYI all atomic sessions run on tmux -L ${SOCKET_NAME})`);
   if (isInsideTmux()) {
-    switchClient(tmuxSessionName);
-  } else {
-    const muxBinary = getMuxBinary() ?? "tmux";
-    const attachProc = Bun.spawn([muxBinary, "attach-session", "-t", tmuxSessionName], {
-      stdio: ["inherit", "inherit", "inherit"]
+    const defaultShell = process.env.SHELL || (isWin ? "pwsh" : "sh");
+    createSession(tmuxSessionName, defaultShell, "orchestrator");
+    const launcherCmd = isWin ? ["pwsh", "-NoProfile", "-File", launcherPath] : ["bash", launcherPath];
+    const proc = Bun.spawn(launcherCmd, {
+      stdio: ["inherit", "inherit", "inherit"],
+      cwd: projectRoot
     });
+    await proc.exited;
+  } else {
+    const shellCmd = isWin ? `pwsh -NoProfile -File "${escPwsh(launcherPath)}"` : `bash "${escBash(launcherPath)}"`;
+    createSession(tmuxSessionName, shellCmd, "orchestrator");
+    const attachProc = spawnMuxAttach(tmuxSessionName);
     await attachProc.exited;
   }
 }
 
-export { WorkflowBuilder, defineWorkflow, AGENTS, WORKFLOWS_GITIGNORE, discoverWorkflows, findWorkflow, validateCopilotWorkflow, validateOpenCodeWorkflow, getMuxBinary, resetMuxBinaryCache, isTmuxInstalled, isInsideTmux, tmuxRun, createSession, createWindow, createPane, sendLiteralText, sendSpecialKey, sendKeysAndSubmit, capturePane, capturePaneVisible, capturePaneScrollback, killSession, killWindow, sessionExists, attachSession, switchClient, getCurrentSession, attachOrSwitch, selectWindow, normalizeTmuxCapture, normalizeTmuxLines, paneLooksReady, paneHasActiveTask, paneIsIdle, waitForPaneReady, attemptSubmitRounds, waitForOutput, clearClaudeSession, createClaudeSession, claudeQuery, validateClaudeWorkflow, WorkflowLoader, executeWorkflow };
+export { WorkflowBuilder, defineWorkflow, validateCopilotWorkflow, validateOpenCodeWorkflow, SOCKET_NAME, getMuxBinary, resetMuxBinaryCache, isTmuxInstalled, isInsideTmux, tmuxRun, createSession, createWindow, createPane, sendLiteralText, sendSpecialKey, sendKeysAndSubmit, capturePane, capturePaneVisible, capturePaneScrollback, killSession, killWindow, sessionExists, attachSession, spawnMuxAttach, switchClient, getCurrentSession, attachOrSwitch, selectWindow, normalizeTmuxCapture, normalizeTmuxLines, paneLooksReady, paneHasActiveTask, paneIsIdle, waitForPaneReady, attemptSubmitRounds, waitForOutput, clearClaudeSession, createClaudeSession, claudeQuery, validateClaudeWorkflow, WorkflowLoader, AGENTS, WORKFLOWS_GITIGNORE, discoverWorkflows, findWorkflow, loadWorkflowsMetadata, executeWorkflow };