@bastani/atomic 0.9.16-alpha.2 → 0.9.16-alpha.3

package/dist/builtin/workflows/src/extension/workflow-model-catalog.ts

@@ -1,24 +0,0 @@
-import type { CreateAgentSessionOptions } from "@bastani/atomic";
-import type { WorkflowModelCatalogPort, WorkflowModelInfo } from "../shared/types.js";
-import type { PiModelContext } from "./public-types.js";
-
-export function workflowModelCatalogFromContext(ctx?: PiModelContext): WorkflowModelCatalogPort | undefined {
-	if (ctx?.modelRegistry === undefined && ctx?.model === undefined) return undefined;
-	return {
-		listModels: async (): Promise<readonly WorkflowModelInfo[]> => {
-			const available = ctx.modelRegistry?.getAvailable() ?? (ctx.model === undefined ? [] : [ctx.model]);
-			return available.map((model) => ({
-				provider: String(model.provider),
-				id: model.id,
-				fullId: `${String(model.provider)}/${model.id}`,
-				model: model as NonNullable<CreateAgentSessionOptions["model"]>,
-			}));
-		},
-		...(ctx.model !== undefined
-			? {
-					currentModel: ctx.model as NonNullable<CreateAgentSessionOptions["model"]>,
-					preferredProvider: String(ctx.model.provider),
-				}
-			: {}),
-	};
-}

package/dist/builtin/workflows/src/extension/workflow-module-loader.ts

@@ -1,162 +0,0 @@
-/**
- * Shared workflow module loading helpers.
- *
- * Discovery loads user-authored workflow files through this jiti instance so
- * TypeScript/ESM/CJS semantics and the @bastani/workflows virtual SDK alias
- * stay consistent.
- */
-
-import { createJiti } from "jiti/static";
-import * as typeboxModule from "typebox";
-import adversarialVerification from "../../builtin/adversarial-verification.js";
-import classifyAndAct from "../../builtin/classify-and-act.js";
-import fanOutAndSynthesize from "../../builtin/fan-out-and-synthesize.js";
-import generateAndFilter from "../../builtin/generate-and-filter.js";
-import goal from "../../builtin/goal.js";
-import loopUntilDone from "../../builtin/loop-until-done.js";
-import openClaudeDesign from "../../builtin/open-claude-design.js";
-import ralph from "../../builtin/ralph.js";
-import tournament from "../../builtin/tournament.js";
-import { isBrandedWorkflowDefinition } from "../authoring/workflow.js";
-import * as workflowsSdkSurface from "../sdk-surface.js";
-import { validateWorkflowBudget } from "../shared/budget.js";
-
-const WORKFLOWS_MODULE_SPECIFIER = "@bastani/workflows";
-const WORKFLOWS_BUILTIN_MODULE_SPECIFIER = `${WORKFLOWS_MODULE_SPECIFIER}/builtin`;
-const TYPEBOX_MODULE_SPECIFIER = "typebox";
-// Keep this in sync with index.ts through sdk-surface.ts.
-const WORKFLOWS_SDK_MODULE: Record<string, unknown> = {
-	...workflowsSdkSurface,
-};
-const WORKFLOWS_BUILTIN_MODULE: Record<string, unknown> = {
-	adversarialVerification,
-	classifyAndAct,
-	fanOutAndSynthesize,
-	generateAndFilter,
-	goal,
-	loopUntilDone,
-	openClaudeDesign,
-	ralph,
-	tournament,
-};
-const TYPEBOX_MODULE: Record<string, unknown> = {
-	...typeboxModule,
-};
-const WORKFLOWS_VIRTUAL_MODULES: Record<string, unknown> = {
-	[WORKFLOWS_MODULE_SPECIFIER]: WORKFLOWS_SDK_MODULE,
-	[WORKFLOWS_BUILTIN_MODULE_SPECIFIER]: WORKFLOWS_BUILTIN_MODULE,
-	[TYPEBOX_MODULE_SPECIFIER]: TYPEBOX_MODULE,
-	[`${WORKFLOWS_BUILTIN_MODULE_SPECIFIER}/adversarial-verification`]: { default: adversarialVerification },
-	[`${WORKFLOWS_BUILTIN_MODULE_SPECIFIER}/classify-and-act`]: { default: classifyAndAct },
-	[`${WORKFLOWS_BUILTIN_MODULE_SPECIFIER}/fan-out-and-synthesize`]: { default: fanOutAndSynthesize },
-	[`${WORKFLOWS_BUILTIN_MODULE_SPECIFIER}/generate-and-filter`]: { default: generateAndFilter },
-	[`${WORKFLOWS_BUILTIN_MODULE_SPECIFIER}/goal`]: { default: goal },
-	[`${WORKFLOWS_BUILTIN_MODULE_SPECIFIER}/loop-until-done`]: { default: loopUntilDone },
-	[`${WORKFLOWS_BUILTIN_MODULE_SPECIFIER}/open-claude-design`]: { default: openClaudeDesign },
-	[`${WORKFLOWS_BUILTIN_MODULE_SPECIFIER}/ralph`]: { default: ralph },
-	[`${WORKFLOWS_BUILTIN_MODULE_SPECIFIER}/tournament`]: { default: tournament },
-};
-
-const workflowModuleLoader = createJiti(import.meta.url, {
-	moduleCache: false,
-	// Keep workflow-file import semantics deterministic: jiti owns .ts/.js/.mjs/.cjs
-	// resolution instead of handing some imports back to native import().
-	tryNative: false,
-	// Resolve the @bastani/workflows SDK (and its builtin submodules) to in-memory
-	// surfaces in every runtime. This mirrors the compiled bun binary path and
-	// keeps discovery fast: aliasing the SDK to its on-disk package re-evaluated
-	// the entire SDK module graph once per workflow file (moduleCache stays false),
-	// which scaled discovery to multiple seconds on projects with many workflow
-	// files. Workflow files themselves are still evaluated fresh from disk, so
-	// `/workflow reload` continues to observe edits.
-	virtualModules: WORKFLOWS_VIRTUAL_MODULES,
-});
-
-function materializeModuleObject(mod: object): Record<string, unknown> {
-	const materialized: Record<string, unknown> = {};
-
-	// jiti's callable API can return an interop namespace proxy. Its own property
-	// descriptors contain the authored export values, but property access may apply
-	// default-export conveniences (and even expose a throwing inherited `then`
-	// getter for `export default null`). Copy own descriptors into a plain object
-	// so candidate collection sees the exact authored exports.
-	for (const key of Object.getOwnPropertyNames(mod)) {
-		const descriptor = Object.getOwnPropertyDescriptor(mod, key);
-		if (descriptor === undefined) continue;
-
-		const value = "value" in descriptor ? descriptor.value : descriptor.get?.call(mod);
-		Object.defineProperty(materialized, key, {
-			value,
-			enumerable: descriptor.enumerable,
-			configurable: true,
-			writable: true,
-		});
-	}
-
-	return materialized;
-}
-
-function normalizeWorkflowModule(mod: unknown): Record<string, unknown> {
-	if (mod !== null && typeof mod === "object") {
-		return materializeModuleObject(mod);
-	}
-	// CJS/default interop can return the exported value directly; wrap it so the
-	// candidate collector can handle it the same way as an ESM default export.
-	return { default: mod };
-}
-
-export interface WorkflowModuleCandidate {
-	readonly value: unknown;
-	readonly exportKey: string;
-}
-
-export function validateWorkflowDefinitionShape(value: unknown): string | null {
-	if (value === null || typeof value !== "object") {
-		return "export is not an object";
-	}
-	const d = value as Record<string, unknown>;
-
-	if (d.__piWorkflow !== true) {
-		return "missing or incorrect __piWorkflow sentinel (expected true); export a workflow from workflow({...})";
-	}
-	if (!isBrandedWorkflowDefinition(value)) {
-		return "workflow definition is not produced by workflow({...}); hand-rolled __piWorkflow objects are not supported";
-	}
-	if (typeof d.name !== "string" || (d.name as string).trim().length === 0) {
-		return "name must be a non-empty string";
-	}
-	if (typeof d.normalizedName !== "string" || (d.normalizedName as string).trim().length === 0) {
-		return "normalizedName must be a non-empty string";
-	}
-	if (typeof d.run !== "function") {
-		return "run must be a function";
-	}
-	if (d.budget !== undefined) {
-		const reason = validateWorkflowBudget(d.budget, "budget");
-		if (reason !== null) return reason;
-	}
-	return null;
-}
-
-export function loadWorkflowModule(filePath: string): Record<string, unknown> {
-	return normalizeWorkflowModule(workflowModuleLoader(filePath));
-}
-
-export function collectWorkflowModuleCandidates(mod: Record<string, unknown>): WorkflowModuleCandidate[] {
-	const candidates: WorkflowModuleCandidate[] = [];
-
-	// Default export first (RFC §5.12: check mod.default before named exports)
-	if ("default" in mod && mod.default !== undefined) {
-		candidates.push({ value: mod.default, exportKey: "default" });
-	}
-
-	// Then all named exports (a file may export multiple workflow definitions)
-	for (const [key, val] of Object.entries(mod)) {
-		if (key === "default") continue;
-		if (val !== undefined) {
-			candidates.push({ value: val, exportKey: key });
-		}
-	}
-
-	return candidates;
-}

package/dist/builtin/workflows/src/extension/workflow-policy.ts

@@ -1,13 +0,0 @@
-import {
-	INTERACTIVE_WORKFLOW_POLICY,
-	NON_INTERACTIVE_WORKFLOW_POLICY,
-	type WorkflowExecutionPolicy,
-} from "../shared/types.js";
-
-export const WORKFLOW_NON_INTERACTIVE_MESSAGE =
-	"Workflows are policy-gated in non-interactive (-p) mode; deterministic workflows can run headlessly while runtime human input remains unavailable.";
-
-export function workflowPolicyFromContext(ctx?: { readonly hasUI?: boolean }): WorkflowExecutionPolicy {
-	if (ctx?.hasUI === false) return NON_INTERACTIVE_WORKFLOW_POLICY;
-	return INTERACTIVE_WORKFLOW_POLICY;
-}

package/dist/builtin/workflows/src/extension/workflow-ports.ts

@@ -1,45 +0,0 @@
-import type { WorkflowMcpPort, WorkflowPersistencePort } from "../shared/types.js";
-import { clearMcpScope, type PiEventBus, type PiMcpExtensionAPI, setMcpScope } from "./mcp.js";
-import type { ExtensionAPI } from "./public-types.js";
-
-export function makePersistencePort(pi: ExtensionAPI, persistRuns: boolean): WorkflowPersistencePort | undefined {
-	if (!persistRuns) return undefined;
-	if (typeof pi.appendEntry !== "function") return undefined;
-	const port: WorkflowPersistencePort = {
-		appendEntry: (type, payload) => pi.appendEntry!(type, payload),
-	};
-	if (typeof pi.setLabel === "function") {
-		port.setLabel = (entryId, label) => pi.setLabel!(entryId, label);
-	}
-	if (typeof pi.appendCustomMessageEntry === "function") {
-		port.appendCustomMessageEntry = (content, meta) => pi.appendCustomMessageEntry!(content, meta);
-	}
-	return port;
-}
-
-export function makeMcpPort(pi: ExtensionAPI): WorkflowMcpPort | undefined {
-	if (typeof pi.events?.emit !== "function") return undefined;
-	const piForMcp: PiMcpExtensionAPI = {
-		events: { emit: pi.events.emit as PiEventBus["emit"] },
-	};
-	return {
-		setScope(stageId: string, allow: string[] | null, deny: string[] | null) {
-			try {
-				setMcpScope(piForMcp, {
-					stageId,
-					allow: allow ?? undefined,
-					deny: deny ?? undefined,
-				});
-			} catch {
-				// A workflow can outlive its extension instance; scope events are advisory.
-			}
-		},
-		clearScope(stageId: string) {
-			try {
-				clearMcpScope(piForMcp, stageId);
-			} catch {
-				// A workflow can outlive its extension instance; scope events are advisory.
-			}
-		},
-	};
-}

package/dist/builtin/workflows/src/extension/workflow-prompts.ts

@@ -1,73 +0,0 @@
-export const WORKFLOW_TOOL_DESCRIPTION =
-	"Run named builtin, project, user, or package workflows; custom definitions may import reusable project/package workflows or builtin definitions from @bastani/workflows/builtin and nest them with ctx.workflow(...), including deeper composition within the configured maxDepth; " +
-	"when workflow execution fits but another shape would better achieve the task, author a custom TypeScript workflow({...}) inline with normal coding tools, reload it, and run it; after successfully creating and reloading a newly authored custom workflow, report the folder containing its generated code as 'Custom workflow created. You can inspect its code at: <workflow-folder-path>'; do this only for newly created custom workflows, never builtin or pre-existing workflows; " +
-	"discover with list/get/inputs/models, list session runs with status (no runId; statusFilter narrows the list), inspect status/stages/stage details, " +
-	"send prompt answers or steering only while the root workflow is nonterminal, pause/resume/interrupt/quit runs, and reload workflow resources. " +
-	"For action 'run' and 'resume', budget accepts per-field duration, token, cost, and warning overrides; fields resolve over the workflow declaration and config, and 0 disables a field. " +
-	"For primitive prompt answers, use booleans or the documented confirm labels, exact case-insensitive select labels or 1-based indexes, and text strings for input/editor; an invalid answer remains pending and returns guidance instead of choosing a default. " +
-	"For large stage handoffs, write context to files/artifacts, pass paths via reads, and prompt downstream agents to 'Read the file at <path>...' instead of injecting large previous text. " +
-	"Wrap critical parts of run inputs and steering messages in <keepContext>...</keepContext> so compaction preserves them verbatim in the stages that inherit them; tag role constraints, prohibitions, must-hold criteria, and identifiers, not background or bulk reference material. " +
-	"For transcripts, prefer status/stages/stage to get sessionFile/transcriptPath, " +
-	"quote the exact path without rewriting separators (Windows backslashes are valid), " +
-	"then search it with rg/grep and read small ranges; transcript is path-only by default when sessionFile/transcriptPath exists, explicit tail/limit returns bounded previews, and missing transcript paths fall back to a small preview. " +
-	"Use action 'models' to inspect models in the configured catalog; the result is a configured-auth snapshot showing what's present in the registry with configured authentication, not proof of credentials, entitlements, OAuth freshness, or live provider access. " +
-	"When authoring a workflow that should dynamically select a model, first call workflow({ action: 'models' }) to inspect the configured catalog, then select from the returned provider/id entries considering the isCurrent marker and available thinking levels.";
-
-export const DEFAULT_PROMPT_GUIDANCE: string[] = [
-	`**Workflows**: Treat workflows as the default execution path for any non-trivial task and for any request that has inherent structure plus an objective you can make verifiable. Use the \`workflow\` tool for existing named workflows; when the task needs a graph that is not installed, author a custom TypeScript \`workflow({...})\` inline with normal coding tools, reload workflow resources, and run it.
-  - Workflow fit check: prefer a workflow for implementation, build, debug/diagnosis, bug-fix, migration, new-feature, scoped multi-file, or docs/code changes with validation; and whenever there are multiple steps, dependencies, handoffs, uncertainty, review/validation needs, long-running work, measurable done criteria, or an outcome that needs evidence.
-  - Treat loop or stop-condition wording as a strong workflow signal, especially "do X until Y", "repeat until", "iterate until", "review/fix until passing", "run checks and fix until green", "keep going until done", or any prompt that names an approval gate or evidence requirement.
-  - Do not force-fit an installed workflow. When another graph better matches the task, write a task-specific TypeScript workflow inline. Rich custom workflows may use deterministic branching, dynamic fan-out, child workflows, artifacts, structured outputs, human-in-the-loop prompts, gates, retries, and explicit stop conditions.
-  - Before launching any workflow for a non-trivial task, perform a short workflow-architecture pass. Derive implementation lifecycle needs, whole-codebase research needs, independent slices, competing strategies, exact API/type/build contracts, schema or generated-artifact contracts, state transitions/lifecycle behavior, deterministic stop conditions, and required evidence. Enumerate implementation slices in this same pass, not a second planning ritual; give each slice its own objective, acceptance criteria, and gates, and require each to leave a buildable, testable repository state before the next slice. Use a compact internal coverage matrix: \`requirement/risk | required evidence | workflow/stage that produces it | gap\`. Add the topology row \`acyclic topology | node/edge sketch for branches and loops | architecture pass | unresolved back-edge\`. Unresolved material rows or back-edges must change the graph before launch.
-  - In that architecture pass, sketch each branch, loop, and nested workflow boundary. Identify which stages repeat, require distinct tracked work for every iteration, name the current frontier before each repeat, reject self-edges and ancestor edges, compose nested workflows through \`ctx.workflow(...)\` boundaries rather than recursive \`run\` invocation, and preserve stable per-iteration identity and call order for resume/replay.
-  - Compare candidate workflows by guarantees, not broad objectives: run one named workflow only when it covers the lifecycle and produces evidence for every material requirement/risk. A generic implementation workflow may cover the lifecycle without covering exact API/type/build contracts, schemas/generated artifacts, state transitions, or domain-specific gates. Do not treat "has reviewers" as proof that a task-specific risk is covered.
-  - Use these routing signals without adding decorative stages: broad repository uncertainty → Fan-out-and-synthesize with repository-focused branches; independent slices → Fan-out-and-synthesize; plausible-but-wrong contract risk → Adversarial verification or a task-specific verification stage; competing architectures or implementations → Generate-and-filter or Tournament; an explicit repeat-until condition → Loop until done; implementation lifecycle → a task-specific worker/reviewer loop; exact API/build/schema requirements → dedicated deterministic gates.
-  - For a request containing several implementation items, enumerate every item before launch and classify it as independent, dependent, or clustered. Inspect stated issue/PR/branch dependencies, whether prerequisites are already merged into each selected base, and likely shared files, API contracts, migrations, generated artifacts, decisions, approvals, and release effects.
-  - Do not infer a cross-item sequence from list order or from "create a PR after" when "after" naturally refers to that item's own implementation/review/check/PR lifecycle. Prove the dependency before serializing independent workflow items; if a material dependency remains unclear after research, ask one grouped clarification.
-  - Run independent implementation items as separate concurrent top-level named workflow runs with bounded concurrency. Give each item its own explicitly supported worktree path, branch, run ID, root lifecycle, and failure boundary, then report an item → run ID → worktree → branch → result/PR map. Compose or sequence only real dependencies; run independent clusters in parallel and preserve ordering inside each cluster.
-  - For a mixed queue with dependent A → B and unrelated C, compose only the A → B dependency cluster. Launch C as its own concurrent top-level named workflow with its own root failure boundary. One real cross-item dependency does not put the whole queue in one parent.
-  - A first item's review, repair, or check failure must not block unrelated items. Keep other top-level runs active, report the failed item separately, and fill an open dispatcher slot when policy permits. Several worktrees inside one sequential root provide checkout isolation, not concurrent top-level execution or independent root failure boundaries.
-  - A first named workflow launch commits the selected execution shape for the turn. For one task, end after the single launch. For an independent queue, issue the complete bounded wave of planned per-item top-level launches before ending the turn; do not casually chain unplanned unrelated launches. Each top-level run keeps an independent root lifecycle and failure boundary. When one task needs multiple capabilities or one dependency cluster needs ordered handoffs, design one custom parent before launch for that task or cluster, import reusable project/package definitions or builtins from \`@bastani/workflows/builtin\`, and compose them with \`ctx.workflow(childDefinition, { inputs, stageName })\`. Keep unrelated queue items out of that parent. Imported children may nest more workflows up to \`maxDepth\`; their stages, HIL prompts, control, durability, and declared outputs remain part of the expanded parent graph and root failure boundary. Pass definitions, not registry-name strings or paths.
-  - Workflow definitions are normal TypeScript modules. Composition examples: nest \`fanOutAndSynthesize\` for repository mapping; wrap \`openClaudeDesign\` with project-specific approval/export stages; or build a reusable user-defined research child and import it into several parent workflows. Map typed inputs and consume only declared outputs.
-  - When plausible-but-wrong behavior is a material risk in an arbitrary task-specific workflow, prefer a bounded evidence-backed adversarial loop. Give a fresh-context grumpy/skeptical-but-fair reviewer the literal objective and require actionable, evidence-backed falsification probes without invented requirements. Have it emit a structured verifier plan containing each exact probe, inputs, command/assertion, expected success condition, and requirement/risk covered.
-  - Support both verifier shapes: for explicit known contracts, author direct task-specific \`ctx.tool(...)\` gates before launch; for risks requiring adversarial discovery, let the model select high-value probes through structured output, then execute the selected compile, test, schema generation/validation, runtime, or artifact-inspection checks authoritatively through durable \`ctx.tool(...)\` calls. Actual tool results—not model self-report—must feed skeptical evaluation, consolidated evidence-backed repair findings, and reruns after the implementation child repairs them.
-  - Define bounded pass, repair, failure, and iteration-limit conditions before launch. Use \`ctx.tool\` for workflow-owned external checks and side effects whose results should be durably checkpointed. Each \`ctx.tool\` call is tracked as a durable, non-chat graph node and may run before, between, after, or without model stages; a tool-only workflow is valid tracked execution; keep pure transformations as ordinary TypeScript, and do not wrap every model-stage action in a tool call.
-  - Choose the cheapest graph that covers every material coverage row without collapsing independently verifiable implementation slices merely to minimize stage count. Avoid decorative composition and duplicated research or review loops. Prefer composing a proven builtin or shared child over copying its prompt/graph.
-  - Before the first launch, state the selected graph, why one broad builtin is sufficient or insufficient, the evidence each major stage produces, and the stop/repair conditions. A simple direct match may use one sentence; a composed graph must briefly name its children and task-specific gates. For a custom adversarial loop, also name the skeptical reviewer, deterministic \`ctx.tool\` verifier gates, how model-selected plans become tool executions, and how failures reach bounded repair.
-  - Before launching an authored workflow, assign every model stage a role, failure cost, primary model, thinking level, and fallback policy. Use the role/risk defaults in the model-selection guide: reserve \`max\` for high-cost-of-error roles such as security, identity, adversarial challenge, and final approval; use \`high\` for demanding codebase mapping, lifecycle analysis, compatibility, planning, synthesis, triage, and repair; use \`medium\` for user-impact review and final reporting; keep deterministic checks as tool nodes with no model call. An explicit user request for a thinking level always wins over these defaults, subject to catalog support. For a mixed workflow, mapping may be \`high\`, approval \`max\`, reporting \`medium\`, and tests tool-only; never assign \`max\` to every model stage without a stage-specific reason.
-  - Print a compact \`Stage | Model | Thinking | Role\` assignment before launch with a short cost/quality rationale for each model stage. Apply the same role/risk policy to every fallback attempt rather than inheriting \`max\` mechanically; choose each primary and fallback level from the configured catalog, and if no selected catalog model supports the role's level, leave the stage unpinned rather than inventing an unsupported level.
-  - Example custom shapes: classify a request and dispatch category-specific stages; fan out per package and synthesize artifact-backed results; decompose one implementation objective into stacked, independently verified slices with a bounded child lifecycle per slice; implement, run fresh-context verifiers, reduce findings, and loop through repairs until approved; generate several plans and filter or tournament-rank them; or rerun checks and fixes until green with a progress ledger and max-iteration escape hatch.
-  - Budget reconnaissance: once workflow fit is clear, keep pre-workflow exploration to a few quick reads that sharpen the objective and validation criteria. Put deep research, upstream/design comparison, and behavior probing inside the workflow. Pass large context through files/artifacts and \`reads\` rather than injecting it into prompts.
-  - Course-correct instead of drifting: after roughly ten exploratory tool calls with no artifact, edit, or commit, or repeated "let me verify one more thing" loops, stop, write findings to a context file, and hand the task to the best-fit named or custom workflow. Sunk inline research transfers through files; it is not a reason to stay inline.
-  - Only skip workflows for tiny, deterministic, low-risk answers or direct edits where stage tracking clearly costs more than it adds, typically a single-file/no-test/no-review change or a simple answer.`,
-	`**Workflow discovery and lifecycle**:
-  - For unfamiliar named workflows, discover with \`action: "list"\`, inspect with \`action: "get"\` or \`action: "inputs"\`, and run with \`action: "run"\`, \`workflow\`, and validated \`inputs\`; do not invent workflow names or input keys.
-  - Wrap critical parts of the \`inputs\` you pass — objective, prompt, acceptance criteria — in \`<keepContext>\` / \`</keepContext>\`. Tagged text survives compaction verbatim regardless of the compression ratio, and stages inherit it because workflows inject your inputs into their prompts. A long stage is compacted repeatedly, and compaction ranks lines individually: a verbose restated objective outlives the one line that bounds it, so a stage can end up executing a coherent but unbounded version of what you asked for. Decide this per launch rather than tagging everything — tag role constraints, prohibitions, must-hold criteria, and identifiers such as a target branch, worktree path, or issue number; leave background, quoted issue text, and reference material untagged and pass bulk through files and \`reads\`. Protected lines count against the keep target rather than raising it, so an over-tagged input makes the evidence stages need compress harder.
-  - Tag steering the same way. A \`send\` amendment is authoritative and stages must carry it forward, but it arrives late in an already-long session and is exactly one short message competing with the whole transcript; \`<keepContext>\` around the requirement keeps it from being compacted away before the stage acts on it.
-  - In interactive chat, named workflow launches run in the background. Run \`/workflow connect <run>\` to see agents working and chat with and steer each stage. Inspection and control calls (\`status\`, \`stages\`, \`stage\`, \`transcript\`, \`send\`, \`pause\`, \`resume\`, \`interrupt\`, \`quit\`) remain available while work runs.
-  - \`workflow send\` is nonterminal-only: once the authoritative root run has completed, failed, skipped, been cancelled or killed, or ended terminal-blocked, start a new workflow if tracked work remains. Proceed inline only when the remaining task is small, deterministic, and low risk. Use explicit \`/workflow attach <run> <stage>\` for user-driven post-mortem chat; it does not resume or modify workflow execution.
-  - Natural-language instructions to create or use a worktree do not enable runner isolation. A named workflow must declare and implement any worktree and feature-branch inputs it supports; inspect its inputs and pass a distinct path and branch for each concurrent item. Reusable \`baseBranch\` binding creates a missing target as a detached checkout from that base or reuses an existing same-repository worktree as-is; neither case checks out a separate feature-branch input.
-  - Once you have started the selected single run or every run in the selected bounded wave, end the current turn and wait for user input or lifecycle notices. Do not use sleep/status polling loops: key start, finish, and failure events arrive automatically. Use targeted \`status\`/\`stages\`/\`stage\` checks only when the user asks or the next step needs them, and use \`send\`/\`pause\`/\`resume\`/\`interrupt\`/\`quit\` only to answer, steer, or honor control requests.
-  - For transcripts, avoid whole-file reads. Get \`sessionFile\`/\`transcriptPath\` from \`stages\` or \`stage\`, preserve the exact path and platform separators, search with \`rg\`/\`grep\`, and read small relevant ranges; use explicit \`tail\` or \`limit\` only for a bounded preview.`,
-	`**Workflow authoring and handoffs**:
-  - When a user asks to create or edit a workflow, clarify only unresolved requirements that materially affect its purpose, inputs, stages, handoffs, validation, success criteria, or starter pattern. Read the workflow docs/examples, implement the TypeScript definition with normal coding tools, reload it, and run representative test inputs before presenting it. Use the create-spec skill when it adds value; it is not mandatory when context is already sufficient.
-  - After creating and reloading a newly authored custom workflow, close the loop by stating the folder containing the workflow file just written, for example \`.atomic/workflows/\`, in this shape: \`Custom workflow created. You can inspect its code at: <workflow-folder-path>\`. Do this only for newly created custom workflows, never builtin or pre-existing workflows.
-  - Keep a small, readable workflow in one entry file. Do not split short one-use prompts, create one file per stage, add wrapper-only modules, hide the graph across files, or use line counts alone as a module boundary.
-  - When a meaningful source boundary improves clarity, reuse, ownership, or testability, keep the graph and control flow in the top-level workflow entry file and extract cohesive concerns such as long or reused prompt builders, shared TypeBox schemas and workflow-specific types, model-policy constants shared by several stages, deterministic helpers with their own testable behavior, or reusable child workflow definitions into a subdirectory below the top-level discovery directory — either one owned by a single workflow or a shared support directory. Project and user discovery scans only top-level \`.ts\`/\`.js\`/\`.mjs\`/\`.cjs\` files in the workflow directory, so those support modules are not scanned as extra top-level workflow candidates; use \`.js\` import extensions from TypeScript source.
-  - When creating or editing a workflow that pins an explicit stage \`model\` or \`fallbackModels\`, consult \`packages/coding-agent/docs/models/model-selection.md\` for role-based recommendations, treating benchmark thinking levels as measurement configurations rather than universal workflow defaults, then call \`workflow({ action: "models" })\` to see the models actually present in the user's configured catalog. Use only the catalog's returned \`fullId\` values as model strings, and append a thinking suffix only when that exact level appears in the entry's \`availableThinkingLevels\`; apply the stage role and failure-cost policy independently to the primary and every fallback; treat an absent or empty \`availableThinkingLevels\` as no suffix support rather than inferring one. If a guide-recommended model for the role is unavailable, try another guide-recommended model that is present in the catalog. If the selected model does not support the role's level, choose another catalog model that does or leave the stage unpinned rather than inventing or silently promoting a level. An explicit user request for a level overrides the role default, but never fabricate an unsupported catalog level. If no recommendation intersects with the catalog, leave the stage unpinned rather than inventing a substitute, and mention the limitation, asking the user only if the workflow requires an explicit model choice. If the catalog is empty, continue with unpinned stages, state that no configured models were returned, and do not fabricate model IDs. Do not inspect or infer credentials, environment variables, auth files, token validity, entitlements, or the reason a model is absent; \`isCurrent\` marks the active selection, not a quality recommendation.
-  - Consult docs/workflows.md and its starter patterns (Classify-and-act, Fan-out-and-synthesize, Adversarial verification, Generate-and-filter, Tournament, Loop until done, and Stacked implementation slices) when designing a stage graph.
-  - Treat workflow composition as a first-class authoring option. Before duplicating stages, inspect reusable workflow modules and builtin exports; import their definitions and invoke them with \`ctx.workflow(...)\`, mapping typed inputs and consuming only declared outputs. Nested workflows can themselves import children, so combine small reusable graphs into a richer parent while respecting \`maxDepth\`.
-  - For implementation objectives, prefer the smallest independently verifiable slice: target roughly 100–500 changed lines between verification points by default, with one reviewable concern that builds and tests on its own. This is a default, not a law: a genuinely atomic change (for example, a mechanical rename across many files or a generated-artifact refresh) stays one slice, and a small objective is not split merely to reach a count.
-  - Decompose those slices during the pre-launch architecture pass, not in a second planning ritual. Run every slice through a child workflow with its own implement/review/repair lifecycle: invoke imported \`goal\`, \`ralph\`, or a task-specific child via \`ctx.workflow(...)\`, rather than making one parent stage own all slices.
-  - Stack implementation slices in order: give each slice an explicit branch input and, before invoking its child, create or check out that named branch in its worktree with a durable \`ctx.tool(...)\` step; \`base_branch\` and \`git_worktree_dir\` alone do not create/check out a feature branch. Slice N+1 must be created from slice N's verified branch, pass that branch as \`base_branch\`, and use a distinct worktree. Verify each slice before proceeding; if a slice fails its gates, stop at the first unverified slice; earlier verified slices remain verified and are reported as such; do not roll them back or continue past the failure.
-  - Atomic \`workflow({ run })\` definitions are imperative, dynamic TypeScript. Discovery validates module loading, imports, and definition shape, including schemas and the \`run\` function, but it does not compile \`run\` into a complete graph or prove acyclicity. Runtime inputs, branches, loops, files, network data, model or human output, helpers, and nested workflows determine the materialized graph during execution.
-  - Cyclic workflow graphs are unsupported. Workflow authors and coding agents MUST NOT create self-edges or dependency edges from the current frontier to an existing ancestor. Every materialized execution topology must remain a DAG. Redesign or stop before launch if a cycle cannot be removed.
-  - Bounded loops must create distinct tracked work for every iteration; never reopen an ancestor below its downstream work. Stacked implementation slices are unrolled, not looped: each slice gets a fresh child boundary and distinct tracked nodes, and no slice may add an edge back to the current frontier, itself, or an ancestor. If a retained session receives follow-up without new dependency work, keep it as non-topological activity metadata rather than adding a back-edge. Before launch, sketch nodes and dependencies for every branch and loop and reject any proposed parent edge to the node itself or an ancestor.
-  - Treat dynamic graph validation during execution, replay, and DBOS hydration as the authoritative cycle boundary. If runtime topology code changes, require incremental edge checks and DBOS hydration validation; prompt guidance and TypeScript types cannot replace those runtime checks.
-  - Every workflow invocation automatically receives one stable, non-default Intercom group. Intercom-capable stages inherit it, nested workflows keep the top-level invocation group, and subagents inherit their launching stage's group. Do not mint or thread group names through ordinary workflow definitions. Use an explicit \`group\` only for an intentional override: a named group or \`group: true\` creates a subgroup, while \`group: "default"\` opts into the shared default group. Stages without Intercom access receive no group, and \`contact_supervisor\` still crosses group boundaries for authorized escalation.
-  - Prefer \`ctx.tool(name, args, fn)\` for workflow-owned TypeScript operations with side effects, such as filesystem writes, network mutations, and external API actions. It creates a tracked, non-attachable durable graph node before invoking \`fn\`; it may be used before, between, after, or without model stages. A completed \`ctx.tool\` call is durably checkpointed with its serializable result, so resume replays that result without rerunning \`fn\`. For checks that may fail during a bounded repair loop, opt into \`failureMode: "return"\`, branch on the typed outcome, and pass only the needed error fields to the repair stage or artifact yourself; Atomic does not inject failure evidence into later prompts. Retries do not bound a hung callback, so every \`ctx.tool\` callback that starts a child process or performs network I/O MUST set an explicit positive finite \`timeoutMs\` and forward the supplied \`signal\` to cancellable work. A timeout applies per attempt, aborts that attempt's signal, and gives retries a fresh deadline and signal. Cancellation and storage faults still throw. Keep pure computation and side-effect-free transformations as ordinary TypeScript. Do not wrap agent-stage internals or every function call indiscriminately; this rule applies to side effects orchestrated directly by the workflow definition.
-  - Pass large stage context through files/artifacts and \`reads\` with an explicit \`Read the file at <path>...\` prompt rather than large \`previous\` payloads or injected session history.
-  - Wrap critical stage-prompt content in \`<keepContext>\` / \`</keepContext>\`. Tagged content survives compression verbatim regardless of the compression ratio, and every line of the span including the tag lines is protected. A long-running stage will be compacted, and compaction ranks lines individually: an objective is verbose and restated while the constraint that narrows it is usually one line, so the constraint is the cheaper deletion and what survives reads as broader permission than intended. Tag role constraints that bound a stage to part of the work, acceptance criteria and immutable contracts, explicit prohibitions, and identifiers a stage must not lose such as a target branch, worktree path, or run ID. Do not tag bulk context: protected lines count against the keep target rather than raising it, so a large protected span makes the surrounding transcript compress harder — tag the constraint, not the material it applies to.
-  - Separate implementation/review acceptance from explicitly authorized final actions such as PR/MR/review creation, release tagging, deployment, or publication. Stop implementation loops once acceptance is proven and carry a remaining final action separately.
-  - A model stage sees its local prompt, artifacts, tools, and reads, not the graph name or surrounding implementation. State the concrete action, evidence, and success criteria directly.`,
-];

package/dist/builtin/workflows/src/extension/workflow-reload-coordinator.ts

@@ -1,66 +0,0 @@
-import type { WorkflowReloadReport } from "./workflow-reload-report.js";
-
-type ReloadBatch = {
-	readonly discoveryGeneration: number;
-	requestCount: number;
-	readonly promise: Promise<WorkflowReloadReport>;
-	readonly resolve: (report: WorkflowReloadReport) => void;
-	readonly reject: (error: Error) => void;
-};
-
-export interface WorkflowReloadCoordinator {
-	request(discoveryGeneration: number): Promise<WorkflowReloadReport>;
-}
-
-function createBatch(discoveryGeneration: number): ReloadBatch {
-	let resolve: (report: WorkflowReloadReport) => void = () => undefined;
-	let reject: (error: Error) => void = () => undefined;
-	const promise = new Promise<WorkflowReloadReport>((resolvePromise, rejectPromise) => {
-		resolve = resolvePromise;
-		reject = (error) => rejectPromise(error);
-	});
-	return { discoveryGeneration, requestCount: 0, promise, resolve, reject };
-}
-
-/**
- * Runs one reload at a time. Requests coalesce only with the latest queued pass
- * from the same session generation; generation boundaries remain ordered.
- */
-export function createWorkflowReloadCoordinator(
-	reload: (discoveryGeneration: number, coalescedRequests: number) => Promise<WorkflowReloadReport>,
-): WorkflowReloadCoordinator {
-	const pending: ReloadBatch[] = [];
-	let draining = false;
-
-	const drain = async (): Promise<void> => {
-		if (draining) return;
-		draining = true;
-		try {
-			while (pending.length > 0) {
-				const batch = pending.shift()!;
-				try {
-					const report = await reload(batch.discoveryGeneration, batch.requestCount);
-					batch.resolve(report);
-				} catch (error) {
-					batch.reject(error instanceof Error ? error : new Error(String(error)));
-				}
-			}
-		} finally {
-			draining = false;
-			if (pending.length > 0) void drain();
-		}
-	};
-
-	return {
-		request(discoveryGeneration): Promise<WorkflowReloadReport> {
-			let batch = pending.at(-1);
-			if (batch?.discoveryGeneration !== discoveryGeneration) {
-				batch = createBatch(discoveryGeneration);
-				pending.push(batch);
-			}
-			batch.requestCount += 1;
-			queueMicrotask(() => void drain());
-			return batch.promise;
-		},
-	};
-}

package/dist/builtin/workflows/src/extension/workflow-reload-report.ts

@@ -1,42 +0,0 @@
-import type { ConfigDiagnostic } from "./config-loader.js";
-import type { DiscoveryDiagnostic } from "./discovery.js";
-
-export type WorkflowReloadDiagnostic =
-	| (ConfigDiagnostic & { readonly phase: "config" })
-	| (DiscoveryDiagnostic & { readonly phase: "discovery" });
-
-type WorkflowReloadReportState = {
-	readonly generation: number;
-	readonly workflowCount: number;
-	readonly coalescedRequests: number;
-	readonly diagnostics: WorkflowReloadDiagnostic[];
-};
-
-export type WorkflowReloadReport = WorkflowReloadReportState &
-	(
-		| { readonly outcome: "applied" }
-		| { readonly outcome: "failed"; readonly error: string }
-		| { readonly outcome: "superseded" }
-	);
-
-export function normalizeWorkflowReloadReport(report: WorkflowReloadReport | undefined): WorkflowReloadReport {
-	return (
-		report ?? {
-			outcome: "applied",
-			generation: 0,
-			workflowCount: 0,
-			coalescedRequests: 1,
-			diagnostics: [],
-		}
-	);
-}
-
-export function workflowReloadDiagnostics(
-	configDiagnostics: readonly ConfigDiagnostic[],
-	discoveryDiagnostics: readonly DiscoveryDiagnostic[],
-): WorkflowReloadDiagnostic[] {
-	return [
-		...configDiagnostics.map((diagnostic) => ({ ...diagnostic, phase: "config" as const })),
-		...discoveryDiagnostics.map((diagnostic) => ({ ...diagnostic, phase: "discovery" as const })),
-	];
-}

package/dist/builtin/workflows/src/extension/workflow-request-abort.ts

@@ -1,15 +0,0 @@
-export function raceWorkflowRequestAbort<T>(operation: Promise<T>, signal: AbortSignal | undefined): Promise<T> {
-	if (signal === undefined) return operation;
-	if (signal.aborted) {
-		void operation.catch(() => {});
-		return Promise.reject(signal.reason ?? new DOMException("Workflow request aborted", "AbortError"));
-	}
-	const abort = Promise.withResolvers<never>();
-	const onAbort = (): void => {
-		abort.reject(signal.reason ?? new DOMException("Workflow request aborted", "AbortError"));
-	};
-	signal.addEventListener("abort", onAbort, { once: true });
-	return Promise.race([operation, abort.promise]).finally(() => {
-		signal.removeEventListener("abort", onAbort);
-	});
-}

package/dist/builtin/workflows/src/extension/workflow-resume-picker-rows.ts

@@ -1,96 +0,0 @@
-/**
- * Row sources for the `/workflow resume` picker.
- *
- * Only inactive workflows belong in the resume selector. Live runs contribute
- * paused (quit) or recoverably-failed rows; actively-running live runs are
- * hidden because resuming an executing workflow would double-dispatch it.
- * The same collection backs the picker's live refresh (store changes plus a
- * bounded cross-session poll), so state transitions appear while it is open.
- */
-
-import { getDurableBackend } from "../durable/factory.js";
-import { isWorkflowRunResumable } from "../durable/resume-eligibility.js";
-import type { ResumableWorkflowEntry } from "../durable/types.js";
-import { topLevelWorkflowRuns } from "../shared/run-visibility.js";
-import type { Store } from "../shared/store.js";
-import { subscribeStoreInvalidation } from "../shared/store-observation.js";
-import type { RunSnapshot } from "../shared/store-types.js";
-import { workflowRunResumeCandidate } from "../shared/workflow-artifacts.js";
-import type { WorkflowResumeRefresh } from "../tui/workflow-resume-selector.js";
-import type { ExtensionRuntime } from "./runtime.js";
-import { prepareWorkflowResumeCatalog } from "./workflow-durable-resume-command.js";
-import { classifyDurableResumeShadow } from "./workflow-resume-shadow.js";
-
-export interface ResumePickerLiveSource {
-	readonly liveRuns: readonly RunSnapshot[];
-	/** Live ids whose resumable durable duplicates must be suppressed. */
-	readonly suppressedLiveIds: ReadonlySet<string>;
-}
-
-/** A live run is resumable when the shared predicate accepts it and the durable
- * backend has not explicitly deleted it. A live paused/quit run resumes through
- * its live stage controls, so it must NOT require a durable checkpoint here;
- * a restored snapshot that depends on durable state is filtered by its shadow
- * classification instead.
- */
-function isResumableLiveRun(run: RunSnapshot): boolean {
-	if (!getDurableBackend().isWorkflowLoadable(run.id)) return false;
-	return isWorkflowRunResumable(workflowRunResumeCandidate(run));
-}
-
-export function collectResumePickerLiveRuns(runStore: Store): ResumePickerLiveSource {
-	// `eligible` rows are re-listed from the durable catalog, and `ineligible`
-	// rows have no durable checkpoint or pending prompt progress, so the resume
-	// path would refuse them. Only `not_shadow` runs can actually be resumed here.
-	const runs = topLevelWorkflowRuns(runStore.runs());
-	const shadowClassification = new Map(runs.map((run) => [run.id, classifyDurableResumeShadow(run, runStore)]));
-	const isOfferable = (run: RunSnapshot): boolean => shadowClassification.get(run.id) === "not_shadow";
-	const resumableById = new Map(runs.map((run) => [run.id, isResumableLiveRun(run)]));
-	const liveRuns = runs.filter((run) => isOfferable(run) && resumableById.get(run.id) === true);
-	const isCurrentlyRunning = (run: RunSnapshot): boolean =>
-		run.endedAt === undefined && run.status === "running" && run.exitReason !== "quit";
-	const activeLiveIds = new Set(
-		runs
-			.filter(
-				(run) =>
-					shadowClassification.get(run.id) !== "eligible" &&
-					isCurrentlyRunning(run) &&
-					resumableById.get(run.id) !== true,
-			)
-			.map((run) => run.id),
-	);
-	// A non-running snapshot rejected by the shared predicate must not reappear as
-	// a resumable durable row. Completed inspection rows remain visible separately.
-	const rejectedLiveIds = new Set(
-		runs.filter((run) => !isCurrentlyRunning(run) && resumableById.get(run.id) !== true).map((run) => run.id),
-	);
-	const suppressedLiveIds = new Set([...activeLiveIds, ...rejectedLiveIds]);
-	return { liveRuns, suppressedLiveIds };
-}
-
-export interface ResumePickerLiveUpdateOptions {
-	readonly watch: (onChange: () => void) => () => void;
-	readonly refresh: WorkflowResumeRefresh;
-}
-
-export function resumePickerLiveUpdateOptions(
-	runStore: Store,
-	runtime: ExtensionRuntime,
-): ResumePickerLiveUpdateOptions {
-	return {
-		watch: (onChange) => subscribeStoreInvalidation(runStore, onChange),
-		refresh: async () => {
-			const current = collectResumePickerLiveRuns(runStore);
-			const catalog = await prepareWorkflowResumeCatalog(runtime, current.suppressedLiveIds);
-			return {
-				liveRuns: current.liveRuns,
-				catalog: { durable: catalog.resumable, completed: catalog.completed },
-			};
-		},
-	};
-}
-
-export interface ResumePickerCatalogRows {
-	readonly durable: readonly ResumableWorkflowEntry[];
-	readonly completed: readonly ResumableWorkflowEntry[];
-}

package/dist/builtin/workflows/src/extension/workflow-resume-shadow.ts

@@ -1,53 +0,0 @@
-import type { DurableWorkflowBackend } from "../durable/backend.js";
-import { getDurableBackend } from "../durable/factory.js";
-import { isDurableWorkflowResumable } from "../durable/resume-eligibility.js";
-import { getLoadableDurableWorkflow } from "../durable/workflow-status-transition.js";
-import { type JobTracker, jobTracker } from "../runs/background/job-tracker.js";
-import { type StageControlRegistry, stageControlRegistry } from "../runs/foreground/stage-control-registry.js";
-import { expandWorkflowGraph } from "../shared/expanded-workflow-graph.js";
-import { readGraphStoreSnapshot } from "../shared/store-observation.js";
-import type { Store } from "../shared/store-public-types.js";
-import type { RunSnapshot } from "../shared/store-types.js";
-
-interface DurableResumeShadowDeps {
-	readonly backend?: DurableWorkflowBackend;
-	readonly jobs?: JobTracker;
-	readonly stageControls?: StageControlRegistry;
-}
-
-export type DurableResumeShadowClassification = "eligible" | "ineligible" | "not_shadow";
-
-/** Classify restored metadata without manufacturing progress the durable backend rejects. */
-export function classifyDurableResumeShadow(
-	run: RunSnapshot,
-	store: Store,
-	deps: DurableResumeShadowDeps = {},
-): DurableResumeShadowClassification {
-	const backend = deps.backend ?? getDurableBackend();
-	const handle = getLoadableDurableWorkflow(backend, run.id);
-	if (handle?.status !== "paused" && handle?.status !== "running") return "not_shadow";
-	const jobs = deps.jobs ?? jobTracker;
-	if (jobs.has(run.id)) return "not_shadow";
-	const controls = deps.stageControls ?? stageControlRegistry;
-	const graph = expandWorkflowGraph(readGraphStoreSnapshot(store), run.id);
-	const controlRunIds = new Set<string>([run.id]);
-	for (const stage of graph.stages) controlRunIds.add(stage.workflowGraphTarget.runId);
-	if ([...controlRunIds].some((runId) => controls.run(runId).stages().length > 0)) return "not_shadow";
-	if (!isDurableWorkflowResumable(handle)) return "ineligible";
-	if (run.status !== "paused" || run.exitReason !== "quit" || run.resumable !== true) {
-		store.recordRunPaused(run.id, undefined, { exitReason: "quit", resumable: true });
-	}
-	return "eligible";
-}
-
-/**
- * Reconcile a session-restored snapshot with an authoritative resumable
- * durable handle. Live jobs/controls win; zero-progress orphans remain intact.
- */
-export function reconcileDurableResumeShadow(
-	run: RunSnapshot,
-	store: Store,
-	deps: DurableResumeShadowDeps = {},
-): boolean {
-	return classifyDurableResumeShadow(run, store, deps) === "eligible";
-}