@bastani/atomic 0.6.5 → 0.6.6-1

package/.agents/skills/workflow-creator/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: workflow-creator
 description: Create AND run Atomic CLI workflows (`defineWorkflow().run().compile()` with `ctx.stage()`) across Claude, Copilot, and OpenCode SDKs. Use for **authoring** when the user wants to build, edit, debug, or design agent pipelines — multi-stage automations, review/fix loops, parallel fan-out, headless/background stages, `defineWorkflow`, `ctx.stage`, `ctx.inputs`, declared `WorkflowInput` schemas, `runWorkflow`, `createRegistry`, `listWorkflows`, the SDK's metadata accessors (`getName`, `getInputSchema`, `getAgent`), `validateInputs`, the interactive workflow picker (`WorkflowPicker` from `@bastani/atomic/workflows/components`), single or multi-workflow composition roots. Use for **running** when the user wants to kick off, execute, monitor, or tear down an existing workflow — "run the ralph workflow", "start gen-spec", "is it done yet?", "what's the status?", "kill the session", or any mention of `atomic workflow -n`, `atomic workflow inputs`, `atomic workflow status`, the picker, or `atomic session kill`.
+metadata:
+  provider: atomic
 ---
 
 # Workflow Creator
@@ -18,20 +20,20 @@ Two user journeys live in this skill:
 
 Load references on demand. **Only `getting-started.md` is always-load.** Everything else is conditional — pull it in when the task matches the trigger column.
 
-| File | Load when |
-|---|---|
-| `getting-started.md` | **Always** — quick-start examples for all 3 SDKs, SDK exports, `SessionContext` field reference |
-| `agent-setup-recipe.md` | When the user is starting from zero (empty terminal, no project, "set me up", "how do I get started"). Deterministic env-detect → install → scaffold → smoke-test playbook with typed-error recovery hints |
-| `failure-modes.md` | Before shipping any multi-session workflow. 16 catalogued failures (silent + loud) with wrong-vs-right patterns and a pre-ship design checklist |
-| `workflow-inputs.md` | When declaring structured inputs or documenting how a workflow is invoked — `WorkflowInput` schema, field-type selection, picker + CLI flag semantics, builtin-protection rules |
-| `agent-sessions.md` | When writing SDK calls — `s.session.query()` (Claude), `s.session.send()` (Copilot), `s.client.session.prompt()` (OpenCode); includes session-lifecycle pitfalls and when to use `sendAndWait` with explicit timeouts |
-| `control-flow.md` | When using loops, conditionals, parallel execution (`Promise.all`), headless fan-out, or review/fix patterns |
-| `state-and-data-flow.md` | When passing data between sessions — `s.save()`, `s.transcript()`, `s.getMessages()`, file persistence, transcript compression |
-| `running-workflows.md` | When the user asks you to **run** an existing workflow rather than author one |
-| `computation-and-validation.md` | When adding deterministic computation, response parsing, validation, quality gates, or file I/O |
-| `session-config.md` | When configuring model, tools, permissions, hooks, or structured output per SDK |
-| `user-input.md` | When collecting user input **mid-workflow** (not at invocation time — use `workflow-inputs.md` for that) |
-| `registry-and-validation.md` | When setting up `createRegistry()` and iterating it via `listWorkflows`, understanding key scheme, validate-on-register rules, and same-name collision detection (only relevant for the multi-workflow cli) |
+| File                            | Load when                                                                                                                                                                                                             |
+| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `getting-started.md`            | **Always** — quick-start examples for all 3 SDKs, SDK exports, `SessionContext` field reference                                                                                                                       |
+| `agent-setup-recipe.md`         | When the user is starting from zero (empty terminal, no project, "set me up", "how do I get started"). Deterministic env-detect → install → scaffold → smoke-test playbook with typed-error recovery hints            |
+| `failure-modes.md`              | Before shipping any multi-session workflow. 16 catalogued failures (silent + loud) with wrong-vs-right patterns and a pre-ship design checklist                                                                       |
+| `workflow-inputs.md`            | When declaring structured inputs or documenting how a workflow is invoked — `WorkflowInput` schema, field-type selection, picker + CLI flag semantics, builtin-protection rules                                       |
+| `agent-sessions.md`             | When writing SDK calls — `s.session.query()` (Claude), `s.session.send()` (Copilot), `s.client.session.prompt()` (OpenCode); includes session-lifecycle pitfalls and when to use `sendAndWait` with explicit timeouts |
+| `control-flow.md`               | When using loops, conditionals, parallel execution (`Promise.all`), headless fan-out, or review/fix patterns                                                                                                          |
+| `state-and-data-flow.md`        | When passing data between sessions — `s.save()`, `s.transcript()`, `s.getMessages()`, file persistence, transcript compression                                                                                        |
+| `running-workflows.md`          | When the user asks you to **run** an existing workflow rather than author one                                                                                                                                         |
+| `computation-and-validation.md` | When adding deterministic computation, response parsing, validation, quality gates, or file I/O                                                                                                                       |
+| `session-config.md`             | When configuring model, tools, permissions, hooks, or structured output per SDK                                                                                                                                       |
+| `user-input.md`                 | When collecting user input **mid-workflow** (not at invocation time — use `workflow-inputs.md` for that)                                                                                                              |
+| `registry-and-validation.md`    | When setting up `createRegistry()` and iterating it via `listWorkflows`, understanding key scheme, validate-on-register rules, and same-name collision detection (only relevant for the multi-workflow cli)           |
 
 ## Scaffold a new workflow from scratch
 
@@ -102,22 +104,22 @@ budgets). Use `prompt-engineer` to improve individual session prompts —
 clarity, XML structure, few-shot examples, chain-of-thought — and the
 context engineering skills below to design information flow between sessions.
 
-| Design Concern | Skill | Trigger |
-|---|---|---|
-| Prompt clarity and structure | `prompt-engineer` | Every workflow — clear instructions, XML tags, examples, chain-of-thought |
-| Session prompt structure | `context-fundamentals` | Every workflow — token budgeting, prompt positioning, progressive disclosure |
-| Context failure prevention | `context-degradation` | Long conversations, accumulated state, multi-turn loops |
-| Transcript compression | `context-compression` | Passing large transcripts between sessions |
-| Multi-session architecture | `multi-agent-patterns` | Coordination topology, handoff protocols, error propagation |
-| Cross-run persistence | `memory-systems` | Retaining knowledge across separate executions |
-| Custom tools and capabilities | `tool-design` | Sessions exposing custom tools |
-| File-based coordination | `filesystem-context` | Sessions sharing state via files |
-| Remote execution | `hosted-agents` | Sandboxed or remote environments |
-| Token efficiency | `context-optimization` | Compaction triggers, observation masking, cache-friendly ordering |
-| Quality gates | `evaluation` | Review loops or quality checkpoints |
-| LLM-as-judge review | `advanced-evaluation` | Automated review sessions judging other sessions' output |
-| Task-model fit | `project-development` | Validating whether a task is viable for agent automation |
-| Deliberative reasoning | `bdi-mental-states` | Explainable reasoning chains or formal cognitive models |
+| Design Concern                | Skill                  | Trigger                                                                      |
+| ----------------------------- | ---------------------- | ---------------------------------------------------------------------------- |
+| Prompt clarity and structure  | `prompt-engineer`      | Every workflow — clear instructions, XML tags, examples, chain-of-thought    |
+| Session prompt structure      | `context-fundamentals` | Every workflow — token budgeting, prompt positioning, progressive disclosure |
+| Context failure prevention    | `context-degradation`  | Long conversations, accumulated state, multi-turn loops                      |
+| Transcript compression        | `context-compression`  | Passing large transcripts between sessions                                   |
+| Multi-session architecture    | `multi-agent-patterns` | Coordination topology, handoff protocols, error propagation                  |
+| Cross-run persistence         | `memory-systems`       | Retaining knowledge across separate executions                               |
+| Custom tools and capabilities | `tool-design`          | Sessions exposing custom tools                                               |
+| File-based coordination       | `filesystem-context`   | Sessions sharing state via files                                             |
+| Remote execution              | `hosted-agents`        | Sandboxed or remote environments                                             |
+| Token efficiency              | `context-optimization` | Compaction triggers, observation masking, cache-friendly ordering            |
+| Quality gates                 | `evaluation`           | Review loops or quality checkpoints                                          |
+| LLM-as-judge review           | `advanced-evaluation`  | Automated review sessions judging other sessions' output                     |
+| Task-model fit                | `project-development`  | Validating whether a task is viable for agent automation                     |
+| Deliberative reasoning        | `bdi-mental-states`    | Explainable reasoning chains or formal cognitive models                      |
 
 ## How Workflows Work
 
@@ -290,18 +292,18 @@ The dev's CLI is **never** re-execed. The SDK ships an internal orchestrator ent
 atomic workflow -n <name> -a <agent> [inputs...]
 ```
 
-Surface | Command | When
----|---|---
-Named, with prompt | `… -n hello -a claude "fix the bug"` | Requires workflow to declare a `prompt` input
-Named, structured | `… -n gen-spec -a claude --research_doc=notes.md` | Structured inputs via `--<field>` flags
-Interactive picker | `atomic workflow -a claude` | Discovery — fuzzy list + form; this is the intentional no-`-n` path
-List (atomic builtins) | `atomic workflow list`, `atomic workflow list -a <agent>` | Browse registered builtins, optionally filtered
-List (user cli) | Iterate `listWorkflows(registry)` and add a `list` Commander subcommand yourself | No built-in `--list` flag
-List (single-workflow) | Not applicable — the file *is* the workflow
-Inspect inputs | `atomic workflow inputs <name> -a claude` | Print input schema as JSON
-Status (one or all) | `atomic workflow status [<session-id>]` | Query state — `in_progress`, `error`, `completed`, `needs_review`
-Kill non-interactively | `atomic session kill <id> -y` | Tear down without confirmation prompt — `-y` is mandatory for agents
-Detached (background) | `… -d` / `… --detach` | Runs without attaching; reattach with `atomic workflow session connect <name>`
+| Surface                | Command                                                                          | When                                                                           |
+| ---------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| Named, with prompt     | `… -n hello -a claude "fix the bug"`                                             | Requires workflow to declare a `prompt` input                                  |
+| Named, structured      | `… -n gen-spec -a claude --research_doc=notes.md`                                | Structured inputs via `--<field>` flags                                        |
+| Interactive picker     | `atomic workflow -a claude`                                                      | Discovery — fuzzy list + form; this is the intentional no-`-n` path            |
+| List (atomic builtins) | `atomic workflow list`, `atomic workflow list -a <agent>`                        | Browse registered builtins, optionally filtered                                |
+| List (user cli)        | Iterate `listWorkflows(registry)` and add a `list` Commander subcommand yourself | No built-in `--list` flag                                                      |
+| List (single-workflow) | Not applicable — the file *is* the workflow                                      |
+| Inspect inputs         | `atomic workflow inputs <name> -a claude`                                        | Print input schema as JSON                                                     |
+| Status (one or all)    | `atomic workflow status [<session-id>]`                                          | Query state — `in_progress`, `error`, `completed`, `needs_review`              |
+| Kill non-interactively | `atomic session kill <id> -y`                                                    | Tear down without confirmation prompt — `-y` is mandatory for agents           |
+| Detached (background)  | `… -d` / `… --detach`                                                            | Runs without attaching; reattach with `atomic workflow session connect <name>` |
 
 Any of the named shapes above (positional or structured) accepts
 `-d` / `--detach` to run without attaching. Use it when you're automating
@@ -347,21 +349,22 @@ Enforced by the builder, loader, and runtime:
 
 Every workflow pattern maps directly to TypeScript code:
 
-| Workflow Concept | Programmatic Pattern |
-|---|---|
-| Agent session (send prompt, get response) | `ctx.stage({ name }, {}, {}, async (s) => { /* use s.client, s.session */ })` — **must** include an LLM call (Rule 9) |
-| Background (headless) session | `ctx.stage({ name, headless: true }, {}, {}, async (s) => { /* same API */ })` — invisible in graph, tracked by background counter |
-| Sequential execution | `await ctx.stage(...)` followed by `await ctx.stage(...)` |
-| Parallel execution | `Promise.all([ctx.stage(...), ctx.stage(...)])` |
-| Parallel background tasks | `Promise.all([ctx.stage({ name: "a", headless: true }, ...), ctx.stage({ name: "b", headless: true }, ...)])` |
-| Conditional branching | `if (...) { await ctx.stage({ name: "fix" }, {}, {}, ...) }` |
-| Bounded loops with visible graph nodes | `for (let i = 1; i <= N; i++) { await ctx.stage({ name: \`step-\${i}\` }, {}, {}, ...) }` |
-| Return data from session | `const h = await ctx.stage(opts, {}, {}, async (s) => { return value; }); h.result` |
-| Data flow between sessions | `s.save()` to persist → `s.transcript(handle)` or `s.transcript("name")` to retrieve |
-| Pure deterministic computation (no LLM call) | Plain TypeScript at the top level of `.run()`. **Never** a standalone stage — see Rule 9 and F22. |
-| Deterministic work tied to an LLM call | Inside the same stage callback, before/after the query. E.g. `s.session.query(...)` → parse → validate → `s.save(parsed)`. |
-| Subagent orchestration | Claude: `--agent` via `chatFlags` (interactive) or `agent` SDK option (headless); Copilot: `{ agent: "name" }` in sessionOpts; OpenCode: `agent` param in `s.client.session.prompt()` |
-| Per-session configuration | Pass `clientOpts` (2nd arg) and `sessionOpts` (3rd arg) to `ctx.stage()` |
+| Workflow Concept                             | Programmatic Pattern                                                                                                                                                                  |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Agent session (send prompt, get response)    | `ctx.stage({ name }, {}, {}, async (s) => { /* use s.client, s.session */ })` — **must** include an LLM call (Rule 9)                                                                 |
+| Background (headless) session                | `ctx.stage({ name, headless: true }, {}, {}, async (s) => { /* same API */ })` — invisible in graph, tracked by background counter                                                    |
+| Sequential execution                         | `await ctx.stage(...)` followed by `await ctx.stage(...)`                                                                                                                             |
+| Parallel execution                           | `Promise.all([ctx.stage(...), ctx.stage(...)])`                                                                                                                                       |
+| Parallel background tasks                    | `Promise.all([ctx.stage({ name: "a", headless: true }, ...), ctx.stage({ name: "b", headless: true }, ...)])`                                                                         |
+| Conditional branching                        | `if (...) { await ctx.stage({ name: "fix" }, {}, {}, ...) }`                                                                                                                          |
+| Bounded loops with visible graph nodes       | `for (let i = 1; i <= N; i++) { await ctx.stage({ name: \`step-\${i}\` }, {}, {}, ...) }`                                                                                             |
+| Return data from session                     | `const h = await ctx.stage(opts, {}, {}, async (s) => { return value; }); h.result`                                                                                                   |
+| Data flow between sessions                   | `s.save()` to persist → `s.transcript(handle)` or `s.transcript("name")` to retrieve                                                                                                  |
+| Pure deterministic computation (no LLM call) | Plain TypeScript at the top level of `.run()`. **Never** a standalone stage — see Rule 9 and F22.                                                                                     |
+| Deterministic work tied to an LLM call       | Inside the same stage callback, before/after the query. E.g. `s.session.query(...)` → parse → validate → `s.save(parsed)`.                                                            |
+| Subagent orchestration                       | Claude: `--agent` via `chatFlags` (interactive) or `agent` SDK option (headless); Copilot: `{ agent: "name" }` in sessionOpts; OpenCode: `agent` param in `s.client.session.prompt()` |
+| Per-session configuration                    | Pass `clientOpts` (2nd arg) and `sessionOpts` (3rd arg) to `ctx.stage()`                                                                                                              |
+| Per-session permission posture (autonomous)  | Claude: `chatFlags: ["--dangerously-skip-permissions"]` (interactive) or `permissionMode: "bypassPermissions"` on `s.session.query()` (headless). Copilot: `onPermissionRequest: approveAll` (default — auto-applied). OpenCode: pass `permission: [{ permission: "*", pattern: "*", action: "allow" }]` in `sessionOpts` on **every stage** so the posture is visible in the workflow source, not buried in runtime defaults. See `references/session-config.md` §"OpenCode session permission ruleset". |
 
 ### When to use a stage vs. plain TypeScript
 
@@ -409,17 +412,17 @@ transcript compression), and `references/computation-and-validation.md`
 
 Map the user's intent to sessions and patterns:
 
-| Question | Maps to |
-|----------|---------|
-| What are the distinct **LLM interactions**? | Each LLM conversation → one `ctx.stage()` call (Rule 9) |
-| Can any LLM calls run in parallel? | `Promise.all([ctx.stage(...), ...])` |
-| Should any parallel LLM calls run in the background? | `ctx.stage({ name, headless: true }, ...)` — invisible in graph, ideal for data-gathering |
+| Question                                                 | Maps to                                                                                                                                                       |
+| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| What are the distinct **LLM interactions**?              | Each LLM conversation → one `ctx.stage()` call (Rule 9)                                                                                                       |
+| Can any LLM calls run in parallel?                       | `Promise.all([ctx.stage(...), ...])`                                                                                                                          |
+| Should any parallel LLM calls run in the background?     | `ctx.stage({ name, headless: true }, ...)` — invisible in graph, ideal for data-gathering                                                                     |
 | Does any step need **pure deterministic code** (no LLM)? | Plain TypeScript at the top of `.run()` — **not** a dedicated stage. Bundle it inside the nearest stage callback if it's directly tied to that stage's query. |
-| Do any steps need to repeat? | `for`/`while` loop with `ctx.stage()` inside |
-| Are there conditional paths? | `if`/`else` wrapping `ctx.stage()` calls |
-| What data flows between steps? | `s.save()` → `s.transcript(handle)` / `s.getMessages(handle)` |
-| Does the workflow need user input? | SDK-specific user input APIs (see `references/user-input.md`) |
-| Do any steps need a specific model? | SDK-specific session config (see `references/session-config.md`) |
+| Do any steps need to repeat?                             | `for`/`while` loop with `ctx.stage()` inside                                                                                                                  |
+| Are there conditional paths?                             | `if`/`else` wrapping `ctx.stage()` calls                                                                                                                      |
+| What data flows between steps?                           | `s.save()` → `s.transcript(handle)` / `s.getMessages(handle)`                                                                                                 |
+| Does the workflow need user input?                       | SDK-specific user input APIs (see `references/user-input.md`)                                                                                                 |
+| Do any steps need a specific model?                      | SDK-specific session config (see `references/session-config.md`)                                                                                              |
 
 Then walk the **Design Advisory Skills** table above (§"Design Advisory
 Skills") — for each row whose trigger applies to your workflow, pull that
@@ -433,11 +436,11 @@ Pass the agent as a runtime argument to `.for()` on the builder — this
 narrows all context types and gives correct `s.client`/`s.session` types.
 Call `.for()` **before** `.run()`:
 
-| Agent | Builder Chain | Primary Session API |
-|-------|---------------|---------------------|
-| Claude | `defineWorkflow({...}).for("claude")` | `s.session.query(prompt)` — sends prompt to the Claude TUI pane |
-| Copilot | `defineWorkflow({...}).for("copilot")` | `s.session.send({ prompt })` — the runtime wraps `send` to block until `session.idle` with no timeout (see `failure-modes.md` §F10); do not use `sendAndWait` in Atomic workflows |
-| OpenCode | `defineWorkflow({...}).for("opencode")` | `s.client.session.prompt({ sessionID: s.session.id, parts: [...] })` |
+| Agent    | Builder Chain                           | Primary Session API                                                                                                                                                               |
+| -------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Claude   | `defineWorkflow({...}).for("claude")`   | `s.session.query(prompt)` — sends prompt to the Claude TUI pane                                                                                                                   |
+| Copilot  | `defineWorkflow({...}).for("copilot")`  | `s.session.send({ prompt })` — the runtime wraps `send` to block until `session.idle` with no timeout (see `failure-modes.md` §F10); do not use `sendAndWait` in Atomic workflows |
+| OpenCode | `defineWorkflow({...}).for("opencode")` | `s.client.session.prompt({ sessionID: s.session.id, parts: [...] })`                                                                                                              |
 
 The runtime manages client/session lifecycle automatically. For native SDK
 types and advanced APIs, import directly from the provider packages

package/.agents/skills/workflow-creator/references/session-config.md

@@ -289,18 +289,65 @@ await ctx.stage({ name: "..." }, {
 ### Session options (`sessionOpts` — 3rd arg to `ctx.stage()`)
 
 These are forwarded to `client.session.create()`. Use them to set a title,
-parentID, or workspaceID for the session:
+parentID, workspaceID, or — most importantly — a `permission` ruleset for
+the session:
 
 ```ts
 await ctx.stage({ name: "..." }, {}, {
   title: "Feature implementation",
   parentID: "parent-session-id",
   workspaceID: "workspace-id",
+  // Recommended default — autonomous stages should approve every tool call.
+  // Mirrors Copilot's `approveAll` and Claude's `bypassPermissions`. Omit
+  // (or narrow) only when a stage must gate specific tools behind HIL.
+  permission: [{ permission: "*", pattern: "*", action: "allow" }],
 }, async (s) => {
   // s.session is the created OpencodeSession, s.session.id is the session ID
 });
 ```
 
+### OpenCode session permission ruleset (recommended default)
+
+Every opencode stage in the builtin and example workflows passes
+`permission: [{ permission: "*", pattern: "*", action: "allow" }]`
+explicitly. **Do the same for new opencode workflows.** This is OpenCode's
+equivalent of:
+
+| Agent    | Autonomous-default knob                                         |
+| -------- | --------------------------------------------------------------- |
+| Claude   | `chatFlags: ["--dangerously-skip-permissions"]` (interactive) / `permissionMode: "bypassPermissions"` (headless `s.session.query()` options) |
+| Copilot  | `onPermissionRequest: approveAll` (defaults on automatically)   |
+| OpenCode | `permission: [{ permission: "*", pattern: "*", action: "allow" }]` (default in the runtime; **set explicitly so workflow authors can see and override per stage**) |
+
+Why explicit:
+
+- The runtime applies the same allow-all ruleset as a fallback, but
+  **workflow authors should see the permission decision in the workflow
+  source** — not learn it by reading the executor.
+- A workflow author who needs a stricter ruleset (e.g. deny `bash` on a
+  production machine, ask before `edit` on a sensitive directory) can
+  override the field per stage. The runtime only applies the default when
+  `permission` is `undefined` in the session opts.
+- Mirroring the explicit pattern keeps the three SDK variants visually
+  symmetric — every stage in every agent shows its permission posture in
+  the same place (3rd arg to `ctx.stage()`).
+
+To narrow per stage, pass any other ruleset shape:
+
+```ts
+// Deny shell commands in this stage; ask for everything else.
+await ctx.stage({ name: "review" }, {}, {
+  title: "review",
+  permission: [
+    { permission: "bash", pattern: "*", action: "deny" },
+    { permission: "*", pattern: "*", action: "ask" },
+  ],
+}, async (s) => { /* ... */ });
+```
+
+The full type lives in `@opencode-ai/sdk/v2` as `PermissionRuleset`
+(`Array<{ permission: string; pattern?: string; action: "allow" | "deny" | "ask" }>`).
+
 ### Session prompting
 
 Use `s.client` and `s.session.id` inside the callback:

package/.agents/skills/xlsx/SKILL.md

@@ -2,6 +2,8 @@
 name: xlsx
 description: "Use this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like \"the xlsx in my downloads\") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved."
 license: Proprietary. LICENSE.txt has complete terms
+metadata:
+  provider: atomic
 ---
 
 # Requirements for Outputs

package/.opencode/opencode.json

@@ -1,6 +1,5 @@
 {
   "$schema": "https://opencode.ai/config.json",
-  "permission": "allow",
   "mcp": {
     "github": {
       "type": "remote",
@@ -17,5 +16,10 @@
       ],
       "enabled": false
     }
-  }
+  },
+  "instructions": [
+    "/home/alilavaee/.atomic/AGENTS.md",
+    "/home/vscode/.atomic/AGENTS.md"
+  ],
+  "permission": "allow"
 }

package/README.md

@@ -128,6 +128,7 @@ Minimal example (Claude + Rust):
     "ghcr.io/devcontainers/features/github-cli:1": {}
   },
   "remoteEnv": {
+    "GH_TOKEN": "${localEnv:GH_TOKEN}",
     "ANTHROPIC_API_KEY": "${localEnv:ANTHROPIC_API_KEY}"
   }
 }
@@ -302,15 +303,15 @@ Detached mode is what you want for scripted / CI automation and long-running tas
 
 Atomic ships **two** things that share one workflow runtime. You can use either on its own or both together:
 
-|                       | Atomic CLI                                                                                                                                                                                                                               | Atomic SDK                                                                                                                                                                                                                                                      |
-| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **What it is**        | Global `atomic` binary                                                                                                                                                                                                                   | `@bastani/atomic/workflows` TypeScript library                                                                                                                                                                                                                  |
-| **Install**           | `bun install -g @bastani/atomic` (or `install.sh` / `install.ps1`)                                                                                                                                                                       | `bun add @bastani/atomic` inside your project                                                                                                                                                                                                                   |
-| **Entrypoint**        | `atomic <command>`                                                                                                                                                                                                                       | `bun run src/<agent>-worker.ts`                                                                                                                                                                                                                                 |
-| **Code required?**    | No — everything is pre-built. You can also ask the agent inside `atomic chat` to use the `workflow-creator` skill, decide when a complex task needs its own workflow, and build/run that workflow on the fly.                            | No to start — describe the workflow in natural language and use the `workflow-creator` skill to generate it. Then refine it in natural language or edit the TypeScript workflow and composition root directly, with full visibility into exactly what will run. |
+|                       | Atomic CLI                                                                                                                                                                                                                               | Atomic SDK                                                                                                                                                                                                                                                                                                                                                                            |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **What it is**        | Global `atomic` binary                                                                                                                                                                                                                   | `@bastani/atomic/workflows` TypeScript library                                                                                                                                                                                                                                                                                                                                        |
+| **Install**           | `bun install -g @bastani/atomic` (or `install.sh` / `install.ps1`)                                                                                                                                                                       | `bun add @bastani/atomic` inside your project                                                                                                                                                                                                                                                                                                                                         |
+| **Entrypoint**        | `atomic <command>`                                                                                                                                                                                                                       | `bun run src/<agent>-worker.ts`                                                                                                                                                                                                                                                                                                                                                       |
+| **Code required?**    | No — everything is pre-built. You can also ask the agent inside `atomic chat` to use the `workflow-creator` skill, decide when a complex task needs its own workflow, and build/run that workflow on the fly.                            | No to start — describe the workflow in natural language and use the `workflow-creator` skill to generate it. Then refine it in natural language or edit the TypeScript workflow and composition root directly, with full visibility into exactly what will run.                                                                                                                       |
 | **What you get**      | `atomic chat` (agent REPL), three autonomous built-in workflows (`ralph`, `deep-research-codebase`, `open-claude-design`), session management, the live workflow panel, Atomic skills (`/init`, `/research-codebase`, `/create-spec`, …) | `defineWorkflow`, `createRegistry`, `runWorkflow`, metadata accessors (`getName`, `getInputSchema`, …), session primitives (`listSessions`, `getSessionStatus`, `attachSession` / `detachSession`, `nextWindow` / `previousWindow` / `gotoOrchestrator`), typed errors (`MissingDependencyError`, `SessionNotFoundError`, …), `ctx.stage`, `s.save` / `s.transcript`, headless stages |
-| **When to reach for** | You want autonomous execution of a standard pattern out of the box, interactive chat with your agent's full toolset, or a CLI agent that can create a purpose-built workflow before doing complex work.                                  | You want to control the outer loop yourself — review flows, deployment gates, custom research pipelines — with full visibility into the TypeScript your team will run identically.                                                                              |
-| **Read next**         | [Quick Start](#quick-start) (steps 1–3)                                                                                                                                                                                                  | [Quick Start step 4](#4-build-your-own-workflow--sdk) and [Building your own atomic-powered app](#building-your-own-atomic-powered-app)                                                                                                                         |
+| **When to reach for** | You want autonomous execution of a standard pattern out of the box, interactive chat with your agent's full toolset, or a CLI agent that can create a purpose-built workflow before doing complex work.                                  | You want to control the outer loop yourself — review flows, deployment gates, custom research pipelines — with full visibility into the TypeScript your team will run identically.                                                                                                                                                                                                    |
+| **Read next**         | [Quick Start](#quick-start) (steps 1–3)                                                                                                                                                                                                  | [Quick Start step 4](#4-build-your-own-workflow--sdk) and [Building your own atomic-powered app](#building-your-own-atomic-powered-app)                                                                                                                                                                                                                                               |
 
 Both surfaces call the same runtime underneath (tmux/psmux session graph, provider SDKs, detach/reattach) — they're two entry points, not two products. Neither depends on the other: you can `bun add @bastani/atomic` in a project without ever installing the global binary, and you can use `atomic chat` and the built-in workflows without writing any TypeScript.
 
@@ -368,14 +369,14 @@ These are workflows you'd author with `defineWorkflow` and run from your own `sr
       - [`atomic completions` — Shell Completions](#atomic-completions--shell-completions)
     - [Atomic-Provided Skills (invokable from any agent chat)](#atomic-provided-skills-invokable-from-any-agent-chat)
   - [Building your own atomic-powered app](#building-your-own-atomic-powered-app)
-    - [One factory, three input shapes](#one-factory-three-input-shapes)
-    - [One method: `run()`](#one-method-run)
+    - [Primitives, not a wrapper](#primitives-not-a-wrapper)
+    - [Programmatic invocation](#programmatic-invocation)
     - [Embedding under a parent CLI — `runWorkflow` inside any Commander tree](#embedding-under-a-parent-cli--runworkflow-inside-any-commander-tree)
-    - [`entry` — for bundled apps and tests](#entry--for-bundled-apps-and-tests)
+    - [`WorkflowPicker` component](#workflowpicker-component)
     - [Registry rules](#registry-rules)
     - [Input precedence](#input-precedence)
     - [Builtin workflows via the `atomic` CLI](#builtin-workflows-via-the-atomic-cli)
-    - [Migration from 0.x (directory-scanning) to current](#migration-from-0x-directory-scanning-to-current)
+    - [Migration from 0.x (directory-scanning) and the `createWorkflowCli` wrapper](#migration-from-0x-directory-scanning-and-the-createworkflowcli-wrapper)
   - [Configuration](#configuration)
     - [`.atomic/settings.json`](#atomicsettingsjson)
     - [Agent-Specific Files](#agent-specific-files)
@@ -437,19 +438,19 @@ The [`examples/`](./examples) directory contains small, complete user apps you c
 
 **Design principle — when does `-a/--agent` belong on your CLI?** Each agent-scoped worker file imports a single workflow pinned to one agent (`import workflow from "./claude/index.ts"`), so there's nothing to disambiguate — no `-a` flag. Only reach for `-a/--agent` when one CLI dispatches across workflows that exist in multiple agent variants — e.g. a `cli.ts` that registers `hello` for claude *and* copilot. The atomic CLI itself uses `-a` for exactly that reason: its builtin registry has cross-agent variants of `ralph`, `deep-research-codebase`, and `open-claude-design`.
 
-| Example                         | What it demonstrates                                                                                                                                                                                                                                         |
-| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `hello-world`                   | Minimal single-session workflow with structured inputs (greeting, style, optional notes)                                                                                                                                                                     |
-| `sequential-describe-summarize` | Two stages passing data via `s.save()` → `s.transcript(handle)` — the canonical handoff pattern                                                                                                                                                              |
-| `parallel-hello-world`          | `Promise.all()` fan-out and transcript merge                                                                                                                                                                                                                 |
-| `headless-test`                 | Visible seed → 3 parallel headless stages → visible merge → headless verdict                                                                                                                                                                                 |
-| `hil-favorite-color`            | Human-in-the-loop prompt mid-workflow                                                                                                                                                                                                                        |
-| `hil-favorite-color-headless`   | HIL pause inside a headless stage                                                                                                                                                                                                                            |
-| `structured-output-demo`        | Per-SDK structured output (JSON-schema validation, Zod)                                                                                                                                                                                                      |
-| `reviewer-tool-test`            | Custom reviewer tool wiring (Copilot — copilot-worker.ts only)                                                                                                                                                                                               |
-| `review-fix-loop`               | Draft → loop(review → fix) with bounded iterations and early exit on a `CLEAN` verdict — a reliable review gate showing how a stage's return value (`handle.result`) drives TypeScript control flow                                                          |
-| `multi-workflow`                | Two Claude workflows under one `cli.ts` — uses `listWorkflows(registry)` to register one Commander subcommand per workflow with each workflow's declared inputs as `--<flag>` options.                                                |
-| `commander-embed`               | Mount an atomic workflow under a parent Commander CLI by calling `runWorkflow({ workflow, inputs })` inside a Commander action, alongside a plain Commander sibling command. No re-entry boilerplate — the SDK ships its own orchestrator entry script. |
+| Example                         | What it demonstrates                                                                                                                                                                                                                                                                                                   |
+| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `hello-world`                   | Minimal single-session workflow with structured inputs (greeting, style, optional notes)                                                                                                                                                                                                                               |
+| `sequential-describe-summarize` | Two stages passing data via `s.save()` → `s.transcript(handle)` — the canonical handoff pattern                                                                                                                                                                                                                        |
+| `parallel-hello-world`          | `Promise.all()` fan-out and transcript merge                                                                                                                                                                                                                                                                           |
+| `headless-test`                 | Visible seed → 3 parallel headless stages → visible merge → headless verdict                                                                                                                                                                                                                                           |
+| `hil-favorite-color`            | Human-in-the-loop prompt mid-workflow                                                                                                                                                                                                                                                                                  |
+| `hil-favorite-color-headless`   | HIL pause inside a headless stage                                                                                                                                                                                                                                                                                      |
+| `structured-output-demo`        | Per-SDK structured output (JSON-schema validation, Zod)                                                                                                                                                                                                                                                                |
+| `reviewer-tool-test`            | Custom reviewer tool wiring (Copilot — copilot-worker.ts only)                                                                                                                                                                                                                                                         |
+| `review-fix-loop`               | Draft → loop(review → fix) with bounded iterations and early exit on a `CLEAN` verdict — a reliable review gate showing how a stage's return value (`handle.result`) drives TypeScript control flow                                                                                                                    |
+| `multi-workflow`                | Two Claude workflows under one `cli.ts` — uses `listWorkflows(registry)` to register one Commander subcommand per workflow with each workflow's declared inputs as `--<flag>` options.                                                                                                                                 |
+| `commander-embed`               | Mount an atomic workflow under a parent Commander CLI by calling `runWorkflow({ workflow, inputs })` inside a Commander action, alongside a plain Commander sibling command. No re-entry boilerplate — the SDK ships its own orchestrator entry script.                                                                |
 | `pane-navigation`               | Driver CLI for the SDK pane-navigation primitives (`nextWindow`, `previousWindow`, `gotoOrchestrator`, `attachSession`, `detachSession`). Spawns a 3-stage workflow detached and exposes `start / list / status / next / prev / home / attach / stop` subcommands. Catches `SessionNotFoundError` for friendly errors. |
 
 Run any of them with:
@@ -1247,19 +1248,19 @@ Native slash commands (`/help`, `/clear`, `/compact`, `/model`, `/theme`, `/agen
 
 The SDK ships pure functions you compose into whatever CLI shape you want:
 
-| Primitive               | Purpose                                                                                                |
-| ----------------------- | ------------------------------------------------------------------------------------------------------ |
-| `defineWorkflow`        | Author a workflow with `.for(agent).run(...).compile()`. Pass `source: import.meta.path`.              |
-| `createRegistry`        | Build an immutable registry of workflows for iteration / lookup.                                       |
-| `listWorkflows(reg)`    | Snapshot every workflow in a registry.                                                                 |
-| `getWorkflow(reg, …)`   | Resolve `(agent, name)` → workflow.                                                                    |
-| `getName / getAgent / getInputSchema / getDescription / getSource / getMinSDKVersion` | Read workflow metadata.        |
-| `validateInputs(wf, raw)` | Run the same validation pipeline atomic uses (required, defaults, enum, integer).                    |
-| `runWorkflow({ workflow, inputs, detach? })` | Spawn the orchestrator tmux session and (optionally) attach. Resolves with `{ id, tmuxSessionName }`. |
-| `listSessions / getSession / stopSession / attachSession / detachSession` | Manage running tmux sessions on the shared atomic socket. |
-| `getSessionStatus / getSessionTranscript`    | Read the orchestrator-written status snapshot or per-session messages from disk.  |
-| `nextWindow / previousWindow / gotoOrchestrator` | **Pane navigation** — pure tmux verbs that update the session's current-window pointer. Never auto-attach; an attached client sees the change live, otherwise a subsequent `attachSession` lands on the new window. |
-| `MissingDependencyError / SessionNotFoundError / WorkflowNotCompiledError / InvalidWorkflowError / IncompatibleSDKError` | **Typed errors** thrown by the primitives above. Catch with `instanceof` to render friendly CLI messages without parsing message text. |
+| Primitive                                                                                                                | Purpose                                                                                                                                                                                                             |
+| ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `defineWorkflow`                                                                                                         | Author a workflow with `.for(agent).run(...).compile()`. Pass `source: import.meta.path`.                                                                                                                           |
+| `createRegistry`                                                                                                         | Build an immutable registry of workflows for iteration / lookup.                                                                                                                                                    |
+| `listWorkflows(reg)`                                                                                                     | Snapshot every workflow in a registry.                                                                                                                                                                              |
+| `getWorkflow(reg, …)`                                                                                                    | Resolve `(agent, name)` → workflow.                                                                                                                                                                                 |
+| `getName / getAgent / getInputSchema / getDescription / getSource / getMinSDKVersion`                                    | Read workflow metadata.                                                                                                                                                                                             |
+| `validateInputs(wf, raw)`                                                                                                | Run the same validation pipeline atomic uses (required, defaults, enum, integer).                                                                                                                                   |
+| `runWorkflow({ workflow, inputs, detach? })`                                                                             | Spawn the orchestrator tmux session and (optionally) attach. Resolves with `{ id, tmuxSessionName }`.                                                                                                               |
+| `listSessions / getSession / stopSession / attachSession / detachSession`                                                | Manage running tmux sessions on the shared atomic socket.                                                                                                                                                           |
+| `getSessionStatus / getSessionTranscript`                                                                                | Read the orchestrator-written status snapshot or per-session messages from disk.                                                                                                                                    |
+| `nextWindow / previousWindow / gotoOrchestrator`                                                                         | **Pane navigation** — pure tmux verbs that update the session's current-window pointer. Never auto-attach; an attached client sees the change live, otherwise a subsequent `attachSession` lands on the new window. |
+| `MissingDependencyError / SessionNotFoundError / WorkflowNotCompiledError / InvalidWorkflowError / IncompatibleSDKError` | **Typed errors** thrown by the primitives above. Catch with `instanceof` to render friendly CLI messages without parsing message text.                                                                              |
 
 **Single workflow (most common):**
 

package/dist/lib/atomic-temp.d.ts

@@ -0,0 +1,8 @@
+export declare const ATOMIC_TEMP_ENV_KEYS: readonly ["TMPDIR", "TMP", "TEMP"];
+export declare function atomicTempDir(homeDir?: string): string;
+export declare function ensureAtomicTempDir(dir?: string): string;
+export declare function atomicTempEnv(dir?: string): Record<string, string>;
+export declare function atomicTempPath(prefix: string, extension: string, id?: string, dir?: string): string;
+export declare function atomicContentTempPath(prefix: string, extension: string, content: string, dir?: string): string;
+export declare function withAtomicTempEnv<T>(fn: () => Promise<T>, dir?: string): Promise<T>;
+//# sourceMappingURL=atomic-temp.d.ts.map

package/dist/lib/atomic-temp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic-temp.d.ts","sourceRoot":"","sources":["../../src/lib/atomic-temp.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,oBAAoB,oCAAqC,CAAC;AAEvE,wBAAgB,aAAa,CAAC,OAAO,GAAE,MAAkB,GAAG,MAAM,CAEjE;AAED,wBAAgB,mBAAmB,CAAC,GAAG,GAAE,MAAwB,GAAG,MAAM,CAMzE;AAED,wBAAgB,aAAa,CAAC,GAAG,GAAE,MAA8B,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAEzF;AAED,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,EAAE,GAAE,MAAqB,EACzB,GAAG,GAAE,MAA8B,GAClC,MAAM,CAER;AAED,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,GAAG,GAAE,MAA8B,GAClC,MAAM,CAGR;AAED,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,GAAG,GAAE,MAA8B,GAClC,OAAO,CAAC,CAAC,CAAC,CAgBZ"}

package/dist/lib/terminal-env.d.ts

@@ -0,0 +1,9 @@
+export declare const TERMINAL_ENV_KEYS: readonly ["LANG", "LC_ALL", "LC_CTYPE", "TERM", "COLORTERM"];
+export type TerminalEnvKey = (typeof TERMINAL_ENV_KEYS)[number];
+export declare function normalizedTerminalEnv(baseEnv?: NodeJS.ProcessEnv): Record<string, string>;
+export declare function mergeTerminalEnv(envVars?: Record<string, string>, baseEnv?: NodeJS.ProcessEnv): Record<string, string>;
+export declare function pickTerminalEnv(env: Record<string, string>): Partial<Record<TerminalEnvKey, string>>;
+export declare function buildSpawnEnv(explicitEnv: Record<string, string>, baseEnv?: NodeJS.ProcessEnv): Record<string, string>;
+export declare function buildLauncherEnv(explicitEnv: Record<string, string>, baseEnv?: NodeJS.ProcessEnv): Record<string, string>;
+export declare function buildTmuxEnv(explicitEnv: Record<string, string>, baseEnv?: NodeJS.ProcessEnv): Record<string, string>;
+//# sourceMappingURL=terminal-env.d.ts.map

package/dist/lib/terminal-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-env.d.ts","sourceRoot":"","sources":["../../src/lib/terminal-env.ts"],"names":[],"mappings":"AAYA,eAAO,MAAM,iBAAiB,8DAMpB,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhE,wBAAgB,qBAAqB,CACnC,OAAO,GAAE,MAAM,CAAC,UAAwB,GACvC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA0BxB;AAED,wBAAgB,gBAAgB,CAC9B,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,EACpC,OAAO,GAAE,MAAM,CAAC,UAAwB,GACvC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAGxB;AAED,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC1B,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC,CAQzC;AAED,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACnC,OAAO,GAAE,MAAM,CAAC,UAAwB,GACvC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAExB;AAUD,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACnC,OAAO,GAAE,MAAM,CAAC,UAAwB,GACvC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAExB;AAED,wBAAgB,YAAY,CAC1B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACnC,OAAO,GAAE,MAAM,CAAC,UAAwB,GACvC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAExB"}

package/dist/sdk/providers/claude.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../../src/sdk/providers/claude.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../../src/sdk/providers/claude.ts"],"names":[],"mappings":"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"}

package/dist/sdk/providers/copilot.d.ts

@@ -4,24 +4,34 @@
  * Checks that Copilot workflow source files use the runtime-managed
  * `s.client` and `s.session` instead of manual SDK client creation.
  */
-import type { SessionConfig as CopilotSessionConfig } from "@github/copilot-sdk";
+import type { CopilotClientOptions, SessionConfig as CopilotSessionConfig } from "@github/copilot-sdk";
 /**
- * Env inherited by the Copilot CLI subprocess the SDK spawns.
+ * Return `true` when `candidate` is a Node.js / npm-loader JavaScript shim
+ * that should not be passed to the Copilot SDK as the CLI executable.
  *
- * `NODE_NO_WARNINGS=1` silences the
- * `ExperimentalWarning: SQLite is an experimental feature` banner that
- * Node prints via the CLI's bundled `require("node:sqlite")`. The SDK
- * pipes the subprocess's stderr through `process.stderr` with a
- * `[CLI subprocess]` prefix, so without this override the warning
- * leaks into every `atomic chat -a copilot` and `atomic workflow -a
- * copilot` invocation.
+ * Filesystem errors for a given candidate are treated as "not a shim" so
+ * that the SDK can surface the real error (e.g. permission denied, ENOENT).
+ */
+export declare function isCopilotShim(candidate: string): boolean;
+/**
+ * Build the subprocess environment for the Copilot CLI process.
+ * Normalises locale to UTF-8 and suppresses Node.js deprecation warnings.
+ */
+export declare function copilotSubprocessEnv(baseEnv?: NodeJS.ProcessEnv): Record<string, string | undefined>;
+/**
+ * Enumerate every existing `cmd` candidate across PATH order.
+ */
+export declare function enumeratePathCandidates(cmd: string, pathEnv: string): string[];
+export declare function resolveCopilotCliPath(): string | undefined;
+/**
+ * Build options suitable for `new CopilotClient(...)`.
  *
- * The SDK uses `options.env ?? process.env` as-is (no merge) when
- * spawning, so we must fold the existing env in ourselves. Returns a
- * fresh object per call so callers can layer additional env without
- * mutating shared state.
+ * Includes:
+ * - `env` from {@link copilotSubprocessEnv} (UTF-8 locale + `NODE_NO_WARNINGS=1`).
+ * - `cliPath` from {@link resolveCopilotCliPath} when resolvable; omitted
+ *   otherwise so the SDK falls back to its bundled CLI.
  */
-export declare function copilotSubprocessEnv(): Record<string, string | undefined>;
+export declare function copilotSdkLaunchOptions(): CopilotClientOptions;
 /**
  * Fold the atomic-managed additional instructions into a caller's
  * `systemMessage` value on `client.createSession`. Behavior:

package/dist/sdk/providers/copilot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"copilot.d.ts","sourceRoot":"","sources":["../../../src/sdk/providers/copilot.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,IAAI,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAGjF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAEzE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,oBAAoB,CAAC,eAAe,CAAC,EAC/C,KAAK,EAAE,MAAM,GACZ,oBAAoB,CAAC,eAAe,CAAC,CASvC;AAED;;GAEG;AACH,eAAO,MAAM,uBAAuB,+DAelC,CAAC"}
+{"version":3,"file":"copilot.d.ts","sourceRoot":"","sources":["../../../src/sdk/providers/copilot.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EACV,oBAAoB,EACpB,aAAa,IAAI,oBAAoB,EACtC,MAAM,qBAAqB,CAAC;AAwC7B;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAYxD;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,GAAE,MAAM,CAAC,UAAwB,GACvC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAEpC;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAQ9E;AAED,wBAAgB,qBAAqB,IAAI,MAAM,GAAG,SAAS,CAe1D;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,IAAI,oBAAoB,CAS9D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,oBAAoB,CAAC,eAAe,CAAC,EAC/C,KAAK,EAAE,MAAM,GACZ,oBAAoB,CAAC,eAAe,CAAC,CASvC;AAED;;GAEG;AACH,eAAO,MAAM,uBAAuB,+DAelC,CAAC"}