@bastani/atomic 0.8.27 → 0.8.28-alpha.2

package/dist/builtin/mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/mcp",
-  "version": "0.8.27",
+  "version": "0.8.28-alpha.2",
   "private": true,
   "description": "Atomic extension that adapts MCP (Model Context Protocol) servers into the coding agent. Fork of: https://github.com/nicobailon/pi-mcp-adapter",
   "contributors": [
@@ -50,7 +50,7 @@
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.7.2",
     "@modelcontextprotocol/sdk": "^1.25.1",
-    "open": "^10.2.0",
+    "open": "^11.0.0",
     "typebox": "^1.1.24",
     "zod": "^3.25.0 || ^4.0.0"
   }

package/dist/builtin/subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/subagents",
-  "version": "0.8.27",
+  "version": "0.8.28-alpha.2",
   "private": true,
   "description": "Atomic extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification. Fork of: https://github.com/nicobailon/pi-subagents",
   "contributors": [

package/dist/builtin/web-access/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/web-access",
-  "version": "0.8.27",
+  "version": "0.8.28-alpha.2",
   "private": true,
   "description": "Atomic extension for web search, URL fetching, GitHub repo cloning, PDF/video extraction. Fork of: https://github.com/nicobailon/pi-web-access",
   "contributors": [

package/dist/builtin/workflows/CHANGELOG.md

@@ -6,6 +6,28 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.8.28-alpha.2] - 2026-06-10
+
+### Fixed
+
+- Fixed the builtin `open-claude-design` workflow not installing the browser skill's `browse` CLI before it is needed. The workflow now runs an initial deterministic, best-effort setup step that probes `PATH` (`which`/`where browse`) and installs the CLI with `npm install -g browse` when missing (skipped under automated tests); per-run bootstrap guidance is derived from the outcome and injected into every browser-using stage (assume-available when ensured, with concrete recovery steps surfaced when the install failed), the install outcome is exposed via a new `browse_cli_status` output, and the read-only `read`/`grep`/`ls` tools are granted to the refinement and pre-export decision gates so they can inspect `preview.html` without mutating it. The step never throws or blocks the run, so stages keep their graceful-degradation fallback ([#1327](https://github.com/bastani-inc/atomic/issues/1327)).
+- Fixed paused workflow run detail cards to surface the natural `workflow resume` action hint while preserving the interrupt hint for non-paused active runs ([#1283](https://github.com/bastani-inc/atomic/issues/1283)).
+- Fixed paused workflow runs being counted as running and displayed as pending/running in `/workflow status` and `/workflow status <id>`, with paused runs now shown separately as `❚❚ paused` ([#1283](https://github.com/bastani-inc/atomic/issues/1283)).
+
+## [0.8.28-alpha.1] - 2026-06-09
+
+### Added
+
+- Added workflow `ctx.ui.custom<T>(factory, options?)` for graph-visible custom TUI human-in-the-loop prompts. Custom prompts create `awaiting_input` prompt nodes, reuse the stage UI broker/attached stage chat component path, expose the same real TUI/theme/keybinding/component types as Atomic extension custom UI, participate in live-memory prompt replay through hashed custom identities, keep labels display-only/outside replay identity, honor prompt/run abort signals, and reject clearly in headless/unavailable UI modes. Iteration 1 supports inline graph rendering; `overlay: true` and non-TUI `workflow send` answers for arbitrary custom widget results return clear unsupported errors rather than silently degrading ([#1309](https://github.com/bastani-inc/atomic/issues/1309)).
+
+### Changed
+
+- Changed workflow transcript introspection to return `sessionFile`/`transcriptPath` metadata with a lazy-read prompt by default when a transcript path exists, while keeping bounded inline previews behind explicit `tail`/`limit` requests and falling back to a small preview when no path is available ([#1314](https://github.com/bastani-inc/atomic/issues/1314)).
+
+### Fixed
+
+- Fixed a workflow kill/abort race that could crash the entire CLI with a process-level uncaught exception (for example `No API key found for ...`). When a workflow was killed mid-prompt, the executor's `raceAbort` left the already-in-flight stage prompt promise unobserved; its later rejection escaped every workflow error boundary and became an unhandled rejection. `raceAbort` now always observes the in-flight promise in the already-aborted branch so a killed run can no longer orphan a rejecting prompt.
+
 ## [0.8.27] - 2026-06-08
 
 ### Changed

package/dist/builtin/workflows/README.md

@@ -139,7 +139,9 @@ export default defineWorkflow("review-and-merge")
   .compile();
 ```
 
-Human input is runtime-only: call `ctx.ui.input`, `ctx.ui.confirm`, `ctx.ui.select`, or `ctx.ui.editor` at the point where the workflow actually needs a decision. No builder-level declaration is required or supported.
+Human input is runtime-only: call `ctx.ui.input`, `ctx.ui.confirm`, `ctx.ui.select`, `ctx.ui.editor`, or `ctx.ui.custom<T>` at the point where the workflow actually needs a decision. No builder-level declaration is required or supported.
+
+`ctx.ui.custom<T>(factory, options?)` mounts an arbitrary focused TUI component in the attached workflow graph/stage UI and resolves with the value passed to `done(value)`. The factory uses the same real TUI/theme/keybinding/component types as Atomic extension `ctx.ui.custom`. Use `options.label` for a safe display-only graph/status label and `options.replayIdentity` (do not include secrets) when the widget's semantics can change without the callsite changing; label text is not part of replay identity. Custom widget prompts require an interactive workflow graph; they are not answerable through non-TUI `workflow send` in iteration 1. Inline graph rendering is supported; `overlay: true` is rejected clearly because nested workflow graph overlays are not safely supported yet.
 
 ### Example 4 — Compose workflows
 
@@ -458,11 +460,11 @@ Tradeoff: `Type.Unsafe<T>()` does not deeply validate at runtime — it trusts t
 
 Input overrides are bare `key=value` tokens (no leading `--`). Values are JSON-parsed when possible, so numbers, booleans, and quoted strings work as expected (e.g. `count=3`, `flag=true`, `prompt="multi word value"`). A whole-object override can be passed as a single JSON token (e.g. `{"prompt":"...","count":3}`). Runtime validation is strict: unknown input keys, missing required values, type mismatches, and invalid `select` choices fail before a named workflow run starts.
 
-Workflows always run as **background tasks** in interactive sessions — the chat editor stays free while a run executes. Press **F2** (or `/workflow connect <run-id>`) to attach to the live graph viewer; HIL prompts (`ctx.ui.input/confirm/select/editor`) appear as awaiting-input graph nodes. Press Enter on the node to answer locally, never as a modal dialog over the chat. Human input is detected when those runtime `ctx.ui.*` calls execute; workflows no longer have a declaration-time HIL flag.
+Workflows always run as **background tasks** in interactive sessions — the chat editor stays free while a run executes. Press **F2** (or `/workflow connect <run-id>`) to attach to the live graph viewer; HIL prompts (`ctx.ui.input/confirm/select/editor/custom`) appear as awaiting-input graph nodes. Press Enter on the node to answer locally, never as a modal dialog over the chat. Human input is detected when those runtime `ctx.ui.*` calls execute; workflows no longer have a declaration-time HIL flag.
 
 Nested `ctx.workflow(...)` calls are displayed as an expanded graph within the top-level run. `/workflow status` and run pickers list only top-level user-launched workflows, not implementation-owned child runs. The `workflow` tool's `stages`, `stage`, `transcript`, `send`, `pause`, `interrupt`, and `resume` actions can still target visible child stage ids, prefixes, or names from the expanded graph; Atomic routes the control action to the owning nested run internally. (`stages`, `stage`, `transcript`, and `send` are `workflow` tool actions, not `/workflow` slash subcommands; the slash command exposes `connect`, `attach`, `pause`, `list`, `status`, `interrupt`, `kill`, `resume`, `reload`, and `inputs`.)
 
-Prompt answer replay is live-memory only. `StageSnapshot.promptAnswerState` reports whether continuation can replay a prompt answer (`available`), must ask again because the private ledger entry is gone (`unavailable`), or must ask again because multiple matching prompt nodes are ambiguous (`ambiguous`). Raw answers stay in a private `PromptAnswerRecord` ledger, are never serialized to snapshots or persistence, and remain resident in memory until the answer is cleared, the run is removed, or the store is cleared. Replay keys include prompt kind, message text, select choices, input/editor initial value, and hashed author callsite, so changing any of those inputs may intentionally re-ask on continuation. Empty `ctx.ui.select(..., [])` calls throw before creating a prompt node.
+Prompt answer replay is live-memory only. `StageSnapshot.promptAnswerState` reports whether continuation can replay a prompt answer (`available`), must ask again because the private ledger entry is gone (`unavailable`), or must ask again because multiple matching prompt nodes are ambiguous (`ambiguous`). Raw answers stay in a private `PromptAnswerRecord` ledger, are never serialized to snapshots or persistence, and remain resident in memory until the answer is cleared, the run is removed, or the store is cleared. Replay keys include prompt kind, message text, select choices, input/editor initial value, custom prompt identity hash, and hashed author callsite, so changing any of those inputs may intentionally re-ask on continuation. Empty `ctx.ui.select(..., [])` calls throw before creating a prompt node. Arbitrary custom-widget answers cannot be supplied with `workflow send`; focus the `custom` awaiting-input node in the interactive graph instead.
 
 ### `workflow` tool (LLM-callable)
 
@@ -471,7 +473,7 @@ Prompt answer replay is live-memory only. `StageSnapshot.promptAnswerState` repo
 ```json
 {
   "name": "workflow",
-  "description": "Run named workflows or direct one-off task/tasks/chain workflows; discover with list/get/inputs, inspect status/stages/stage details, send prompt answers or steering, pause/resume/interrupt/kill runs, and reload workflow resources. 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. For transcripts, prefer status/stages/stage to get sessionFile/transcriptPath, quote the exact path without rewriting separators (Windows backslashes are valid), search it with rg/grep, and read small ranges; transcript defaults to at most 5 recent entries and explicit tail/limit overrides that preview.",
+  "description": "Run named workflows or direct one-off task/tasks/chain workflows; discover with list/get/inputs, inspect status/stages/stage details, send prompt answers or steering, pause/resume/interrupt/kill runs, and reload workflow resources. 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. 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.",
   "parameters": {
     "workflow": "string (optional) — workflow ID or normalized name",
     "inputs": "object (optional) — key/value map of workflow inputs",
@@ -480,9 +482,9 @@ Prompt answer replay is live-memory only. `StageSnapshot.promptAnswerState` repo
     "stageId": "optional stage id, prefix, or name for stage-scoped actions; cannot be combined with all:true",
     "statusFilter": "optional stages filter: pending/running/awaiting_input/paused/blocked/completed/failed/skipped/all",
     "format": "optional agent-facing output format: text or json",
-    "limit": "transcript-only explicit maximum number of recent entries; omitted with tail omitted uses the default 5-entry preview plus metadata/path",
+    "limit": "transcript-only explicit maximum number of recent entries; omitted with tail omitted uses the path-only default when sessionFile/transcriptPath exists",
     "tail": "transcript-only explicit last-N entry count; overrides limit for quick recent-context checks",
-    "includeToolOutput": "transcript-only flag for explicit snapshot tool-event output; prefer rg/grep on the exact quoted sessionFile/transcriptPath for large outputs",
+    "includeToolOutput": "transcript-only flag for inlined snapshot preview/fallback tool-event output; does not bypass the path-only default; prefer rg/grep on the exact quoted sessionFile/transcriptPath for large outputs",
     "text": "optional string payload for send/resume; explicit empty text answers pending prompts",
     "response": "optional structured payload for answering pending prompts; explicit empty response is valid",
     "message": "optional string payload for send/resume when text is not provided",
@@ -506,8 +508,8 @@ Prompt answer replay is live-memory only. `StageSnapshot.promptAnswerState` repo
 
 - **`renderCall`** — renders a compact workflow call summary in the chat scroll.
 - **`renderResult`** — renders the result or dispatch banner; live progress continues through the widget and graph viewer. Named workflow runs are background-oriented.
-- **`transcript`** — reference-first with a small preview by default: use `status`, `stages`, or `stage` to identify the stage and its `sessionFile`/`transcriptPath`, quote the exact path without changing platform separators (for example, preserve Windows backslashes), then search that file with `rg`/`grep` for targeted terms and read only small surrounding ranges. Text results include JSON-escaped `sessionFileJson`/`transcriptPathJson` lines for copy-safe path literals plus up to 5 recent entries by default. Passing explicit `tail` or `limit` overrides that preview for quick context checks. A registered live stage handle is used when one exists, even before live messages arrive; otherwise the action falls back to stored stage snapshots. Snapshot entries are ordered chronologically before `tail`/`limit` is applied, with terminal result/error entries kept after tool entries when timestamps are missing or tied. `includeToolOutput` applies to snapshot tool-event results; live session transcripts may not expose tool output.
-- **`send`** — answers pending stage prompts only when `text`, `response`, or `message` is present; an explicit empty string is a valid answer, while an omitted payload is a no-op. `delivery: "auto"` answers pending prompts first, then resumes paused stages, steers streaming stages, or queues a follow-up.
+- **`transcript`** — path-only by default when a transcript file exists: use `status`, `stages`, or `stage` to identify the stage and its `sessionFile`/`transcriptPath`, quote the exact path without changing platform separators (for example, preserve Windows backslashes), then search that file with `rg`/`grep` for targeted terms and read only small surrounding ranges. Default text results include JSON-escaped `sessionFileJson`/`transcriptPathJson` lines for copy-safe path literals plus a `lazyReadPrompt`, with `entries: not inlined` so transcript bodies and tool outputs stay out of model context. Passing explicit `tail` or `limit` opts into a bounded inline preview for quick context checks. If no transcript path is available, the action falls back to a bounded preview of up to 5 recent entries with a `fallbackNote`. A registered live stage handle is used when one exists, even before live messages arrive; otherwise the action falls back to stored stage snapshots. Snapshot entries are ordered chronologically before `tail`/`limit` is applied, with terminal result/error entries kept after tool entries when timestamps are missing or tied. `includeToolOutput` applies only to inlined snapshot previews or no-path fallback previews; live session transcripts may not expose tool output.
+- **`send`** — answers pending primitive/structured stage prompts only when `text`, `response`, or `message` is present; an explicit empty string is a valid answer, while an omitted payload is a no-op. Arbitrary `ctx.ui.custom<T>` widget prompts require the interactive workflow graph and return a clear unsupported message when targeted through `send`. `delivery: "auto"` answers pending prompts first, then resumes paused stages, steers streaming stages, or queues a follow-up.
 - **`reload`** — refreshes workflow resources directly in-process instead of queuing a literal `/workflow reload` chat follow-up.
 
 ### F2 keyboard shortcut
@@ -520,7 +522,7 @@ Press **F2** while a workflow is running to open the DAG overlay for the active
 
 For interactive use, run workflows through `/workflow <name> [key=value ...]` or let the LLM call the `workflow` tool. In non-interactive (`-p` / `--print` / `--mode json`) sessions, `/workflow <name> key=value` and LLM calls to the `workflow` tool remain available for deterministic workflows. The input picker and graph picker are disabled, top-level `ctx.ui.*` is unavailable, and stage child sessions exclude `ask_user_question`. Named workflow dispatch waits for the terminal run snapshot before returning.
 
-Because human input is runtime-only and workflows no longer carry a declaration-time HIL marker, headless dispatch does not reject a workflow just because its source contains `ctx.ui.*`. If you copy the HIL example above into a non-interactive session, it can pass dispatch and then fail when execution reaches the prompt with an error such as `atomic-workflows: HIL ctx.ui.confirm is unavailable because Atomic runtime did not provide a UI adapter` (the primitive name varies). Run those workflows interactively, or guard/remove runtime `ctx.ui.*` calls before using headless mode.
+Because human input is runtime-only and workflows no longer carry a declaration-time HIL marker, headless dispatch does not reject a workflow just because its source contains `ctx.ui.*`. If you copy the HIL example above into a non-interactive session, it can pass dispatch and then fail when execution reaches the prompt with an error such as `atomic-workflows: HIL ctx.ui.confirm is unavailable because Atomic runtime did not provide a UI adapter` (the primitive name varies, including `ctx.ui.custom`). Run those workflows interactively, or guard/remove runtime `ctx.ui.*` calls before using headless mode.
 
 For library or package authoring, define reusable workflows with the builder and export the compiled definition. Hand-written objects with `__piWorkflow: true` are rejected by discovery and composition; `defineWorkflow(...).compile()` is the public authoring surface. Standalone TypeScript workflow packages can import `defineWorkflow` and `Type` from `@bastani/workflows` directly with no local `.d.ts` file or `declare module` shim. The former imperative `runWorkflow` object-form API is removed; use compiled workflow definitions with the exported `run()` / registry helpers for programmatic execution.
 

package/dist/builtin/workflows/builtin/open-claude-design.ts

@@ -23,7 +23,10 @@
  * a real HTML page on disk (`preview.html`). The workflow attempts to open it
  * through the `browser` skill so the user can interactively review;
  * when browser automation is unavailable, the file path is surfaced so the user
- * can open it manually. The final exporter produces a rich `spec.html` that
+ * can open it manually. Before any stage runs, an initial deterministic setup
+ * step ensures the browser skill's `browse` CLI is available (`which browse`,
+ * then `npm install -g browse` when missing); it is best-effort and never
+ * blocks the run. The final exporter produces a rich `spec.html` that
  * embeds the agreed-upon design alongside the implementation handoff.
  */
 
@@ -33,6 +36,7 @@ import type {
   WorkflowTaskResult,
   WorkflowTaskStep,
 } from "../src/shared/types.js";
+import { spawnSync } from "node:child_process";
 import { mkdirSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -49,6 +53,15 @@ type OutputType = (typeof OUTPUT_TYPES)[number];
 const DEFAULT_OUTPUT_TYPE: OutputType = "prototype";
 const DEFAULT_MAX_REFINEMENTS = 3;
 
+/**
+ * Read-only builtin tools granted to the structured-decision stages
+ * (user-feedback refinement gate and pre-export gate) so they can actually
+ * inspect the on-disk `preview.html` before emitting their decision. The
+ * artifact stays immutable here — writes/edits belong to apply-changes and
+ * forced-fix, so this list deliberately excludes write/edit/bash.
+ */
+const READ_ONLY_TOOLS = ["read", "grep", "ls"] as const;
+
 type PromptSection = readonly [tag: string, content: string];
 
 function taggedPrompt(sections: readonly PromptSection[]): string {
@@ -275,11 +288,126 @@ const ANTI_SLOP_RULES = [
   "Commit to a specific aesthetic direction; do not hedge with generic SaaS defaults.",
 ].join("\n");
 
-const BROWSER_USE_BOOTSTRAP_RULES = [
-  "Probe for the browser skill's `browse` CLI with `which browse`; if it is unavailable, install the CLI with `npm install -g browse` as documented by the skill, then retry once. Do not add project dependencies.",
-  "Use `browse open <url> --local --headed` when a generated local preview should be visible to the user, and use `browse snapshot` plus `browse screenshot --path <file>` for review evidence.",
-  "If `browse` is unavailable after three attempts or the browser runtime still fails, degrade gracefully and surface the manual file path / URL.",
-].join("\n");
+type BrowseCliStatus = {
+  /** Whether the `browse` CLI is expected to be available to downstream stages. */
+  readonly available: boolean;
+  /** True when the CLI was already on PATH and no install was attempted. */
+  readonly alreadyPresent: boolean;
+  /** True when this step installed the CLI via `npm install -g browse`. */
+  readonly installed: boolean;
+  /** Human-readable, single-line outcome surfaced as a workflow output. */
+  readonly summary: string;
+  /** Raw failure reason when the install could not complete; absent on success. */
+  readonly error?: string;
+};
+
+/**
+ * Initial deterministic setup step (no LLM): ensure the browser skill's `browse`
+ * CLI is available before any design stage runs. Mirrors the browser skill's
+ * documented bootstrap (`which browse || npm install -g browse`) but performs it
+ * once, deterministically, instead of relying on each stage to probe/install it.
+ * The PATH probe always runs, but the actual global install is skipped under
+ * automated tests (`NODE_ENV=test`) to avoid slow, networked, environment-
+ * mutating side effects.
+ *
+ * Best-effort by contract: it never throws and never blocks the workflow. When
+ * the CLI cannot be located or installed, downstream stages keep their graceful
+ * degradation path (surface the manual preview path / URL).
+ */
+function ensureBrowseCli(): BrowseCliStatus {
+  const isWindows = process.platform === "win32";
+  const onPath = (): boolean => {
+    try {
+      const probe = spawnSync(isWindows ? "where" : "which", ["browse"], {
+        stdio: "ignore",
+        timeout: 15_000,
+        shell: isWindows,
+      });
+      return probe.status === 0;
+    } catch {
+      return false;
+    }
+  };
+
+  if (onPath()) {
+    return {
+      available: true,
+      alreadyPresent: true,
+      installed: false,
+      summary: "browse CLI already on PATH; skipped install.",
+    };
+  }
+
+  // Never perform a real global `npm install` during automated tests: it is
+  // slow, network-dependent, and would mutate the test runner's global
+  // environment. The PATH probe above and the prompt guidance below are still
+  // exercised; only the install side effect is skipped.
+  if (process.env.NODE_ENV === "test") {
+    return {
+      available: false,
+      alreadyPresent: false,
+      installed: false,
+      summary:
+        "browse CLI not found; skipped global install under the test environment.",
+      error: "global install skipped during tests",
+    };
+  }
+
+  try {
+    const install = spawnSync("npm", ["install", "-g", "browse"], {
+      stdio: "ignore",
+      timeout: 180_000,
+      shell: isWindows,
+    });
+    if (install.status === 0) {
+      return {
+        available: true,
+        alreadyPresent: false,
+        installed: true,
+        summary: "Installed browse CLI via `npm install -g browse`.",
+      };
+    }
+    const reason =
+      install.error?.message ??
+      (typeof install.status === "number"
+        ? `npm install -g browse exited with code ${install.status}`
+        : "npm install -g browse did not complete");
+    return {
+      available: false,
+      alreadyPresent: false,
+      installed: false,
+      summary: `Could not install browse CLI (${reason}); stages will degrade gracefully.`,
+      error: reason,
+    };
+  } catch (error) {
+    const reason =
+      error instanceof Error ? error.message : String(error);
+    return {
+      available: false,
+      alreadyPresent: false,
+      installed: false,
+      summary: `Could not install browse CLI (${reason}); stages will degrade gracefully.`,
+      error: reason,
+    };
+  }
+}
+
+/**
+ * Build the per-run browser bootstrap guidance injected into stage prompts.
+ * When the deterministic setup step already ensured `browse` is installed, the
+ * guidance tells stages to assume availability and not waste turns reinstalling;
+ * otherwise it retains the original probe-and-install fallback.
+ */
+function buildBrowserBootstrapRules(status: BrowseCliStatus): string {
+  const probeRule = status.available
+    ? "The workflow's deterministic setup step already ensured the browser skill's `browse` CLI is installed and on PATH; assume it is available and do NOT reinstall it. Only if a `browse` command reports the executable as missing should you re-probe with `which browse` and run `npm install -g browse` once before retrying. Do not add project dependencies."
+    : `The workflow's deterministic setup step attempted to install the browser skill's \`browse\` CLI but it FAILED with: "${status.error ?? "unknown error"}". Treat this as a known starting condition to work around, not a hard blocker. Probe with \`which browse\` and retry once with \`npm install -g browse\`; if it still fails, use the error above to diagnose a workaround (for example: EACCES/permission errors → retry with a user-writable global prefix; missing npm/Node → report it plainly; network/registry errors → surface them). If the CLI still cannot be made available, degrade gracefully and surface the manual file path / URL. Do not add project dependencies.`;
+  return [
+    probeRule,
+    "Use `browse open <url> --local --headed` when a generated local preview should be visible to the user, and use `browse snapshot` plus `browse screenshot --path <file>` for review evidence.",
+    "If `browse` is unavailable after three attempts or the browser runtime still fails, degrade gracefully and surface the manual file path / URL.",
+  ].join("\n");
+}
 
 export default defineWorkflow("open-claude-design")
   .description(
@@ -316,7 +444,15 @@ export default defineWorkflow("open-claude-design")
   .output("preview_file_url", Type.Optional(Type.String({ description: "file:// URL for the generated preview.html file." })))
   .output("spec_path", Type.Optional(Type.String({ description: "Absolute path to the generated spec.html file." })))
   .output("spec_file_url", Type.Optional(Type.String({ description: "file:// URL for the generated spec.html file." })))
+  .output("browse_cli_status", Type.Optional(Type.String({ description: "Outcome of the initial deterministic step that ensures the browser skill's `browse` CLI is installed." })))
   .run(async (ctx) => {
+    // Initial deterministic setup step (no LLM): ensure the browser skill's
+    // `browse` CLI is installed before any design stage runs. Best-effort —
+    // a failed install never blocks the workflow; downstream stages keep their
+    // graceful-degradation fallback (surface the manual preview path / URL).
+    const browseCli = ensureBrowseCli();
+    const browserBootstrapRules = buildBrowserBootstrapRules(browseCli);
+
     const inputs = ctx.inputs;
 
     const prompt = inputs.prompt;
@@ -344,12 +480,12 @@ export default defineWorkflow("open-claude-design")
     };
     const refinementDecisionConfig = {
       ...designModelConfig,
-      tools: [refinementDecisionTool.name],
+      tools: [...READ_ONLY_TOOLS, refinementDecisionTool.name],
       customTools: [refinementDecisionTool],
     };
     const exportGateDecisionConfig = {
       ...designModelConfig,
-      tools: [exportGateDecisionTool.name],
+      tools: [...READ_ONLY_TOOLS, exportGateDecisionTool.name],
       customTools: [exportGateDecisionTool],
     };
 
@@ -551,7 +687,7 @@ export default defineWorkflow("open-claude-design")
             `Capture transferable design intent from this reference for: ${prompt}. Apply the impeccable \`extract\` sub-skill to lift concrete, citable design traits from the reference URL. Use browser/screenshot tooling if available; never guess about visual traits without observable evidence.`,
           ],
           ["reference_url", reference],
-          ["browser_use_guidelines", BROWSER_USE_BOOTSTRAP_RULES],
+          ["browser_use_guidelines", browserBootstrapRules],
           [
             "instructions",
             [
@@ -671,7 +807,7 @@ export default defineWorkflow("open-claude-design")
           ],
           ["preview_path", previewPath],
           ["preview_file_url", previewFileUrl],
-          ["browser_use_guidelines", BROWSER_USE_BOOTSTRAP_RULES],
+          ["browser_use_guidelines", browserBootstrapRules],
           [
             "instructions",
             [
@@ -794,7 +930,7 @@ export default defineWorkflow("open-claude-design")
               ["current_design_and_feedback", "{previous}"],
               [
                 "browser_use_guidelines",
-                BROWSER_USE_BOOTSTRAP_RULES,
+                browserBootstrapRules,
               ],
               [
                 "instructions",
@@ -881,7 +1017,7 @@ export default defineWorkflow("open-claude-design")
             ["preview_file_url", previewFileUrl],
             [
               "browser_use_bootstrap",
-              BROWSER_USE_BOOTSTRAP_RULES,
+              browserBootstrapRules,
             ],
             [
               "instructions",
@@ -1044,7 +1180,7 @@ export default defineWorkflow("open-claude-design")
           ["spec_file_url", specFileUrl],
           ["preview_path", previewPath],
           ["preview_file_url", previewFileUrl],
-          ["browser_use_guidelines", BROWSER_USE_BOOTSTRAP_RULES],
+          ["browser_use_guidelines", browserBootstrapRules],
           [
             "instructions",
             [
@@ -1078,6 +1214,7 @@ export default defineWorkflow("open-claude-design")
       preview_file_url: previewFileUrl,
       spec_path: specPath,
       spec_file_url: specFileUrl,
+      browse_cli_status: browseCli.summary,
     };
   })
   .compile();

package/dist/builtin/workflows/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/workflows",
-  "version": "0.8.27",
+  "version": "0.8.28-alpha.2",
   "private": true,
   "description": "Atomic extension for multi-stage workflow authoring and execution.",
   "contributors": [

package/dist/builtin/workflows/src/authoring.d.ts

@@ -57,7 +57,7 @@ export declare const Type: Omit<typeof TypeboxType, "Any" | "Array" | "BigInt" |
     Void(): TVoid;
 };
 export type { Static, TSchema } from "typebox";
-export type { AgentSessionAdapter, CompleteAdapter, CompleteStageOpts, GitWorktreeSetupOptions, GitWorktreeSetupResult, PromptAdapter, PromptOptions, ResolvedInputs, RunResult, RunStatus, StageAdapters, StageStatus, StageOptions, StageContext, StageSnapshot, StageExecutionMeta, StageMcpOptions, StageOutputOptions, StagePromptOptions, StageSessionCreateOptions, StageSessionCreateResult, StageSessionRuntime, WorkflowAction, WorkflowArtifact, WorkflowChainOptions, WorkflowChainStep, WorkflowChildResult, WorkflowContextMode, WorkflowControlEvent, WorkflowCustomToolDefinition, WorkflowDetails, WorkflowDetailsMode, WorkflowDetailsStatus, WorkflowDirectOptions, WorkflowDirectTaskItem, WorkflowExecutionMode, WorkflowExecutionPolicy, WorkflowInputBindings, WorkflowInputSchema, WorkflowInputSchemaMap, WorkflowInputValues, WorkflowIntercomSummary, WorkflowMaxOutput, WorkflowMcpPort, WorkflowModelAttempt, WorkflowModelCatalogPort, WorkflowModelFallbackFields, WorkflowModelInfo, WorkflowModelUsage, WorkflowModelValue, WorkflowOutputMode, WorkflowOutputSchema, WorkflowOutputSchemaMap, WorkflowOutputValues, WorkflowParallelChainStep, WorkflowParallelOptions, WorkflowPersistencePort, WorkflowProgressSummary, WorkflowRunChildOptions, WorkflowRunOutput, WorkflowRuntimeConfig, WorkflowSerializableObject, WorkflowSerializablePrimitive, WorkflowSerializableValue, WorkflowSharedTaskDefaults, WorkflowTaskContext, WorkflowTaskContextInput, WorkflowTaskOptions, WorkflowTaskResult, WorkflowTaskSessionFields, WorkflowTaskSessionOptions, WorkflowTaskStep, WorkflowThinkingLevel, WorkflowUIAdapter, WorkflowUIContext, WorkflowWorktreeInputBinding, } from "./shared/authoring-contract.js";
+export type { AgentSessionAdapter, CompleteAdapter, CompleteStageOpts, GitWorktreeSetupOptions, GitWorktreeSetupResult, PromptAdapter, PromptOptions, ResolvedInputs, RunResult, RunStatus, StageAdapters, StageStatus, StageOptions, StageContext, StageSnapshot, StageExecutionMeta, StageMcpOptions, StageOutputOptions, StagePromptOptions, StageSessionCreateOptions, StageSessionCreateResult, StageSessionRuntime, WorkflowAction, WorkflowArtifact, WorkflowChainOptions, WorkflowChainStep, WorkflowChildResult, WorkflowContextMode, WorkflowControlEvent, WorkflowCustomToolDefinition, WorkflowCustomUiComponent, WorkflowCustomUiFactory, WorkflowCustomUiKeybindings, WorkflowCustomUiOptions, WorkflowCustomUiOverlayHandle, WorkflowCustomUiOverlayOptions, WorkflowCustomUiTheme, WorkflowCustomUiTui, WorkflowDetails, WorkflowDetailsMode, WorkflowDetailsStatus, WorkflowDirectOptions, WorkflowDirectTaskItem, WorkflowExecutionMode, WorkflowExecutionPolicy, WorkflowInputBindings, WorkflowInputSchema, WorkflowInputSchemaMap, WorkflowInputValues, WorkflowIntercomSummary, WorkflowMaxOutput, WorkflowMcpPort, WorkflowModelAttempt, WorkflowModelCatalogPort, WorkflowModelFallbackFields, WorkflowModelInfo, WorkflowModelUsage, WorkflowModelValue, WorkflowOutputMode, WorkflowOutputSchema, WorkflowOutputSchemaMap, WorkflowOutputValues, WorkflowParallelChainStep, WorkflowParallelOptions, WorkflowPersistencePort, WorkflowProgressSummary, WorkflowRunChildOptions, WorkflowRunOutput, WorkflowRuntimeConfig, WorkflowSerializableObject, WorkflowSerializablePrimitive, WorkflowSerializableValue, WorkflowSharedTaskDefaults, WorkflowTaskContext, WorkflowTaskContextInput, WorkflowTaskOptions, WorkflowTaskResult, WorkflowTaskSessionFields, WorkflowTaskSessionOptions, WorkflowTaskStep, WorkflowThinkingLevel, WorkflowUIAdapter, WorkflowUIContext, WorkflowWorktreeInputBinding, } from "./shared/authoring-contract.js";
 import type * as AuthoringContract from "./shared/authoring-contract.js";
 import type { GitWorktreeSetupOptions, GitWorktreeSetupResult, ResolvedInputs, RunResult, RunStatus, StageSnapshot, WorkflowDefinition as WorkflowContractDefinition, WorkflowDetails, WorkflowDirectOptions, WorkflowDirectTaskItem, WorkflowExecutionPolicy, WorkflowInputValues, WorkflowOutputValues, WorkflowSerializableObject, WorkflowChainStep } from "./shared/authoring-contract.js";
 declare const workflowDefinitionBrand: unique symbol;
@@ -118,13 +118,16 @@ export interface StageNode extends WorkflowSerializableObject {
     readonly parentIds: readonly string[];
 }
 export type NoticeLevel = "info" | "warning" | "error";
-export type PromptKind = "input" | "confirm" | "select" | "editor";
+export type PromptKind = "input" | "confirm" | "select" | "editor" | "custom";
+export type CustomPromptIdentitySource = "caller" | "factory" | "callsite";
 export interface PendingPrompt extends WorkflowSerializableObject {
     readonly id: string;
     readonly kind: PromptKind;
     readonly message: string;
     readonly choices?: readonly string[];
     readonly initial?: string;
+    readonly customIdentityHash?: string;
+    readonly customIdentitySource?: CustomPromptIdentitySource;
     readonly createdAt: number;
 }
 export interface ToolEvent {

package/dist/builtin/workflows/src/extension/background-ui-adapter.ts

@@ -36,8 +36,10 @@ import type {
 } from "../shared/store-types.js";
 import type { WorkflowUIAdapter } from "../shared/types.js";
 
+type BackgroundPromptKind = Exclude<PromptKind, "custom">;
+
 interface PromptDescriptor {
-  readonly kind: PromptKind;
+  readonly kind: BackgroundPromptKind;
   readonly message: string;
   readonly choices?: readonly string[];
   readonly initial?: string;

package/dist/builtin/workflows/src/extension/hil-answer-notifications.ts

@@ -76,7 +76,6 @@ export function installWorkflowHilAnswerNotifications(
   if (typeof send !== "function") return () => undefined;
 
   const state = options.state ?? createWorkflowHilAnswerNotificationState();
-  let previousSnapshot = options.store.snapshot();
 
   const emitOnce = (details: WorkflowHilAnswerNoticeDetails): void => {
     const key = answerNoticeKey(details.runId, details.stageId, details.promptId, details.promptKind);
@@ -86,23 +85,21 @@ export function installWorkflowHilAnswerNotifications(
     sendHilAnswerNotice(send, details);
   };
 
-  const inspectSimplePromptAnswers = (snapshot: StoreSnapshot): void => {
-    for (const previousRun of previousSnapshot.runs) {
-      const currentRun = snapshot.runs.find((run) => run.id === previousRun.id);
-      if (currentRun === undefined) continue;
-
-      for (const previousStage of previousRun.stages) {
-        const answeredPrompt = simplePromptAnswer(previousStage, currentRun);
-        if (answeredPrompt === undefined) continue;
-        const answerRecord = options.store.getStagePromptAnswer(currentRun.id, answeredPrompt.stage.id);
-        if (answerRecord?.answerSource === "workflow_tool") continue;
-        emitOnce(makeSimplePromptAnswerNotice(currentRun, answeredPrompt.stage, answeredPrompt.prompt, answerRecord?.value));
+  const inspectWorkflowPromptAnswers = (snapshot: StoreSnapshot): void => {
+    for (const currentRun of snapshot.runs) {
+      for (const currentStage of currentRun.stages) {
+        const prompt = workflowPromptAnswerCandidate(currentStage);
+        if (prompt === undefined) continue;
+        const answerRecord = options.store.getStagePromptAnswer(currentRun.id, currentStage.id);
+        if (answerRecord === undefined) continue;
+        if (answerRecord.promptId !== prompt.id) continue;
+        if (answerRecord.answerSource === "workflow_tool") continue;
+        emitOnce(makeSimplePromptAnswerNotice(currentRun, currentStage, prompt, answerRecord.value, answerRecord.answeredAt));
       }
     }
-    previousSnapshot = snapshot;
   };
 
-  const unsubscribeStore = options.store.subscribe(inspectSimplePromptAnswers);
+  const unsubscribeStore = options.store.subscribe(inspectWorkflowPromptAnswers);
   const unsubscribeBroker = options.stageUiBroker?.onStagePromptResolved((event) => {
     if (event.answerSource === "workflow_tool") return;
     const answeredStage = findStageSnapshot(options.store.snapshot(), event.runId, event.stageId);
@@ -180,17 +177,11 @@ function sendHilAnswerNotice(
   }
 }
 
-function simplePromptAnswer(
-  previousStage: StageSnapshot,
-  currentRun: RunSnapshot,
-): { stage: StageSnapshot; prompt: PendingPrompt } | undefined {
-  const prompt = previousStage.pendingPrompt;
+function workflowPromptAnswerCandidate(stage: StageSnapshot): PendingPrompt | undefined {
+  const prompt = stage.promptFootprint;
   if (prompt === undefined) return undefined;
-  const currentStage = currentRun.stages.find((stage) => stage.id === previousStage.id);
-  if (currentStage === undefined) return undefined;
-  if (currentStage.pendingPrompt !== undefined) return undefined;
-  if (currentStage.promptAnswerState !== "available") return undefined;
-  return { stage: currentStage, prompt };
+  if (stage.promptAnswerState !== "available") return undefined;
+  return prompt;
 }
 
 function findStageSnapshot(
@@ -215,6 +206,7 @@ function makeSimplePromptAnswerNotice(
   stage: StageSnapshot,
   prompt: PendingPrompt,
   answer: unknown,
+  answeredAt: number,
 ): WorkflowHilAnswerNoticeDetails {
   return {
     kind: "hil_answered",
@@ -226,7 +218,7 @@ function makeSimplePromptAnswerNotice(
     promptId: prompt.id,
     promptKind: prompt.kind,
     promptMessage: truncateAnswerSnippet(prompt.message),
-    answeredAt: Date.now(),
+    answeredAt,
     answerAvailable: true,
     answerIncluded: true,
     answerSummary: formatAnswerSummary(answer),