@bastani/atomic 0.5.34-0 → 0.6.0-0

package/.agents/skills/workflow-creator/references/failure-modes.md

@@ -1,903 +0,0 @@
-# Failure Modes
-
-Common, **silent** ways workflows break across Claude Code, Copilot CLI, and
-OpenCode — and the wrong-vs-right patterns to avoid them.
-
-**Read this before you ship a multi-session workflow.** Most failures here
-don't throw — they produce degraded output that looks plausible, which is
-the hardest kind of bug to catch in review.
-
-## When to consult
-
-- Before writing a planner → orchestrator → reviewer handoff (Copilot / OpenCode)
-- When a stage receives context from a prior stage and the output smells off
-- When a review/fix loop works on small inputs but drifts on large ones
-- When a JSON/markdown parser in a helper stops matching the model's output
-- When you cannot explain where a particular sentence in a downstream prompt came from
-
-## Silent vs. loud
-
-| Severity | What happens | Detection |
-|---|---|---|
-| **Silent** | Wrong output, no exception. Downstream stages consume garbage. | Requires end-to-end observation. Easy to miss in review. |
-| **Loud** | Exception thrown, stage aborts. | Stack trace surfaces in logs. |
-
-Silent failures are catalogued first below. Loud failures are grouped at the end.
-
----
-
-## Quick reference
-
-| # | Failure | Affected | Silent? |
-|---|---|---|---|
-| [F1](#f1-copilot-getlastassistanttext-returns-empty-string) | Copilot: `getLastAssistantText` returns empty string | Copilot | silent |
-| [F2](#f2-copilot-subagent-messages-pollute-getmessages-stream) | Copilot: subagent messages pollute `getMessages()` stream | Copilot | silent |
-| [F3](#f3-opencode-result-parts-contain-non-text-parts) | OpenCode: `result.data.parts` contains non-text parts | OpenCode | silent |
-| [F4](#f4-claude-ssessionquery-returns-sessionmessage-extract-text-with-extractassistanttext) | Claude: `s.session.query()` returns `SessionMessage[]` — extract text with `extractAssistantText(result, 0)` | Claude | silent |
-| [F5](#f5-fresh-session-wipes-prior-stage-context) | Fresh session wipes prior stage context | Copilot, OpenCode | silent |
-| [F6](#f6-planner-prompts-that-dont-request-trailing-commentary-produce-empty-handoffs) | Planner prompts that don't request trailing commentary produce empty handoffs | all | silent |
-| [F7](#f7-continued-sessions-accumulate-state-across-loop-iterations) | Continued sessions accumulate state across loop iterations (lost-in-middle) | all | silent |
-| [F8](#f8-fenced-block-parsers-break-when-the-model-adds-prose) | Fenced-block parsers break when the model adds prose before/after | all | silent |
-| [F9](#f9-ssave-receives-the-wrong-shape) | `s.save()` receives the wrong shape for the SDK | all | silent |
-| [F10](#f10-copilot-sendandwait-default-60s-timeout-throws) | Copilot: `sendAndWait` default 60s timeout throws (use `send` by default) | Copilot | loud |
-| [F11](#f11-provider-level-resume-tries-to-swap-agents) | Provider-level resume tries to swap agents | Copilot, OpenCode | loud |
-| [F12](#f12-parallel-siblings-read-each-others-transcripts) | Parallel siblings read each other's transcripts | all | loud |
-| [F13](#f13-forgetting-to-await-ctxstage) | Forgetting to `await` `ctx.stage()` | all | silent |
-| [F14](#f14-using-a-pending-sessionhandle-before-completion) | Using a pending `SessionHandle` before completion | all | silent |
-| [F15](#f15-headless-stage-errors-are-invisible-in-the-graph) | Headless stage errors are invisible in the graph | all | silent |
-| [F16](#f16-claude-importing-sdk-query-inside-a-non-headless-stage) | Claude: importing the SDK `query()` inside a non-headless stage (anti-pattern) | Claude | silent |
-
----
-
-## Silent failures
-
-### F1. Copilot: `getLastAssistantText` returns empty string
-
-**Symptom.** The orchestrator (or any downstream stage) receives an empty
-`plannerNotes` / `reviewerOutput` despite the prior agent running successfully
-and producing visible output in the TUI.
-
-**Root cause.** Copilot emits an **empty terminating `assistant.message` event**
-after every turn that included a tool call. The actual prose + toolRequests
-live in the earlier `assistant.message` event; the trailing one has
-`content: ""` and no `toolRequests`. Picking `.at(-1).data.content` reliably
-lands on the empty terminator and throws away the real content.
-
-Verified empirically with a toy script against Copilot CLI 1.0.22: a
-single-turn "think then call tool" prompt produced 2 assistant.message
-events, `[{length: 512, toolRequests: 1}, {length: 0, toolRequests: 0}]`.
-The second one is what `.at(-1)` returns.
-
-The event type carries both `content: string` and `toolRequests?: [...]` —
-see `node_modules/@github/copilot-sdk/dist/generated/session-events.d.ts:1408-1455`.
-
-This means the bug affects **any** stage whose final turn includes a tool
-call — not just tool-calls-only turns. Planner, reviewer, debugger, and
-orchestrator stages all hit it if they end on a tool invocation.
-
-**Affected SDKs.** Copilot only.
-
-### ❌ Wrong
-
-```ts
-function getLastAssistantText(messages: SessionEvent[]): string {
-  const assistantMessages = messages.filter(
-    (m): m is Extract<SessionEvent, { type: "assistant.message" }> =>
-      m.type === "assistant.message",
-  );
-  return assistantMessages.at(-1)?.data.content ?? "";
-}
-```
-
-### ✅ Right
-
-```ts
-/** Concatenate every top-level assistant turn's non-empty content. */
-function getAssistantText(messages: SessionEvent[]): string {
-  return messages
-    .filter(
-      (m): m is Extract<SessionEvent, { type: "assistant.message" }> =>
-        m.type === "assistant.message" && !m.data.parentToolCallId,
-    )
-    .map((m) => m.data.content)
-    .filter((c) => c.length > 0)
-    .join("\n\n");
-}
-```
-
-**Detection.** Log the returned text length after every `getAssistantText`
-call during development. An empty or surprisingly short string for a stage
-that clearly ran is the signature.
-
----
-
-### F2. Copilot: subagent messages pollute `getMessages()` stream
-
-**Symptom.** Downstream stages receive a snippet of text that doesn't match
-what the top-level agent said — it looks like a subagent's output.
-
-**Root cause.** `assistant.message` events carry a `parentToolCallId?: string`
-field, documented as *"Tool call ID of the parent tool invocation when this
-event originates from a subagent"*. When the top-level agent delegates,
-`getMessages()` returns **the complete history including subagent messages**.
-Filters that don't exclude `parentToolCallId` can pick a subagent's final
-message via `.at(-1)`.
-
-**Affected SDKs.** Copilot.
-
-### ❌ Wrong
-
-```ts
-messages.filter((m) => m.type === "assistant.message")
-```
-
-### ✅ Right
-
-```ts
-messages.filter(
-  (m) => m.type === "assistant.message" && !m.data.parentToolCallId,
-)
-```
-
-**Detection.** Same as F1 — diff what you extract against the TUI
-scrollback for the top-level agent.
-
----
-
-### F3. OpenCode: `result.data.parts` contains non-text parts
-
-**Symptom.** Concatenated response text contains `[object Object]`,
-truncated content, or swallows tool-call payloads into the prompt.
-
-**Root cause.** `client.session.prompt()` returns `result.data.parts: Part[]`
-where parts can be `type: "text" | "tool" | "file" | "reasoning" | ...`.
-Naive `.map(p => p.text).join()` emits `undefined` for non-text parts.
-
-**Affected SDKs.** OpenCode.
-
-### ❌ Wrong
-
-```ts
-const text = result.data!.parts.map((p) => p.text).join("\n");
-```
-
-### ✅ Right
-
-```ts
-function extractResponseText(
-  parts: Array<{ type: string; [key: string]: unknown }>,
-): string {
-  return parts
-    .filter((p) => p.type === "text")
-    .map((p) => (p as { type: string; text: string }).text)
-    .join("\n");
-}
-```
-
-**Detection.** Grep extracted text for `[object Object]` or `undefined`.
-
----
-
-### F4. Claude: `s.session.query()` returns `SessionMessage[]` — extract text with `extractAssistantText`
-
-**Symptom.** Workflow code tries to access `.output` or `.text` on the
-result of `s.session.query()` and gets `undefined`, or passes the result
-directly to a string parser that throws.
-
-**Root cause.** `s.session.query()` returns `SessionMessage[]` — the native
-Claude Agent SDK type. It does NOT return a `{ output: string }` object or a
-raw TUI scrollback string. The assistant's text lives inside structured content
-blocks within those messages and must be extracted explicitly.
-
-**Affected SDKs.** Claude.
-
-### ❌ Wrong
-
-```ts
-// result is SessionMessage[], not { output: string }
-const result = await s.session.query(prompt);
-const parsed = JSON.parse(result.output);  // TypeError: result.output is undefined
-```
-
-### ✅ Right — use `extractAssistantText(result, 0)`
-
-```ts
-import { extractAssistantText } from "@bastani/atomic/workflows";
-
-const result = await s.session.query(prompt);
-const text = extractAssistantText(result, 0);
-// Now `text` is the concatenated assistant prose for this turn
-```
-
-`extractAssistantText(msgs, afterIndex)` walks `SessionMessage[]` from
-`afterIndex` forward, pulls `TextBlock.text` from each `assistant` message's
-content array, and joins them with newlines.
-
-The ralph helpers in `src/sdk/workflows/builtin/ralph/helpers/prompts.ts`
-(`parseReviewResult`, `extractMarkdownBlock`) use this pattern — always
-extract text first, then parse.
-
-**Detection.** Log `typeof result` after `s.session.query()`. If it's
-`object` (an array), you need `extractAssistantText`. Accessing `.output`
-on an array returns `undefined`.
-
----
-
-### F5. Fresh session wipes prior stage context
-
-**Symptom.** The orchestrator says "I don't see a task list" or "what
-specification are you referring to?" even though the planner clearly ran.
-
-**Root cause.** `client.createSession()` / `client.session.create()` always
-returns a **fresh, empty conversation**. The CLIENT object is just the
-transport — each session is independent. The new session sees only what you
-put in its first prompt.
-
-**Affected SDKs.** Copilot, OpenCode. (Claude's session model is
-different — context accumulates within the same SDK session, so this failure
-mode does NOT apply to `s.session.query()`.)
-
-### ❌ Wrong
-
-```ts
-await ctx.stage({ name: "planner" }, {}, { agent: "planner" }, async (s) => {
-  await s.session.send({ prompt: buildPlannerPrompt((s.inputs.prompt ?? "")) });
-  s.save(await s.session.getMessages());
-});
-// orchestrator is a fresh session — it has no idea what the planner produced
-await ctx.stage({ name: "orchestrator" }, {}, { agent: "orchestrator" }, async (s) => {
-  await s.session.send({ prompt: buildOrchestratorPrompt() });
-  s.save(await s.session.getMessages());
-});
-```
-
-### ✅ Right — explicit handoff
-
-```ts
-const plannerHandle = await ctx.stage(
-  { name: "planner" },
-  {},
-  { agent: "planner" },
-  async (s) => {
-    await s.session.send({ prompt: buildPlannerPrompt((s.inputs.prompt ?? "")) });
-    const messages = await s.session.getMessages();
-    s.save(messages);
-    return getAssistantText(messages); // see F1 for getAssistantText
-  },
-);
-
-await ctx.stage(
-  { name: "orchestrator" },
-  {},
-  { agent: "orchestrator" },
-  async (s) => {
-    await s.session.send({
-      prompt: buildOrchestratorPrompt(
-        (s.inputs.prompt ?? ""),
-        { plannerNotes: plannerHandle.result },
-      ),
-    });
-    s.save(await s.session.getMessages());
-  },
-);
-```
-
-Alternatives: write to shared state (`TaskCreate`/`TaskList`, files, git) and
-have the next stage read from there, or keep the follow-up inside the same
-stage callback when it needs the full live conversation. Provider-level resume
-is an advanced same-role escape hatch, not the normal stage-to-stage handoff.
-
-**Full write-up.** `agent-sessions.md` §"Critical pitfall: session lifecycle
-controls what context is available".
-
----
-
-### F6. Planner prompts that don't request trailing commentary produce empty handoffs
-
-**Symptom.** F1 / F5 are fixed, extraction is correct — and the orchestrator
-still receives empty `plannerNotes` because the planner's last turn legitimately
-had no prose.
-
-**Root cause.** This is a **prompt engineering** bug, not a code bug. When a
-prompt ends with "call `TaskList` to verify" and does not explicitly ask for
-trailing commentary, many models end the turn with just the tool call and
-no text at all. There's nothing in any turn's `content` to extract because
-the model never wrote any.
-
-**Affected SDKs.** All three — though Claude's pane scrollback masks it by
-still capturing something visible.
-
-### ❌ Wrong — silent handoff
-
-```ts
-return `# Planning
-
-${spec}
-
-Decompose the specification into tasks via TaskCreate. After creating all
-tasks, call TaskList to verify.`;
-```
-
-### ✅ Right — explicit trailing commentary requirement
-
-```ts
-return `# Planning
-
-${spec}
-
-Decompose the specification into tasks via TaskCreate. After creating all
-tasks, call TaskList to verify.
-
-## Final output (required)
-
-After the TaskList call, write a short "Handoff Notes" section with:
-- Risks or ambiguities the orchestrator must know about
-- Any assumptions you made that could be wrong
-- Ordering constraints that don't fit into task bodies
-
-The orchestrator will run in a fresh session — anything not in your
-TaskCreate calls or this section will be lost.`;
-```
-
-**Pair this fix with F1.** Even with the correct extraction helper, you need
-the model to actually produce text for the helper to extract.
-
-**Detection.** Log the extracted handoff text during development. An empty
-string + a correctly-fixed extraction helper = F6.
-
----
-
-### F7. Continued sessions accumulate state across loop iterations (lost-in-middle)
-
-**Symptom.** A review/fix loop works on iterations 1-3 then starts
-producing worse output — misidentifying files, hallucinating line numbers,
-or "forgetting" a requirement that was clearly stated in the original spec.
-
-**Root cause.** Each loop iteration adds turns to the same continued
-session, and context grows past the attention window. The model starts
-dropping middle-of-context information (classic lost-in-middle).
-
-**Affected SDKs.** All three. Claude's session transcript accumulates every
-intermediate turn, so long loops grow the context window substantially.
-
-### ❌ Wrong — unbounded loop on a single session
-
-```ts
-await ctx.stage({ name: "review-loop" }, {}, {}, async (s) => {
-  for (let i = 0; i < 20; i++) {
-    await s.session.query(buildReviewPrompt());
-    await s.session.query(buildFixPrompt());
-  }
-});
-```
-
-### ✅ Right — compact or reset between iterations
-
-Options, in order of preference:
-
-1. **Compact** — summarize prior turns via the SDK's compaction mechanism
-   (Claude's `/compact`, OpenCode's summarizer, a sidecar summarization call
-   for Copilot). Keeps decisions and file paths; drops verbose tool output.
-2. **Offload to files** — write intermediate findings to files and reference
-   them by path in the next iteration's prompt (`filesystem-context` skill).
-3. **Fresh session per iteration with explicit handoff** — see F5's pattern;
-   lose the in-session reasoning but gain a clean context window.
-
-```ts
-await ctx.stage({ name: "review-loop" }, {}, {}, async (s) => {
-  const MAX_TURNS_BEFORE_COMPACT = 10;
-  let turnsSinceCompact = 0;
-
-  for (let i = 0; i < MAX_ITERATIONS; i++) {
-    if (turnsSinceCompact >= MAX_TURNS_BEFORE_COMPACT) {
-      await s.session.query("/compact");
-      turnsSinceCompact = 0;
-    }
-    await s.session.query(buildReviewPrompt());
-    turnsSinceCompact += 1;
-  }
-});
-```
-
-**Consult.** `context-degradation`, `context-compression`, `context-optimization`.
-
-**Detection.** Quality-vs-iteration chart. If quality degrades past
-iteration N, N is your safe-turn budget before compaction.
-
----
-
-### F8. Fenced-block parsers break when the model adds prose
-
-**Symptom.** `JSON.parse(content)` throws, or a "matches the first fenced
-block" regex picks up a code example inside prose instead of the actual
-structured output.
-
-**Root cause.** A prompt asks for `only JSON inside a single fenced block`
-and the model adds a sentence of explanation, a "# Summary" heading, or
-quotes a snippet of its own reasoning in a code fence earlier in the reply.
-
-**Affected SDKs.** All three — this is a model-behavior issue, not
-SDK-specific.
-
-### ❌ Wrong
-
-```ts
-const parsed = JSON.parse(content);
-// or:
-const match = content.match(/```json\n([\s\S]*?)\n```/);
-```
-
-### ✅ Right — layered fallback: direct parse → last fenced block → last balanced object
-
-```ts
-export function parseReviewResult(content: string): ReviewResult | null {
-  // 1. Direct JSON
-  try {
-    const parsed = JSON.parse(content);
-    if (parsed?.findings && parsed?.overall_correctness) return parsed;
-  } catch { /* fall through */ }
-
-  // 2. LAST fenced code block (not the first — prose often quotes examples)
-  const blockRe = /```(?:json)?\s*\n([\s\S]*?)\n```/g;
-  let lastBlock: string | null = null;
-  let m: RegExpExecArray | null;
-  while ((m = blockRe.exec(content)) !== null) {
-    if (m[1]) lastBlock = m[1];
-  }
-  if (lastBlock) {
-    try {
-      const parsed = JSON.parse(lastBlock);
-      if (parsed?.findings && parsed?.overall_correctness) return parsed;
-    } catch { /* fall through */ }
-  }
-
-  // 3. Last balanced object containing the required key
-  // (implementation in src/sdk/workflows/builtin/ralph/helpers/prompts.ts)
-  return null;
-}
-```
-
-**Detection.** Fuzz test the parser against real model output captured
-over several runs. If 1 in 20 runs fails to parse, you have F8.
-
----
-
-### F9. `s.save()` receives the wrong shape
-
-**Symptom.** `s.transcript("stage-name")` returns an empty or malformed
-`content` string in the next stage.
-
-**Root cause.** Each SDK has a different contract for what `s.save()`
-expects, and the runtime doesn't type-check the argument beyond "anything".
-
-**Affected SDKs.** All three — the mistake is in the workflow author's code.
-
-### Correct shapes
-
-| SDK | Correct argument |
-|---|---|
-| Claude | `s.save(s.sessionId)` — pass the session ID; the runtime reads the transcript file |
-| Copilot | `s.save(await s.session.getMessages())` — pass `SessionEvent[]` |
-| OpenCode | `s.save(result.data!)` — pass the `{ info, parts }` object |
-
-### ❌ Wrong
-
-```ts
-// Claude — saves the wrong thing (result is SessionMessage[], not { output: string })
-s.save(result.output);  // TypeError: result.output is undefined; use s.save(s.sessionId)
-
-// Copilot — calling getMessages() BEFORE send() returns an empty array
-const earlyMessages = await s.session.getMessages(); // [] — no turns yet
-s.save(earlyMessages);
-
-// Copilot — saving a single message instead of the full array
-s.save((await s.session.getMessages()).at(-1));
-
-// OpenCode — missing the data unwrap
-s.save(result);
-```
-
-### ✅ Right
-
-See the per-SDK examples in `SKILL.md` §"Write the Workflow File" and the
-`SessionContext` reference table.
-
-**Detection.** Read `s.transcript(name).content` in the next stage and
-log the length. A 0-length or JSON-that-isn't-prose signature = F9.
-
----
-
-## Loud failures (throw, but still worth knowing)
-
-### F10. Copilot: `sendAndWait` default 60s timeout throws
-
-**Symptom.** `Timeout after 60000ms waiting for session.idle`. Every
-subsequent `ctx.stage()` call never executes — the throw propagates out of
-`run()` and halts the workflow.
-
-**Root cause.** The raw Copilot SDK's `sendAndWait(options, timeout?)`
-defaults to a 60-second timeout that throws on expiry. Real agent work
-(planners, reviewers, orchestrators) routinely exceeds this.
-
-**Fix.** Use `send` instead. Inside an Atomic stage the runtime wraps
-`s.session.send()` so it blocks until `session.idle` with **no timeout** —
-the same blocking semantics as Claude's `query()` and OpenCode's
-`session.prompt()`. The wrapper lives in `wrapCopilotSend`
-(`src/sdk/runtime/executor.ts`) and is installed per-stage.
-
-```ts
-// Correct: send() in an Atomic stage blocks until idle, no timeout.
-await s.session.send({ prompt });
-const messages = await s.session.getMessages(); // safe to read
-```
-
-**Do not reach for `sendAndWait` with a larger explicit timeout.** `send`
-already waits for idle; `sendAndWait` just adds a throw-on-timeout failure
-mode on top. If you catch yourself writing `sendAndWait(..., 5 * 60 * 1000)`
-to "be safe", you want `send`.
-
----
-
-### F11. Provider-level resume tries to swap agents
-
-**Symptom.** Resumed Copilot / OpenCode session behaves as the original
-agent instead of the requested new one — or the SDK throws "agent mismatch"
-on resume.
-
-**Root cause.** Each session is **bound to one agent at creation time**.
-`resumeSession` reattaches the conversation but does not change the agent.
-
-**Fix.** Use provider-level resume only for multi-turn work within the same
-role. To swap agents, create a new session (fresh) and forward context via
-F5's pattern. In normal workflow code, prefer a same-stage multi-turn session
-over trying to reopen a prior stage.
-
----
-
-### F12. Parallel siblings read each other's transcripts
-
-**Symptom.** `s.transcript("sibling-name")` inside a parallel session
-throws or returns empty.
-
-**Root cause.** `s.transcript()` only exposes **prior completed sessions** —
-ones whose callback has returned and whose saves have flushed. Sessions
-launched concurrently via `Promise.all([ctx.stage(...), ctx.stage(...)])` run
-at the same time; forward-only data flow is enforced.
-
-**Fix.** Restructure to either a linear chain, a "fan-out, then merge"
-pattern where a subsequent session reads both, or use external
-shared state (files, DB) if siblings genuinely need to coordinate.
-
-```ts
-// Fan-out → merge
-// Strings used here for brevity; prefer handles (s.transcript(handle)) when one is in scope.
-const describe = await ctx.stage({ name: "describe" }, {}, {}, async (s) => { /* ... */ });
-
-const [summarizeA, summarizeB] = await Promise.all([
-  ctx.stage({ name: "summarize-a" }, {}, {}, async (s) => {
-    const d = await s.transcript(describe); // OK — prior completed session (handle-based, preferred)
-    // s.transcript("summarize-b") would fail here — sibling not yet complete
-  }),
-  ctx.stage({ name: "summarize-b" }, {}, {}, async (s) => {
-    const d = await s.transcript(describe); // OK — prior completed session
-  }),
-]);
-
-await ctx.stage({ name: "merge" }, {}, {}, async (s) => {
-  const a = await s.transcript(summarizeA); // OK — handle-based, preferred over "summarize-a"
-  const b = await s.transcript(summarizeB);
-});
-```
-
----
-
-### F13. Forgetting to `await` `ctx.stage()`
-
-**Symptom.** A session runs (its tmux window opens, the agent does work)
-but the orchestrator doesn't wait for it. Subsequent sessions that depend
-on its output via `transcript()` or `getMessages()` see empty or missing
-data. The workflow may finish "successfully" before the session's callback
-has returned.
-
-**Root cause.** `ctx.stage()` returns a `Promise<SessionHandle<T>>`.
-Without `await`, the session is spawned but the `.run()` callback continues
-immediately. The session's save never reaches the `completedRegistry`
-before downstream code tries to read it.
-
-**Affected SDKs.** All three — this is a TypeScript control-flow bug, not
-SDK-specific.
-
-### ❌ Wrong
-
-```ts
-// Missing await — session fires but orchestrator doesn't wait
-ctx.stage({ name: "research" }, {}, {}, async (s) => {
-  // ... agent work ...
-  s.save(s.sessionId);
-});
-
-// This runs before "research" completes
-await ctx.stage({ name: "synthesize" }, {}, {}, async (s) => {
-  const r = await s.transcript("research"); // empty or throws
-});
-```
-
-### ✅ Right
-
-```ts
-await ctx.stage({ name: "research" }, {}, {}, async (s) => {
-  // ... agent work ...
-  s.save(s.sessionId);
-});
-
-await ctx.stage({ name: "synthesize" }, {}, {}, async (s) => {
-  const r = await s.transcript("research"); // works
-});
-```
-
-**Detection.** If a session's graph node shows as "running" while
-downstream sessions are already executing, you likely dropped an `await`.
-TypeScript's `@typescript-eslint/no-floating-promises` lint rule catches
-this at compile time.
-
----
-
-### F14. Using a pending `SessionHandle` before completion
-
-**Symptom.** `handle.result` is `undefined` or stale, or
-`s.transcript(handle)` throws / returns empty even though the session
-eventually completes.
-
-**Root cause.** `ctx.stage()` returns a `SessionHandle<T>` whose
-`.result` is only populated after the callback returns. If you store the
-promise but access the handle before awaiting it, the result field is
-not yet set and the session is not in the `completedRegistry`.
-
-**Affected SDKs.** All three.
-
-### ❌ Wrong
-
-```ts
-// Start both but access handles before awaiting
-const handleA = ctx.stage({ name: "a" }, {}, {}, async (s) => { /* ... */ return 42; });
-const handleB = ctx.stage({ name: "b" }, {}, {}, async (s) => {
-  // handleA is a Promise, not a resolved SessionHandle
-  const transcript = await s.transcript(handleA); // fails
-});
-```
-
-### ✅ Right
-
-```ts
-// Await first, then use the resolved handle
-const handleA = await ctx.stage({ name: "a" }, {}, {}, async (s) => { /* ... */ return 42; });
-
-await ctx.stage({ name: "b" }, {}, {}, async (s) => {
-  const transcript = await s.transcript(handleA); // works — handleA is resolved
-  console.log(handleA.result); // 42
-});
-```
-
-For parallel sessions, use `Promise.all()` and access handles only after
-all promises resolve:
-
-```ts
-const [a, b] = await Promise.all([
-  ctx.stage({ name: "a" }, {}, {}, async (s) => { /* ... */ return "x"; }),
-  ctx.stage({ name: "b" }, {}, {}, async (s) => { /* ... */ return "y"; }),
-]);
-// a.result === "x", b.result === "y"
-```
-
-**Detection.** TypeScript's type system helps — `ctx.stage()` returns
-`Promise<SessionHandle<T>>`, not `SessionHandle<T>` directly. If you're
-accessing `.result` without awaiting, the type will be `Promise`, not `T`.
-
----
-
-### F15. Headless stage errors are invisible in the graph
-
-**Symptom.** A workflow fails but the graph shows all visible stages as
-completed. The error message references a session name that doesn't appear
-in the graph panel.
-
-**Root cause.** Headless stages (`{ headless: true }`) are invisible in the
-workflow graph — they have no graph node, no tmux window, and no pane
-preview. When a headless stage throws, the error is recorded in the
-`failedRegistry` and the workflow halts, but the failure is only visible in
-the orchestrator's error output and the session's `error.txt` file on disk.
-
-**Affected SDKs.** All three — this is an executor-level behavior, not
-SDK-specific.
-
-### ❌ Wrong — no error context for headless stages
-
-```ts
-// Headless stage fails silently in the graph
-const [a, b, c] = await Promise.all([
-  ctx.stage({ name: "gather-a", headless: true }, {}, {}, async (s) => {
-    throw new Error("API key expired"); // Fails — no graph node to show red
-  }),
-  ctx.stage({ name: "gather-b", headless: true }, {}, {}, async (s) => { /* ... */ }),
-  ctx.stage({ name: "gather-c", headless: true }, {}, {}, async (s) => { /* ... */ }),
-]);
-```
-
-### ✅ Right — wrap headless stages with descriptive error context
-
-```ts
-const [a, b, c] = await Promise.all([
-  ctx.stage({ name: "gather-a", headless: true }, {}, {}, async (s) => {
-    try {
-      return await doWork(s);
-    } catch (error) {
-      throw new Error(`[gather-a] ${error instanceof Error ? error.message : String(error)}`);
-    }
-  }),
-  // ... same pattern for b, c
-]);
-```
-
-**Detection.** If a workflow fails and the graph shows no failed nodes,
-check the orchestrator log (`orchestrator.log` in the session directory)
-and look for `headless-<name>` in the error output. The session directory
-at `~/.atomic/sessions/<run-id>/<name>-<id>/error.txt` contains the
-full error for each failed headless stage.
-
----
-
-### F16. Claude: importing the SDK `query()` inside a non-headless stage
-
-**Symptom.** A reviewer / extractor / structured-output stage shows up in
-the workflow graph as a tmux pane, but the pane sits idle on the Claude
-welcome screen for the entire stage duration. The stage still produces a
-result — but the visible session never moved. CPU and token cost double:
-two Claude processes ran, one in the pane (idle) and one in-process (the
-SDK call that actually did the work).
-
-**Root cause.** The stage was registered without `headless: true`, so the
-runtime spawned an interactive Claude TUI in a tmux pane and bound
-`s.session` to it. The callback ignored that and called
-`query()` from `@anthropic-ai/claude-agent-sdk` directly:
-
-```ts
-import { query } from "@anthropic-ai/claude-agent-sdk";
-// ...
-ctx.stage({ name: "review" }, {}, {}, async (s) => {
-  for await (const msg of query({ prompt, options: { outputFormat: ... } })) { /* ... */ }
-});
-```
-
-That import bypasses `s.session` entirely. The runtime cannot route the
-SDK call through the TUI it just started, so:
-
-1. The visible pane never receives a prompt — the user sees a blank Claude
-   session in the graph.
-2. A second Claude process spins up in the orchestrator process to service
-   the SDK call. Both processes count against rate limits and token spend.
-3. Idle detection on the pane never fires because no prompt was ever sent;
-   the runtime relies on session-state events that won't arrive, and stage
-   completion happens only because the callback returned (not because the
-   pane finished work).
-
-The runtime exposes exactly two routes for an SDK feature:
-
-| You want to use… | Stage shape | Code in callback |
-|---|---|---|
-| `outputFormat`, custom `agents`, `maxBudgetUsd`, etc. **without** a visible pane | `{ headless: true }` | `s.session.query(prompt, sdkOptions)` — wraps `HeadlessClaudeSessionWrapper.query()` which forwards `options` to the SDK |
-| The visible TUI with a subagent | omit `headless` and pass `chatFlags: ["--agent", "<name>", ...]` | `s.session.query(prompt)` — sends through tmux send-keys |
-
-The one option that does **not** exist is "visible pane + in-process SDK call".
-That combination is always wrong — pick one route or the other.
-
-**Affected SDKs.** Claude only. Copilot and OpenCode don't expose a
-parallel "import the bare SDK" foot-gun in this codebase.
-
-### ❌ Wrong — visible pane + bypassed-SDK call
-
-```ts
-import { query as claudeSdkQuery } from "@anthropic-ai/claude-agent-sdk";
-
-await ctx.stage({ name: "review" }, {}, {}, async (s) => {
-  // Visible TUI was started, but we're ignoring it.
-  for await (const msg of claudeSdkQuery({
-    prompt: reviewPrompt,
-    options: {
-      outputFormat: { type: "json_schema", schema: REVIEW_SCHEMA },
-    },
-  })) {
-    if (msg.type === "result") { /* ... */ }
-  }
-  s.save(s.sessionId);
-});
-```
-
-### ✅ Right (a) — visible TUI with subagent + chatFlags
-
-When you want the user to watch the review happen, run the subagent in
-the pane via `--agent` and parse JSON out of the assistant text. The
-prompt should enumerate the schema fields so the model emits matching
-JSON; a tolerant parser (last-fenced-block + last-balanced-object
-fallback, F8) handles any prose the model adds:
-
-```ts
-await ctx.stage(
-  { name: "review" },
-  { chatFlags: ["--agent", "reviewer", "--allow-dangerously-skip-permissions", "--dangerously-skip-permissions"] },
-  {},
-  async (s) => {
-    const messages = await s.session.query(reviewPrompt);
-    s.save(s.sessionId);
-    return parseReviewResult(extractAssistantText(messages, 0));
-  },
-);
-```
-
-This is the pattern used by `src/sdk/workflows/builtin/ralph/claude/index.ts`
-for its planner, orchestrator, reviewer, and debugger stages.
-
-### ✅ Right (b) — headless stage with SDK options via `s.session.query()`
-
-When you don't need the pane (e.g. background data gathering), set
-`headless: true` and pass SDK options as the second argument to
-`s.session.query()`. The runtime uses `HeadlessClaudeSessionWrapper`,
-which calls the SDK's `query()` in-process and exposes the full options
-surface (`agent`, `outputFormat`, `permissionMode`, `maxBudgetUsd`, etc.):
-
-```ts
-await ctx.stage(
-  { name: "review", headless: true },
-  {}, {},
-  async (s) => {
-    const messages = await s.session.query(reviewPrompt, {
-      agent: "reviewer",
-      permissionMode: "bypassPermissions",
-      allowDangerouslySkipPermissions: true,
-    });
-    s.save(s.sessionId);
-    return extractAssistantText(messages, 0);
-  },
-);
-```
-
-> **Note on `--json-schema`.** The CLI's `--json-schema` flag requires
-> `-p` (print mode) and therefore can't be passed via `chatFlags` to the
-> interactive TUI. If you need SDK-validated structured output, use route
-> (b) — set `headless: true` and pass `outputFormat: { type: "json_schema", schema }`
-> in the `s.session.query()` options. Pair (a)'s visible TUI with a
-> tolerant JSON parser instead. (Note: `s.session.query()`'s headless
-> wrapper currently returns `SessionMessage[]` and discards the SDK
-> result event's `structured_output` field — for now, parse JSON out of
-> the assistant text either way.)
-
-**Detection.**
-1. Grep your workflow for `from "@anthropic-ai/claude-agent-sdk"` —
-   `query`, `tool`, `createSdkMcpServer` and similar imports inside a
-   `.run()` callback are the smell. Workflow code should import from
-   `@bastani/atomic/workflows` and access the SDK exclusively through
-   `s.client` and `s.session`.
-2. Watch the workflow run. If a visible pane shows the Claude welcome
-   screen for the entire duration of a stage and never receives a prompt,
-   you have F16.
-3. Cost monitoring. F16 roughly doubles the Claude process count — if
-   stage spend looks 2× a single run, audit imports.
-
----
-
-## Design checklist
-
-Before shipping a multi-session workflow, walk the list:
-
-- [ ] Copilot stages use `s.session.send` by default; `sendAndWait` only with an explicit user-requested timeout (F10)
-- [ ] Every fresh-session handoff forwards context explicitly (F5)
-- [ ] Every prompt whose output feeds a downstream stage explicitly requests trailing commentary (F6)
-- [ ] Response-text extraction uses the per-SDK correct pattern (F1-F4)
-- [ ] Structured-output parsers extract the LAST fenced block, not the first (F8)
-- [ ] `s.save()` receives the per-SDK correct shape — Copilot uses `s.session.getMessages()` (F9)
-- [ ] Loops over 10 iterations have a compaction / reset strategy (F7)
-- [ ] Parallel groups only read from prior completed sessions, never siblings (F12)
-- [ ] Every `ctx.stage()` call is `await`ed (F13)
-- [ ] `SessionHandle` values are only used after the promise resolves (F14)
-- [ ] If provider-level resume/fork is used at all, it stays within the same agent role (F11)
-- [ ] Headless stage callbacks include descriptive error context so failures can be diagnosed without a graph node (F15)
-- [ ] Claude stages never import `query` (or other entry points) from `@anthropic-ai/claude-agent-sdk` directly — go through `s.session.query()` so the runtime routes to the TUI (interactive) or the SDK (headless) consistently (F16)