@bastani/atomic 0.8.26-alpha.1 → 0.8.26-alpha.11

package/dist/builtin/workflows/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/workflows",
-  "version": "0.8.26-alpha.1",
+  "version": "0.8.26-alpha.11",
   "private": true,
   "description": "Atomic extension for multi-stage workflow authoring and execution.",
   "contributors": [
@@ -83,7 +83,7 @@
   },
   "peerDependencies": {
     "@bastani/atomic": "*",
-    "@earendil-works/pi-tui": "*"
+    "@earendil-works/pi-tui": "^0.78.1"
   },
   "peerDependenciesMeta": {
     "@bastani/atomic": {

package/dist/builtin/workflows/skills/create-spec/SKILL.md

@@ -5,6 +5,20 @@ description: "Create a detailed execution plan/spec/PRD for implementing feature
 
 You are tasked with creating a spec for implementing a new feature or system change in the codebase by leveraging existing research in the **$ARGUMENTS** path. If no research path is specified, use the entire `research/` directory. IMPORTANT: Research documents are located in the `research/` directory — do NOT look in the `specs/` directory for research. Follow the template below to produce a comprehensive specification as output in the `specs/` folder using the findings from RELEVANT research documents found in `research/`. The spec file MUST be named using the format `YYYY-MM-DD-topic.md` (e.g., `specs/2026-03-26-my-feature.md`), where the date is the current date and the topic is a kebab-case summary. Tip: It's good practice to use the `codebase-research-locator` and `codebase-research-analyzer` agents to help you find and analyze the research documents in the `research/` directory. It is also HIGHLY recommended to cite relevant research throughout the spec for additional context.
 
+## Ask Clarifying Questions Before You Start
+
+- If the user's request is vague or lacks necessary details, ask clarifying questions to gather more information before starting the spec creation process. This will help ensure that the spec is comprehensive and aligned with the user's needs.
+
+### Determine the compatibility posture
+
+- Before decomposing the spec creation request, identify whether this project must preserve backward compatibility for real downstream users.
+- If the user explicitly allows breaking changes, public API changes, cleanup, or says there are no real users/downstream dependencies, allow breaking changes.
+- If the user mentions production users, published APIs, downstream consumers, migration safety, or compatibility requirements, disallow breaking changes.
+- If the posture is not inferable from the request, ask the user once before continuing, using the available structured question tool when possible.
+- Carry this posture into the spec creation plan, the final spec frontmatter, and a `## Backwards Compatibility` section in the final spec.
+- When allowing breaking changes, document existing legacy behavior, compatibility shims, optional flags, and public APIs as current state, not as constraints future specs must preserve unless the user explicitly asks for preservation.
+- When not allowing breaking changes, document public APIs, compatibility-sensitive surfaces, downstream callers, migration constraints, and behavior that future work must preserve.
+
 ## Design philosophy: a spec is a theory of its doors
 
 The entrypoints of a program, read together, are the program's **theory of its own purpose**. Everything inside the boundary is mechanism — the *how*. Only at the boundary does the code speak in terms of meaning — the *what* and the *why*. So the single most important thing this spec defines is not the mechanism inside the system, but the **set of doors** the system keeps: the functions, routes, and RPC methods through which untrusted input arrives and irreversible effects happen.

package/dist/builtin/workflows/skills/research-codebase/SKILL.md

@@ -24,14 +24,24 @@ The user's research question/request is: **$ARGUMENTS**
     - **CRITICAL**: Read these files yourself in the main context before spawning any sub-tasks
     - This ensures you have full context before decomposing the research
 
-2. **Analyze and decompose the research question:**
+2. **Determine the compatibility posture:**
+    - Before decomposing the research request, identify whether this project must preserve backward compatibility for real downstream users.
+    - If the user explicitly allows breaking changes, public API changes, cleanup, or says there are no real users/downstream dependencies, set `breaking_changes_allowed: true`.
+    - If the user mentions production users, published APIs, downstream consumers, migration safety, or compatibility requirements, set `breaking_changes_allowed: false`.
+    - If the posture is not inferable from the request, ask the user once before continuing, using the available structured question tool when possible.
+    - Carry this posture into the research plan, every sub-agent prompt, the final research document frontmatter, and the `## Compatibility Context` section.
+    - When `breaking_changes_allowed: true`, document existing legacy behavior, compatibility shims, optional flags, and public APIs as current state, not as constraints future specs must preserve unless the user explicitly asks for preservation.
+    - When `breaking_changes_allowed: false`, document public APIs, compatibility-sensitive surfaces, downstream callers, migration constraints, and behavior that future work must preserve.
+
+3. **Analyze and decompose the research question:**
     - Break the research question down into composable research areas
     - Take time to ultrathink about the underlying patterns, connections, and architectural implications the user might be seeking
     - Identify specific components, patterns, or concepts to investigate
     - Create a research plan using TodoWrite to track all subtasks
+    - Include the compatibility posture in the plan so later synthesis and spec creation inherit the same constraint.
     - Consider which directories, files, or architectural patterns are relevant
 
-3. **Spawn parallel sub-agent tasks:**
+4. **Spawn parallel sub-agent tasks:**
     - Create multiple Task agents to research different aspects concurrently
     - We now have specialized agents that know how to do specific research tasks:
 
@@ -52,7 +62,7 @@ The user's research question/request is: **$ARGUMENTS**
 
     **For online search:**
     - VERY IMPORTANT: In case you discover external libraries as dependencies, use the **codebase-online-researcher** agent for external documentation and resources
-        - The agent fetches live web content using the **browser-use** skill (or `bunx browser-use` / `curl`). Instruct it to apply the token-efficient fetch order: (1) try `curl https://<site>/llms.txt` for an AI-friendly index (see [llmstxt.org](https://llmstxt.org/llms.txt)), (2) try `curl <url> -H "Accept: text/markdown"` to get pre-converted Markdown (supported on Cloudflare-hosted docs via [Markdown for Agents](https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents/)), (3) fall back to HTML parsing via `browser-use`
+        - The agent fetches live web content using the **browser** skill's `browse` CLI (or `npx browse` / `curl`). Instruct it to apply the token-efficient fetch order: (1) try `curl https://<site>/llms.txt` for an AI-friendly index (see [llmstxt.org](https://llmstxt.org/llms.txt)), (2) try `curl <url> -H "Accept: text/markdown"` to get pre-converted Markdown (supported on Cloudflare-hosted docs via [Markdown for Agents](https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents/)), (3) fall back to HTML parsing via `browse`
         - Instruct the agent to return LINKS with their findings and INCLUDE those links in the research document
         - The agent should persist reusable source documents under `research/web/<YYYY-MM-DD>-<kebab-case-topic>.md` (with frontmatter noting `source_url`, `fetched_at`, and `fetch_method`) so future research can reuse them without re-fetching
         - Output directory for the synthesized research artifact: `research/docs/`
@@ -67,8 +77,9 @@ The user's research question/request is: **$ARGUMENTS**
     - Each agent knows its job - just tell it what you're looking for
     - Don't write detailed prompts about HOW to search - the agents already know
     - Remind agents they are documenting, not evaluating or improving
+    - Include `breaking_changes_allowed: true` or `breaking_changes_allowed: false` in each sub-agent prompt so compatibility-sensitive findings are documented with the right posture.
 
-4. **Wait for all sub-agents to complete and synthesize:**
+5. **Wait for all sub-agents to complete and synthesize:**
     - IMPORTANT: Wait for ALL sub-agent tasks to complete before proceeding
     - Compile all sub-agent results (both codebase and research findings)
     - Prioritize live codebase findings as primary source of truth
@@ -79,7 +90,7 @@ The user's research question/request is: **$ARGUMENTS**
     - Answer the user's research question with concrete evidence
     - **If findings reveal the original question was misframed** (e.g., the system works differently than assumed, or the components don't exist where expected), flag this to the user before finalizing the document. This is valuable signal — don't bury it.
 
-5. **Generate research document:**
+6. **Generate research document:**
     - Follow the directory structure for research documents:
 
 ```
@@ -117,6 +128,8 @@ research/
     status: complete
     last_updated: !`date '+%Y-%m-%d'`
     last_updated_by: [Researcher name]
+    breaking_changes_allowed: [true or false]
+    compatibility_context: "[Short explanation of downstream-user/API compatibility posture]"
     ---
 
     # Research
@@ -125,6 +138,10 @@ research/
 
     [Original user query]
 
+    ## Compatibility Context
+
+    [State whether breaking changes are allowed. If true, note that existing compatibility shims, optional flags, legacy APIs, and public APIs are documented as current state rather than preservation constraints. If false, summarize compatibility-sensitive surfaces, downstream users/callers, migration constraints, and behavior future work must preserve.]
+
     ## Summary
 
     [High-level documentation of what was found, answering the user's question by describing what exists]
@@ -167,19 +184,19 @@ research/
     [Any areas that need further investigation]
     ```
 
-1. **Add GitHub permalinks (if applicable):**
+7. **Add GitHub permalinks (if applicable):**
     - Check if on main branch or if commit is pushed: `git branch --show-current` and `git status`
     - If on main/master or pushed, generate GitHub permalinks:
         - Get repo info: `gh repo view --json owner,name`
         - Create permalinks: `https://github.com/{owner}/{repo}/blob/{commit}/{file}#L{line}`
     - Replace local file references with permalinks in the document
 
-2. **Present findings:**
+8. **Present findings:**
     - Present a concise summary of findings to the user
     - Include key file references for easy navigation
     - Ask if they have follow-up questions or need clarification
 
-3. **Handle follow-up questions:**
+9. **Handle follow-up questions:**
 
 - If the user has follow-up questions, append to the same research document
 - Update the frontmatter fields `last_updated` and `last_updated_by` to reflect the update
@@ -207,10 +224,12 @@ research/
 - **REMEMBER**: Document what IS, not what SHOULD BE
 - **NO RECOMMENDATIONS**: Only describe the current state of the codebase
 - **File reading**: Always read mentioned files FULLY (no limit/offset) before spawning sub-tasks
+- **Compatibility posture**: Always determine `breaking_changes_allowed` before decomposing the question. This is a single project/research posture, not a request to add compatibility flags. Use it to document whether old APIs and shims are constraints for future work.
 - **Critical ordering**: Follow the numbered steps exactly
     - ALWAYS read mentioned files first before spawning sub-tasks (step 1)
-    - ALWAYS wait for all sub-agents to complete before synthesizing (step 4)
-    - ALWAYS gather metadata before writing the document (step 5 before step 6)
+    - ALWAYS determine compatibility posture before decomposing the question (step 2)
+    - ALWAYS wait for all sub-agents to complete before synthesizing (step 5)
+    - ALWAYS gather metadata before writing the document (as part of step 6)
     - NEVER write the research document with placeholder values
 
 - **Frontmatter consistency**:

package/dist/builtin/workflows/src/extension/index.ts

@@ -1795,7 +1795,11 @@ export function makeExecuteWorkflowTool(
         const isPaused =
           run?.status === "paused" ||
           (run?.stages.some((s) => s.status === "paused") ?? false);
-        if (!isPaused && run?.status === "failed" && run.endedAt !== undefined && run.resumable !== false) {
+        const isResumableContinuation = run !== undefined && !isPaused && (
+          (run.status === "failed" && run.endedAt !== undefined && run.resumable !== false) ||
+          (run.endedAt === undefined && run.resumable === true && run.failureRecoverability === "recoverable")
+        );
+        if (isResumableContinuation) {
           const continuation = activeRuntime.resumeFailedRun(stageRunId, stage.stageId, { policy });
           return {
             action: "resume",
@@ -3133,7 +3137,11 @@ function factory(pi: ExtensionAPI): void {
       const isPaused =
         run?.status === "paused" ||
         (run?.stages.some((s) => s.status === "paused") ?? false);
-      if (!isPaused && run?.status === "failed" && run.endedAt !== undefined && run.resumable !== false) {
+      const isResumableContinuation = run !== undefined && !isPaused && (
+        (run.status === "failed" && run.endedAt !== undefined && run.resumable !== false) ||
+        (run.endedAt === undefined && run.resumable === true && run.failureRecoverability === "recoverable")
+      );
+      if (isResumableContinuation) {
         const continuation = runtimeForContext(ctx).resumeFailedRun(stageRunId, stageId, { policy });
         if (continuation.ok) {
           print(continuation.message);

package/dist/builtin/workflows/src/extension/runtime.ts

@@ -44,6 +44,7 @@ import {
 import { validateWorkflowModels } from "../runs/shared/model-fallback.js";
 import { runDetached } from "../runs/background/runner.js";
 import type { JobTracker } from "../runs/background/job-tracker.js";
+import { appendRunEnd } from "../shared/persistence-session-entries.js";
 import { classifyWorkflowFailure } from "../shared/workflow-failures.js";
 
 // ---------------------------------------------------------------------------
@@ -389,13 +390,39 @@ export function createExtensionRuntime(opts: ExtensionRuntimeOpts = {}): Extensi
     return { ok: true, stageId: failedStageId };
   }
 
+  function finalizeResumedActiveBlockedSourceRun(source: RunSnapshot, continuationRunId: string): void {
+    const errorMessage = source.error ?? source.failureMessage ?? `workflow resumed in new run ${continuationRunId}`;
+    const metadata = {
+      ...(source.failureKind !== undefined ? { failureKind: source.failureKind } : {}),
+      ...(source.failureCode !== undefined ? { failureCode: source.failureCode } : {}),
+      failureRecoverability: "non_recoverable",
+      failureDisposition: "terminal_killed",
+      ...(source.failureMessage !== undefined ? { failureMessage: source.failureMessage } : {}),
+      ...(source.failedStageId !== undefined ? { failedStageId: source.failedStageId } : {}),
+      resumable: false,
+      ...(source.retryAfterMs !== undefined ? { retryAfterMs: source.retryAfterMs } : {}),
+    } as const;
+    const recorded = activeStore.recordRunEnd(source.id, "killed", undefined, errorMessage, metadata);
+    if (recorded && persistence !== undefined) {
+      appendRunEnd(persistence, {
+        runId: source.id,
+        status: "killed",
+        error: errorMessage,
+        ...metadata,
+        ts: Date.now(),
+      });
+    }
+  }
+
   function resumeFailedRun(sourceRunId: string, stageId?: string, options?: RuntimeDispatchOptions): ResumeFailedRunResult {
     const source = activeStore.runs().find((run) => run.id === sourceRunId);
     if (source === undefined) {
       return { ok: false, reason: "run_not_found", message: `run not found: ${sourceRunId}` };
     }
-    if (source.status !== "failed" || source.endedAt === undefined || source.resumable === false) {
-      return { ok: false, reason: "not_resumable", message: `run ${sourceRunId} is not a failed resumable workflow run` };
+    const isTerminalFailedResumable = source.status === "failed" && source.endedAt !== undefined && source.resumable !== false;
+    const isActiveBlockedResumable = source.endedAt === undefined && source.resumable === true && source.failureRecoverability === "recoverable";
+    if (!isTerminalFailedResumable && !isActiveBlockedResumable) {
+      return { ok: false, reason: "not_resumable", message: `run ${sourceRunId} is not a resumable workflow run` };
     }
     const def = registry.get(source.name);
     if (def === undefined) {
@@ -415,12 +442,17 @@ export function createExtensionRuntime(opts: ExtensionRuntimeOpts = {}): Extensi
       ...runOptions({ workflow: def.name, inputs: sourceInputs }, options?.policy),
       continuation: { source, resumeFromStageId: resolvedStage.stageId },
     });
+    if (isActiveBlockedResumable) {
+      finalizeResumedActiveBlockedSourceRun(source, accepted.runId);
+    }
     return {
       ok: true,
       runId: accepted.runId,
       sourceRunId: source.id,
       resumeFromStageId: resolvedStage.stageId,
-      message: `Resuming failed workflow "${def.name}" from run ${source.id.slice(0, 8)} at stage ${resolvedStage.stageId.slice(0, 8)} (new run ${accepted.runId}).`,
+      message: isActiveBlockedResumable
+        ? `Resuming blocked workflow "${def.name}" from run ${source.id.slice(0, 8)} at stage ${resolvedStage.stageId.slice(0, 8)} (new run ${accepted.runId}).`
+        : `Resuming failed workflow "${def.name}" from run ${source.id.slice(0, 8)} at stage ${resolvedStage.stageId.slice(0, 8)} (new run ${accepted.runId}).`,
     };
   }
 

package/dist/builtin/workflows/src/extension/wiring.ts

@@ -226,7 +226,19 @@ async function createTestAgentSession(_options?: CreateAgentSessionOptions): Pro
       return { cancelled: true };
     },
     async compact(): ReturnType<StageSessionRuntime["compact"]> {
-      return { summary: "", firstKeptEntryId: "", tokensBefore: 0 };
+      return {
+        promptVersion: 1,
+        deletedTargets: [],
+        protectedEntryIds: [],
+        stats: {
+          objectsBefore: 0,
+          objectsAfter: 0,
+          objectsDeleted: 0,
+          tokensBefore: 0,
+          tokensAfter: 0,
+          percentReduction: 0,
+        },
+      };
     },
     abortCompaction(): void {},
     async abort(): Promise<void> {},

package/dist/builtin/workflows/src/runs/background/status.ts

@@ -82,6 +82,14 @@ export interface RunDetail {
   readonly stages: readonly RunSnapshot["stages"][number][];
   readonly result?: WorkflowOutputValues;
   readonly error?: string;
+  readonly failureKind?: RunSnapshot["failureKind"];
+  readonly failureCode?: RunSnapshot["failureCode"];
+  readonly failureRecoverability?: RunSnapshot["failureRecoverability"];
+  readonly failureDisposition?: RunSnapshot["failureDisposition"];
+  readonly failedStageId?: string;
+  readonly resumable?: boolean;
+  readonly retryAfterMs?: number;
+  readonly blockedAt?: number;
 }
 
 export type InspectRunResult =
@@ -146,11 +154,26 @@ export function killRun(
   const previousStatus = run.status;
 
   // Abort active executor (no-op if not registered)
-  opts?.cancellation?.abort(runId, "workflow killed");
-
-  const recorded = activeStore.recordRunEnd(runId, "killed", undefined, "workflow killed");
+  const errorMessage = "workflow killed";
+  opts?.cancellation?.abort(runId, errorMessage);
+
+  const metadata = {
+    failureKind: "cancelled",
+    failureCode: "cancelled",
+    failureRecoverability: "non_recoverable",
+    failureDisposition: "terminal_killed",
+    failureMessage: errorMessage,
+    resumable: false,
+  } as const;
+  const recorded = activeStore.recordRunEnd(runId, "killed", undefined, errorMessage, metadata);
   if (recorded && opts?.persistence) {
-    appendRunEnd(opts.persistence, { runId, status: "killed", ts: Date.now() });
+    appendRunEnd(opts.persistence, {
+      runId,
+      status: "killed",
+      error: errorMessage,
+      ...metadata,
+      ts: Date.now(),
+    });
   }
 
   return { ok: true, runId, previousStatus };
@@ -247,14 +270,29 @@ export function resumeRun(
   // Return a deep copy of the snapshot for safe consumption
   const snapshot = structuredClone(run);
   const resumedCopy = structuredClone(resumed);
-  if (run.status === "failed" && run.endedAt !== undefined && run.resumable === false) {
+  if (run.status === "killed" || run.resumable === false) {
     return {
       ok: true,
       runId,
       snapshot,
       resumed: resumedCopy,
       mode: "not_resumable",
-      message: "This failed workflow is not resumable; inspect the snapshot and rerun the workflow when ready.",
+      message: "This workflow is not resumable; inspect the snapshot and start a new workflow run when ready.",
+    };
+  }
+  if (
+    run.endedAt === undefined &&
+    run.resumable === true &&
+    run.failureRecoverability === "recoverable" &&
+    run.failedStageId !== undefined
+  ) {
+    return {
+      ok: true,
+      runId,
+      snapshot,
+      resumed: resumedCopy,
+      mode: resumedCopy.length > 0 ? "paused" : "snapshot",
+      message: `Workflow is blocked on a recoverable ${run.failureCode ?? run.failureKind ?? "workflow"} failure at stage ${run.failedStageId}; retry/resume after the issue clears.`,
     };
   }
   return {
@@ -441,6 +479,14 @@ export function inspectRun(
     stages: expandedStages.map((stage) => structuredClone(stage)),
     result: copy.result,
     error: copy.error,
+    failureKind: copy.failureKind,
+    failureCode: copy.failureCode,
+    failureRecoverability: copy.failureRecoverability,
+    failureDisposition: copy.failureDisposition,
+    failedStageId: copy.failedStageId,
+    resumable: copy.resumable,
+    retryAfterMs: copy.retryAfterMs,
+    blockedAt: copy.blockedAt,
   };
 
   return { ok: true, runId: copy.id, detail };