@bastani/atomic 0.9.28-alpha.3 → 0.9.28-alpha.5

package/dist/builtin/subagents/skills/cua-driver/WORKFLOW.md

@@ -0,0 +1,173 @@
+# Observe, act, verify
+
+## Choose the route
+
+Name the user's postcondition and any method constraint before acting.
+
+1. For a non-GUI outcome, use a caller-provided application API, filesystem operation, or CLI when permitted; independently read back its result. An MCP-only client must not assume it has a shell.
+2. For exact window geometry, prefer `set_window_frame` and verify with `list_windows`. For a known native menu path, use `invoke_menu` and verify the command's effect. It can temporarily activate the target, so apply the foreground authorization boundary.
+3. For supported browser page content, use [BROWSER.md](BROWSER.md) when page-aware automation is permitted. GUI-only or native-input proof stays on the native route.
+4. For native controls, prefer snapshot-bound accessibility actions. If semantics cannot reach the target, use a fresh, valid screenshot and the window pixel route.
+5. If the selected background route refuses or visibly fails, consider explicitly authorized foreground delivery for that action.
+6. If exact-window observation or delivery is unavailable, use the desktop route only when the task and authorization admit full-display capture and visible input.
+
+Skip a route whose prerequisite is demonstrably absent: no valid window image means no window-pixel attempt. Do not exhaust impossible actions just to reach a later rung. A refusal never grants broader authority.
+
+## Select the target
+
+Discover running applications and their windows before assuming a remembered PID still exists. Use `launch_app` when the user requests or implies launch. Select the intended window from its returned `windows` or `list_windows({pid})`; never blindly take the first item.
+
+A cold launch may return a process before a window appears. Retry bounded window discovery, not repeated launches. Empty discovery does not prove the process exited. For closure, absence from `list_windows` proves no listed windows, not process termination.
+
+Choose the target on each action:
+
+```json
+{ "target": { "kind": "window", "pid": 844, "window_id": 10725 } }
+```
+
+```json
+{ "target": { "kind": "desktop", "display_id": "primary" } }
+```
+
+These objects are argument fragments for tools advertising `target`, not standalone commands. Replace example IDs and coordinates with observed values. Do not combine `target` with flat `scope`, `pid`, or `window_id` input fields. Observation tools and semantic-only tools such as `get_window_state` and `set_value` retain their own `pid`/`window_id` schema.
+
+`list_windows.z_index` uses larger integers for windows nearer the front. A null value is unknown, not zero; array order is not stacking evidence. Titles, bounds, and application identity help select among returned candidates but never replace an exact identifier.
+
+## Observe
+
+`get_window_state({pid, window_id})` requests the accessibility tree and a grounding screenshot by default. Check what actually came back: permission, backing-store, or surface-identity failures can leave usable tree data without an image. `screenshot_error` and `screenshot_frame_valid:false` are not empty-tree signals.
+
+Prefer `structuredContent.elements` in MCP (the CLI prints structured fields directly) over parsing `tree_markdown`. Rows may contain `element_token`, role, label, value, actions, parent, depth, enabled/selected state, `frame` (screen coordinates, the space of `scope:"desktop"` actions), and `screenshot_frame` (pixels of the screenshot in the same response, the space of window-local pointer `x`/`y`). Missing fields are unknown.
+
+- Use `query` to project matching rows plus ancestors without renumbering their indices.
+- Use `max_elements` / `max_depth` to bound the walk, and compare returned/total counts. Truncation does not prove absence.
+- Use `include_screenshot:false` only when tree-only observation is enough; it cannot ground a pixel action.
+- Where advertised, `include_accessibility_tree:false` requests capture without a tree walk. Check the installed schema first.
+- `capture_mode` is deprecated and ignored. Do not change configuration to repair a sparse tree.
+- Use `screenshot_out_file` to save a PNG instead of inlining it, then actually read the image. Use an absolute, run-scoped output path.
+
+The accessibility model may lag or disagree with rendered state: Electron text shims can echo writes, Catalyst may expose placeholders, and virtualized rows may have unusable frames. Cross-check the relevant visible outcome. An empty tree can also mean an unavailable accessibility bridge; inspect `degraded_reason` and the platform guide. Retry once for lazy initialization, not indefinitely.
+
+## Act once
+
+Use an opaque `element_token` from the latest snapshot of the intended window. Do not derive or edit tokens. A later snapshot can invalidate a pending action, including when another agent observes the same window.
+
+Example CLI window action, with IDs and token replaced from the preceding response:
+
+```bash
+cua-driver click '{"target":{"kind":"window","pid":844,"window_id":10725},"element_token":"s0000002a:14","session":"run-1"}'
+```
+
+| Intent                          | Arguments in addition to exact target/session                                  |
+| ------------------------------- | ------------------------------------------------------------------------------ |
+| Activate a control              | `click` with `element_token`                                                   |
+| Double/right click              | `double_click` / `right_click`; inspect the host schema and delivery result    |
+| Insert text                     | `type_text` with `element_token` and `text`                                    |
+| Focus a visible field and type  | `type_text` with `x,y,text`, when that form is advertised                      |
+| Replace an exposed native value | `set_value` with `pid,element_token,value` (its own schema, no `target`)       |
+| Send a key or combination       | `press_key` with `key`, or `hotkey` with `keys`                                |
+| Scroll / drag                   | Inspect `describe scroll` / `describe drag`; units and supported shapes matter |
+
+Text insertion and value replacement are different intents. Setting a field does not prove a form submission, navigation, or rename committed. Open a collapsed search/input control and reobserve before typing into it; one focus-click may not both open and focus it. Inspect the existing value/selection before replacing content.
+
+If a text action returns `unverifiable`, take a fresh snapshot before retrying. A deferred provider can publish after the call unwinds, so retrying immediately may duplicate text. If renderer focus is missing, the advertised `type_text` pixel form focuses then types in one call. For minimized windows, prefer an exposed semantic commit control; do not assume Return or a value write commits, and do not silently restore the window.
+
+Keep `delivery_mode:"background"` as the default for window input. The route may use accessibility hit-testing even when addressed by pixels: pixel coordinates do not promise physical pointer delivery. Read the returned `route` instead of inferring it from the tool name.
+
+## Pixel coordinates
+
+Ground window actions on the PNG from that exact `get_window_state`; ground desktop actions on `get_desktop_state`. Origins are top-left, increasing downward. The driver handles its own window capture scaling; do not add window offsets to window-local input.
+
+The harness may downsample the displayed preview independently of the returned PNG. Use the returned dimensions and the original file. If measuring on a resized preview, account for its exact scale in both axes; do not assume the preview is native resolution. Do not guess from accessibility frames or another app's geometry.
+
+After movement, resize, navigation, or a competing desktop interaction, reobserve. When using `zoom`, read its schema and preserve the `from_zoom` mapping on the supported follow-up action. A manually cropped image requires its crop offset; an untracked crop is not an action coordinate source.
+
+For tiny targets, inspect at full resolution or annotate a copy without changing its dimensions. Keep the raw evidence unmodified. `debug_image_out`, where advertised, captures an action diagnostic; it is not a pre-action approval step.
+
+## Desktop loop
+
+Use the full-display path when authorized and the narrower route cannot satisfy the task. It is global input to the visible desktop, not background targeting. Ensure the desired app/field is visible and focused before keyboard input; stop if the user or another controller changes it.
+
+```bash
+cua-driver get_desktop_state '{"session":"run-1","screenshot_out_file":"/absolute/run-dir/before.png"}'
+# Read before.png; replace x/y with the observed target.
+cua-driver click '{"target":{"kind":"desktop","display_id":"primary"},"x":600,"y":300,"session":"run-1"}'
+cua-driver get_desktop_state '{"session":"run-1","screenshot_out_file":"/absolute/run-dir/after.png"}'
+# Read after.png and verify the intended outcome.
+```
+
+Desktop calls use the portable `display_id:"primary"` target. Do not assume arbitrary display IDs work. A desktop action does not change the modality or authority of later calls; the next action can target a window again.
+
+## Verify and stop
+
+For an expressible exact-window postcondition, use `verify_state` with bounded predicates and stable samples. Its result is `satisfied`, `unsatisfied`, or `unknown`. The driver does not interpret its optional final image; the agent does. Read `unknown_reason`: ambiguous matches, unavailable observations, untrusted web state, or insufficient stable samples are not success.
+
+```bash
+cua-driver verify_state '{"pid":844,"window_id":10725,"expect":[{"element":{"selector":{"label_contains":"Saved"},"exists":true}}],"include_screenshot":true,"session":"run-1"}'
+```
+
+This example proves a matching trusted element exists, not that every application has a meaningful “Saved” indicator. `label_contains` matches an element's accessible name, which for label-less text is its value. On macOS a selector also reaches display-only text (static text, read-only values) when no addressable control matches it. Text inside web content stays `unknown` with `untrusted_source`; read it from a fresh snapshot instead. Choose predicates that establish this task. Use fresh `get_window_state` for outcomes the predicate language cannot express, and fresh `get_desktop_state` for desktop proof. `verify_state` remains an exact-window tool; a previous desktop action does not disable it.
+
+Action facts are not task outcomes:
+
+| Field                | Meaning for the next decision                                                                         |
+| -------------------- | ----------------------------------------------------------------------------------------------------- |
+| `effect:"confirmed"` | The action has publishable readback; still check the task postcondition                               |
+| `partial`            | Only the reported delivered portion landed; inspect before repair                                     |
+| `unverifiable`       | Delivery cannot prove effect; observe before retrying                                                 |
+| `suspected_noop`     | Available evidence suggests no useful change                                                          |
+| `refused`            | The route deliberately did not deliver                                                                |
+| `route`              | Public actuator class: `accessibility`, `synthetic_events`, `global_input`, `dom`, or `trusted_input` |
+| `escalation`         | Suggested next route/reason, never authorization or an automatic retry                                |
+
+Successful action escalation uses `target` (`pixel`, `foreground`, or `page`) and `reason` (`route_unavailable`, `delivery_failed`, `effect_unconfirmed`, `suspected_noop`, or `permission_required`). Error diagnostics may have a different shape; inspect their code and current schema. Missing action facts are not confirmation.
+
+When the postcondition is visibly satisfied, stop acting. For media, selection alone is not playback: check the title, playing/pause indicator, and elapsed progress after preroll/buffering. For closure, verify the requested window disappeared. State only what the evidence proves.
+
+Never replay canceled, partial, or unknown actions automatically. An interrupted transport may have delivered input before losing its response. Report the interruption accurately and obtain fresh state before any further action.
+
+## Filesystem outcomes and GUI fallbacks
+
+When the requested outcome is a filesystem change and the caller has a
+headless filesystem or command capability, use that semantic route. Enumerate the
+exact source set, decide the destination-conflict policy before changing
+anything, perform one batch-safe operation, then independently read back both
+source and destination manifests. Do not open a file manager merely to mimic a
+move, copy, or rename that the caller can execute and verify directly.
+
+If the caller has no such capability, use the file manager as a GUI fallback
+and keep each claim narrow:
+
+1. After entering an inline rename and setting its value, commit it with the
+   platform's confirmation key, then take a fresh snapshot. Value readback from
+   the inline editor proves only that the editor changed; it does not prove the
+   filesystem rename committed.
+2. For a multi-selection, use the platform modifier (`cmd` on macOS, `ctrl` on
+   Windows/Linux). With authorization for visible control on macOS and Windows, issue that modified click with
+   `delivery_mode:"foreground"` so the target observes physical modifier state;
+   a refused background attempt is an escalation signal, not a failed action to
+   trust or repeat. Re-snapshot before the next operation. Continue only when
+   every intended item is selected and the prior selection was preserved.
+3. After a cross-window drag or paste, verify the destination contains the
+   complete expected set and the source reflects copy-versus-move semantics.
+   A delivered drag, keypress, or menu action is not file-operation proof.
+4. If a destination conflict presents an unrecognized policy or ambiguous
+   partial result, stop that GUI path and surface the unresolved state instead
+   of retrying blindly.
+
+### Clipboard outcomes and GUI fallbacks
+
+When the requested postcondition is an exact value on the system clipboard,
+rather than the literal gesture of selecting and copying it, keep the operation
+semantic. Read the value from the narrowest typed source, call
+`clipboard_write`, then prove the real clipboard state with `clipboard_read`.
+For browser content, this means reading the page with `get_browser_state` and
+writing the exact observed text; a passive page-text ref does not need to be
+clicked first.
+
+Use visual selection followed by the platform copy hotkey only when the user
+explicitly asks for that gesture, the source cannot expose the value
+semantically, or direct clipboard tools are unavailable. Treat that as a GUI
+fallback: re-snapshot before acting, verify the selected range when the
+application exposes it, and escalate only the delivery step that cannot land
+in the background.

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

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/web-access",
-  "version": "0.9.28-alpha.3",
+  "version": "0.9.28-alpha.5",
   "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": [
@@ -31,7 +31,7 @@
   },
   "peerDependencies": {
     "@bastani/atomic": "*",
-    "@earendil-works/pi-tui": "^1.0.4"
+    "@earendil-works/pi-tui": "^1.1.0"
   },
   "peerDependenciesMeta": {
     "@bastani/atomic": {

package/dist/builtin/workflows/CHANGELOG.md

@@ -6,6 +6,22 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.9.28-alpha.5] - 2026-10-08
+
+### Fixed
+
+- Fixed managed PostgreSQL health checks failing a workflow stage on a healthy but busy host: an unanswered check now retries with a short backoff for up to 15 seconds, the connection limit is 3 seconds instead of 1, and the "did not answer a health check in time" diagnostic clears once PostgreSQL answers again ([#3491](https://github.com/bastani-inc/atomic/issues/3491))
+
+## [0.9.28-alpha.4] - 2026-10-07
+
+### Added
+
+- Added a Claude Haiku 5.5 prompt-engineering guide based on Anthropic's model-specific guidance, covering effort, search grounding, JSON/tool interactions, completion, verification, and refusal handling.
+
+### Changed
+
+- Updated the bundled Impeccable skill to 4.5.0 with engine 0.1.11, adding the `generate` playbook, component-review guidance, and reading, operating, and persuasion design modes. Atomic's telemetry and update-check defaults remain off.
+
 ## [0.9.28-alpha.3] - 2026-10-07
 
 ### Changed

package/dist/builtin/workflows/README.md

@@ -846,7 +846,7 @@ The live session is unbounded: accepted variants and steered edits are written i
 
 The session starts at `user-feedback-N-start`; durable `live-poll-N-M` and `live-reply-N-M` tool nodes own polling and acknowledgements, while `live-generate-*`, `live-steer-*`, `live-manual_edit_apply-*`, and `live-variant_mount_failed-*` mint model stages. Replies pass the event id before the status. Successful `variant_mounted` events are journal-only; `accept`, `discard`, and `prefetch` mint no model stage, and `timeout` is absorbed in the poll node. Nonzero helper exits fail the run rather than looking like timeouts. No `<artifact_dir>/feedback/` directory or per-session record is written.
 
-The poll and reply nodes run the bundled Impeccable 4.3.1 launcher (`skills/impeccable/scripts/impeccable`, or `impeccable.cmd` on Windows) with the `live-poll` verb; the launcher runs the engine binary beside it or downloads and checksum-verifies the pinned engine release on first use, so a machine without network access needs `IMPECCABLE_BIN` pointed at a preinstalled engine. Live sessions persist the selected app root for every helper and support SvelteKit, Nuxt, TanStack Start, Astro, Next.js, Vite, and static HTML injection.
+The poll and reply nodes run the bundled Impeccable 4.5.0 launcher (`skills/impeccable/scripts/impeccable`, or `impeccable.cmd` on Windows) with the `live-poll` verb; the launcher runs the engine binary beside it or downloads and checksum-verifies the pinned engine release on first use, so a machine without network access needs `IMPECCABLE_BIN` pointed at a preinstalled engine. Live sessions persist the selected app root for every helper and support SvelteKit, Nuxt, TanStack Start, Astro, Next.js, Vite, and static HTML injection.
 
 Research context moves between stages as artifact files, not inline prompt payloads: the project design context is written to `<artifact_dir>/design-context.md` and the curated references brief to `<artifact_dir>/references.md`; `reference-discovery`, `generate-1`, and `exporter` read the required files via `reads`.
 

package/dist/builtin/workflows/builtin/{chunk-aqv8ny38.js → chunk-9ywkdsa9.js}

@@ -37,7 +37,7 @@ import {
   parseFailureDiagnostics,
   summarizeReviewConvergence,
   reverify_consolidated_batch
-} from "./chunk-p3xmajmj.js";
+} from "./chunk-v4scsq3y.js";
 import {
   VERIFICATION_SCALE
 } from "./chunk-n1910xc4.js";

package/dist/builtin/workflows/builtin/{chunk-p6jagvyf.js → chunk-bnz4knhy.js}

@@ -1,7 +1,7 @@
 import {
   getDurableBackend2,
   getAvailableDurableBackend2
-} from "./chunk-p3xmajmj.js";
+} from "./chunk-v4scsq3y.js";
 export {
   getAvailableDurableBackend2 as getAvailableDurableBackend,
   getDurableBackend2 as getDurableBackend

package/dist/builtin/workflows/builtin/{chunk-br4ac9a3.js → chunk-dx5sjaxe.js}

@@ -39,7 +39,7 @@ import {
   reviewerFailureText,
   summarizeReviewConvergence,
   reverify_consolidated_batch
-} from "./chunk-p3xmajmj.js";
+} from "./chunk-v4scsq3y.js";
 import {
   fold_usage
 } from "./chunk-tgt0s5e5.js";

package/dist/builtin/workflows/builtin/{chunk-p3xmajmj.js → chunk-v4scsq3y.js}

@@ -6542,6 +6542,9 @@ function resolveEmbeddedPostgresTarget(host) {
 // dist/builtin/workflows/src/durable/dbos-postgres-health.ts
 var HEALTH_INTERVAL_MS = 5000;
 var RECOVERY_ATTEMPTS = 3;
+var MONITORING_PROBE_RETRY_WINDOW_MS = 15000;
+var MONITORING_PROBE_RETRY_INITIAL_MS = 250;
+var MONITORING_PROBE_RETRY_MAX_MS = 2000;
 function isMonitoringConnectionTimeout(error) {
   if (!(error instanceof Error))
     return false;
@@ -6569,6 +6572,7 @@ class PostgresHealth {
   attempts = 0;
   nextRecoveryAt = 0;
   failure;
+  failureUnanswered = false;
   healthySinceFailure = false;
   revision = 0;
   listeners = new Set;
@@ -6581,10 +6585,11 @@ class PostgresHealth {
   get endpoint() {
     return this.operations.url?.();
   }
-  retainFailure(error) {
+  retainFailure(error, unanswered = false) {
     const message = error instanceof Error ? error.message : String(error);
     const safe = redactedDatabaseMessage(message, this.endpoint);
     this.failure = new Error(safe);
+    this.failureUnanswered = unanswered;
     this.healthySinceFailure = false;
   }
   dependencyFailure(message) {
@@ -6612,7 +6617,7 @@ class PostgresHealth {
         await this.operations.validate?.(client);
       }
     } catch (error) {
-      this.retainFailure(error);
+      this.retainFailure(error, isQueryReadTimeout(error));
       if (!isQueryReadTimeout(error)) {
         this.invalidate();
         if (this.endpoint === undefined)
@@ -6650,19 +6655,39 @@ class PostgresHealth {
   }
   async probe() {
     const revision = this.revision;
+    const now = this.operations.now ?? Date.now;
+    const wait = this.operations.wait ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
     let identity;
     try {
       identity = await this.operations.probe();
     } catch (error) {
       if (!(isMonitoringConnectionFailure(error) || isQueryReadTimeout(error)) || this.stopped)
         throw error;
-      try {
-        identity = await this.operations.probe();
-      } catch (retryError) {
-        if (isMonitoringConnectionTimeout(retryError) || !isMonitoringConnectionFailure(retryError))
-          throw retryError;
-        this.retainFailure(retryError);
-        return;
+      const deadline = now() + MONITORING_PROBE_RETRY_WINDOW_MS;
+      let delay = MONITORING_PROBE_RETRY_INITIAL_MS;
+      let failure = error;
+      for (;; ) {
+        if (isMonitoringConnectionTimeout(failure) || isQueryReadTimeout(failure)) {
+          if (now() >= deadline)
+            throw failure;
+          await wait(delay);
+          delay = Math.min(delay * 2, MONITORING_PROBE_RETRY_MAX_MS);
+          if (this.stopped)
+            throw failure;
+        }
+        try {
+          identity = await this.operations.probe();
+          break;
+        } catch (retryError) {
+          if (isMonitoringConnectionTimeout(retryError) || isQueryReadTimeout(retryError)) {
+            failure = retryError;
+            continue;
+          }
+          if (!isMonitoringConnectionFailure(retryError))
+            throw retryError;
+          this.retainFailure(retryError);
+          return;
+        }
       }
     }
     if (revision !== this.revision)
@@ -6677,6 +6702,8 @@ class PostgresHealth {
     this.attempts = 0;
     this.nextRecoveryAt = 0;
     this.healthySinceFailure = true;
+    if (this.failureUnanswered)
+      this.failure = undefined;
     return identity.url;
   }
   async refresh() {
@@ -6686,7 +6713,7 @@ class PostgresHealth {
         return ready;
     } catch (error) {
       if (isQueryReadTimeout(error) || isMonitoringConnectionTimeout(error)) {
-        this.retainFailure(new Error("Managed PostgreSQL did not answer a health check in time."));
+        this.retainFailure(new Error("Managed PostgreSQL did not answer a health check in time."), true);
         throw this.dependencyFailure("Managed PostgreSQL did not answer a health check in time.");
       }
       this.retainFailure(error);
@@ -6954,6 +6981,7 @@ var POSTGRES_IDENTITY_SQL = `SELECT current_setting('data_directory') AS data_di
 	system_identifier::text, current_setting('server_version') AS server_version FROM pg_control_system()`;
 var POSTGRES_TIMEZONE_SQL = "SELECT set_config('timezone_abbreviations', 'Default', true)";
 var POSTGRES_HEALTH_QUERY_TIMEOUT_MS = 3000;
+var POSTGRES_HEALTH_CONNECT_TIMEOUT_MS = 3000;
 async function probePostgresTimezoneData(port) {
   const client = new Client({
     host: "127.0.0.1",
@@ -6962,7 +6990,7 @@ async function probePostgresTimezoneData(port) {
     password: "atomic",
     database: "postgres",
     ssl: false,
-    connectionTimeoutMillis: 1000,
+    connectionTimeoutMillis: POSTGRES_HEALTH_CONNECT_TIMEOUT_MS,
     query_timeout: POSTGRES_HEALTH_QUERY_TIMEOUT_MS,
     statement_timeout: POSTGRES_HEALTH_QUERY_TIMEOUT_MS
   });
@@ -6982,7 +7010,7 @@ async function probePostgresIdentity(port) {
     password: "atomic",
     database: "postgres",
     ssl: false,
-    connectionTimeoutMillis: 1000,
+    connectionTimeoutMillis: POSTGRES_HEALTH_CONNECT_TIMEOUT_MS,
     query_timeout: POSTGRES_HEALTH_QUERY_TIMEOUT_MS,
     statement_timeout: POSTGRES_HEALTH_QUERY_TIMEOUT_MS
   });
@@ -9894,7 +9922,7 @@ function createPendingStageDeliveryStoreMethods(context) {
         const run = context.findRun(input.runId);
         if (run === undefined)
           return;
-        const { getAvailableDurableBackend } = await import("./chunk-p6jagvyf.js");
+        const { getAvailableDurableBackend } = await import("./chunk-bnz4knhy.js");
         const availableBackend = getAvailableDurableBackend();
         const backend = availableBackend === undefined ? undefined : durableBackendForRun(availableBackend, context.state.runs, input.runId);
         const receipt = await backend?.readSettledPendingStageMessage?.(input.runId, input.message.id);

package/dist/builtin/workflows/builtin/goal.js

@@ -1,7 +1,7 @@
 import {
   goal_default
-} from "./chunk-aqv8ny38.js";
-import"./chunk-p3xmajmj.js";
+} from "./chunk-9ywkdsa9.js";
+import"./chunk-v4scsq3y.js";
 import"./chunk-2377r57g.js";
 import"./chunk-z0d03ktm.js";
 import"./chunk-n1910xc4.js";

package/dist/builtin/workflows/builtin/index.js

@@ -16,8 +16,8 @@ import {
 } from "./chunk-kb7s3gx2.js";
 import {
   goal_default
-} from "./chunk-aqv8ny38.js";
-import"./chunk-p3xmajmj.js";
+} from "./chunk-9ywkdsa9.js";
+import"./chunk-v4scsq3y.js";
 import"./chunk-z0d03ktm.js";
 import {
   open_claude_design_default
@@ -27,7 +27,7 @@ import {
 } from "./chunk-94f8zfz1.js";
 import {
   ralph_default
-} from "./chunk-br4ac9a3.js";
+} from "./chunk-dx5sjaxe.js";
 import {
   tournament_default
 } from "./chunk-wf876n16.js";

package/dist/builtin/workflows/builtin/ralph.js

@@ -1,7 +1,7 @@
 import {
   ralph_default
-} from "./chunk-br4ac9a3.js";
-import"./chunk-p3xmajmj.js";
+} from "./chunk-dx5sjaxe.js";
+import"./chunk-v4scsq3y.js";
 import"./chunk-2377r57g.js";
 import"./chunk-z0d03ktm.js";
 import"./chunk-n1910xc4.js";

package/dist/builtin/workflows/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/workflows",
-  "version": "0.9.28-alpha.3",
+  "version": "0.9.28-alpha.5",
   "private": true,
   "description": "Atomic extension for multi-stage workflow authoring and execution.",
   "contributors": [
@@ -85,7 +85,7 @@
   },
   "peerDependencies": {
     "@bastani/atomic": "*",
-    "@earendil-works/pi-tui": "^1.0.4",
+    "@earendil-works/pi-tui": "^1.1.0",
     "typebox": "*"
   },
   "peerDependenciesMeta": {

package/dist/builtin/workflows/skills/impeccable/SKILL.md

@@ -1,8 +1,13 @@
 ---
 name: impeccable
 description: Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks.
-version: 4.3.1
+version: 4.5.0
 license: Apache 2.0
+metadata:
+    github-repo: https://github.com/pbakaus/impeccable
+    github-path: .pi/skills/impeccable
+    github-ref: refs/tags/skill-v4.5.0
+    github-tree-sha: 2493a4daa753fb20fdab53a51fb89ba8f5157496
 allowed-tools:
   - Bash(npx impeccable *)
   - Bash(.pi/skills/impeccable/scripts/impeccable *)
@@ -66,7 +71,8 @@ Choose the mode from the requested surface, not the product, and persist it only
 | `clarify [target]` | Fix | Improve UX copy, labels, and error messages | [reference/clarify.md](reference/clarify.md) |
 | `adapt [target]` | Fix | Adapt for different devices and screen sizes | [reference/adapt.md](reference/adapt.md) · native: [reference/adapt.native.md](reference/adapt.native.md) |
 | `optimize [target]` | Fix | Diagnose and fix UI performance | [reference/optimize.md](reference/optimize.md) |
-| `live` | Iterate | Visual variant mode: pick elements in the browser, generate alternatives | [reference/live.md](reference/live.md) |
+| `live` | Iterate | Visual variant mode: pick elements in the browser, iterate on alternatives | [reference/live.md](reference/live.md) |
+| `generate [n] [action] [element]` | Iterate | Variants, versions, or alternatives of a named element to choose from in the live browser; no manual picking | [reference/generate.md](reference/generate.md) |
 
 Routing:
 

package/dist/builtin/workflows/skills/impeccable/reference/adapt.md

@@ -188,6 +188,12 @@ Test thoroughly across contexts:
 - **Edge cases**: Very small screens (320px), very large screens (4K)
 - **Slow connections**: Test on throttled network
 
+**Custom controls** (sliders, drag surfaces, scrollable control strips): a before/after slider can pass every width check above and still refuse to drag on iOS, so exercise each one in scope in the same batched round as the checks above:
+
+- **Primary gesture**: Tap it and confirm it responds as designed, then drag it with the target input method; the drag must complete, not just start
+- **Scroll across it**: A swipe along the page's scroll axis across the control scrolls the page or container without activating it; a drag that starts on the control along its axis moves the control, not the page. Neither failure throws an error, so try both
+- **Evidence**: Say what produced the evidence: an emulated viewport, synthesized touch input through a browser tool, which engine ran it (Chromium is not Safari), or a physical device. Screenshots and resized viewports verify layout, never a gesture. Name what stayed untested and move on; unreachable hardware is a reported gap, not a blocker
+
 When the adaptation feels native to each context, hand off to `/impeccable polish` for the final pass.
 
 ---

package/dist/builtin/workflows/skills/impeccable/reference/audit.md

@@ -48,11 +48,12 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the
 **Check for**:
 - **Fixed widths**: Hard-coded widths that break on mobile
 - **Touch targets**: Interactive elements < 44x44px
+- **Broken touch interaction**: Custom sliders, drag surfaces, and scrollable control strips whose primary gesture fails under touch, that swallow page scroll or lose the drag to it, or that stay stuck after an interrupted gesture. Code tells: mouse-only handlers, no `touch-action` on a pointer-event drag surface, drag state that nothing clears on cancel, lost capture, or blur. Exercise the gesture when a browser tool can synthesize touch (a rendered viewport proves layout, not the gesture), then say what produced the evidence (emulated viewport, synthesized touch, which engine, physical device) and what stayed untested
 - **Horizontal scroll**: Content overflow on narrow viewports
 - **Text scaling**: Layouts that break when text size increases
 - **Missing breakpoints**: No mobile/tablet variants
 
-**Score 0-4**: 0=Desktop-only (breaks on mobile), 1=Major issues (some breakpoints, many failures), 2=Partial (works on mobile, rough edges), 3=Good (responsive, minor touch target or overflow issues), 4=Excellent (fluid, all viewports, proper touch targets)
+**Score 0-4**: 0=Desktop-only (breaks on mobile), 1=Major issues (some breakpoints, many failures), 2=Partial (works on mobile, rough edges), 3=Good (responsive, minor touch target or overflow issues), 4=Excellent (fluid, all viewports, proper touch targets, gestures work under touch)
 
 ### 5. Implementation Integrity (CRITICAL)
 

package/dist/builtin/workflows/skills/impeccable/reference/component-review.md

@@ -0,0 +1,63 @@
+# Plan and asset review
+
+Use this checkpoint on comp-led builds once every raster region has its plate and the plates gate has scored them, before any page code exists. The approved comp is the reference. The user reviews two things: the plates that will ship, and the production plan for everything else, meaning which regions code draws. A painted region planned as code is the most expensive mistake a comp-led build makes, and this is where the user catches it. Text, controls and chrome are judged later, in the assembled first viewport.
+
+## Plan, capture, serve
+
+Run `.pi/skills/impeccable/scripts/impeccable component-review plan`. It writes `.impeccable/review/components.json` from the measured spec, the comp and the plate files, and refuses, naming each one, while any raster region lacks its plate. Never write or edit that file for this stage: the packet is derived from the spec, so every change belongs in the regions file.
+
+If the harness exposes `component_review`, call it with `manifest_path` set to `.impeccable/review/components.json`. The host captures, presents the review and returns the user's decisions. A suspended request is waiting for the user; it is not a failed build or an approval.
+
+Otherwise run `.pi/skills/impeccable/scripts/impeccable component-review capture --manifest .impeccable/review/components.json`, then start `.pi/skills/impeccable/scripts/impeccable component-review serve --session <returned session>` in the background. Open the URL it prints in the available browser and wait for the user; `serve` exits 0 once they submit. Read the decisions with `.pi/skills/impeccable/scripts/impeccable component-review status --session <id>`; `.pi/skills/impeccable/scripts/impeccable component-review verify --manifest .impeccable/review/components.json` confirms approval and refuses pending, needs-work and stale input. Never submit the page or write a receipt on the user's behalf.
+
+`serve` exits 2 when this session has no browser (the same signal as the decision page) and 4 when it closes after 30 idle minutes without a decision. Either way no one is reviewing: stop waiting, do not approve anything yourself, and do not build past this checkpoint. End the run and report the plan and asset review as pending with its session ID, so the user can resume it. A waiting review is pending work, not a completed build.
+
+## Act on the receipt
+
+Apply the user's decisions as given, never your own favorable verdict in their place.
+
+- **approve**: once every item is approved and the inventory is confirmed, advance to the hero.
+- **revise** (a plate): regenerate that plate at the same path with the user's feedback.
+- **revise with split** (an asset): replace that region in the regions file with its layers: a frame plate with a transparent opening (kind `plate`, same box), the content as its own `image` region at the opening's box, and each moving part (a shutter, a door) as its own plate. Name each layer after the original region, as `<id>-frame`, `<id>-view` or `<id>-shutter-left`, so the next round shows it as part of the user's request. Rerun `.pi/skills/impeccable/scripts/impeccable comp-spec --comp <comp.png> --regions <regions.json>` and produce the plates.
+- **revise** (a plan item): change the regions file as the feedback says (resize or extend a raster region, split material into its own plate region, or adjust the code region), rerun `.pi/skills/impeccable/scripts/impeccable comp-spec --comp <comp.png> --regions <regions.json>`, and produce any new plates.
+- **reclassify** (a code region): in the regions file, change that region's `kind` to the one the user chose and rewrite its `note` to describe the material. Rerun `.pi/skills/impeccable/scripts/impeccable comp-spec --comp <comp.png> --regions <regions.json>`, then produce the new plates, with the asset producer when subagents are available.
+- **missing**: add the region to the regions file, rerun `.pi/skills/impeccable/scripts/impeccable comp-spec --comp <comp.png> --regions <regions.json>`, and produce its plate if it is raster.
+
+Then run `plan`, `capture` and `serve` again. Unchanged decisions carry over, so the user sees only what changed. Any spec change, or a plate replaced after acceptance, needs a new round; the build-phase gate stays closed until the review of the current spec is accepted.
+
+## Assemble and review
+
+Build the first viewport from the approved plates and plan, and run the hero gate. Human review does not waive its integrity checks. After three failed hero attempts, stop iterating and present the first-viewport review with the current build; the user's eye settles what the readings could not.
+
+Present a second manifest at `.impeccable/review/hero.json`. You write this one, and its shape is fixed:
+
+```json
+{
+  "schemaVersion": 2,
+  "stage": "hero",
+  "id": "hero",
+  "title": "First viewport",
+  "comp": {"path": ".impeccable/mocks/comp.png", "width": 1536, "height": 1024},
+  "components": [{
+    "id": "first-viewport",
+    "name": "First viewport",
+    "medium": "HTML / CSS",
+    "note": "Assembled first viewport",
+    "box": {"x": 0, "y": 0, "w": 1, "h": 1},
+    "preview": {"kind": "page", "path": "index.html"},
+    "dependencies": ["styles.css", "assets/plates/sky.png", "fonts/display.woff2"]
+  }]
+}
+```
+
+- `schemaVersion` is 2. Version 3 is the plan review packet and requires stage `components`. `codeRegions` and `specSha256` exist only in version 3 and are refused here. `reviewGroup` is refused too: version 3 rejects it, and any other version accepts it only on a page preview in a `components`-stage manifest, never in a hero manifest.
+- `comp.path` is the `comp` value in `.impeccable/build/spec.json`, and `width` and `height` are that PNG's pixel size.
+- Exactly one component, with `box` exactly `{"x": 0, "y": 0, "w": 1, "h": 1}` and `name`, `medium` and `note` as strings.
+- `preview.path` is the page entry the build gates (`artifact` in `.impeccable/build/state.json`).
+- `dependencies` lists every other file the page loads (stylesheets, scripts, plates, images, fonts) as bare strings. Every path, here and above, is project-relative and plain: no leading `./` or `/`, no `..`, no URL, no `?`, `#`, `%`, `:` or backslash. A request to a file missing from this list, or to another host, fails the capture.
+
+The reference stays the approved comp. Call the same host review tool, or run `capture`, `serve` and `verify` with this manifest. Needs-work feedback starts another assembly round.
+
+Acceptance closes human review for this build: never request plan, asset or assembly approval again. While the page renders what the user accepted, the hero score, the palette check and every numeric reading are advisories; material vetoes still hold (a missing or unreferenced plate, an SVG illustration, an organic clip, a clipped plate, invented ink, failed rendered presence). When the capture no longer matches the accepted screenshot, restore what the user accepted; until then the readings apply. Complete the rest of the page, responsive behavior, finish checks and documentation with the accepted first viewport as the visual direction. This is first-viewport calibration, not a claim that the user reviewed the rest of the page. Shared stylesheet edits do not reopen approval. Preserve the accepted direction; a later explicit user change is a new task.
+
+Assembled-page capture executes inline and declared local scripts from the pinned inputs. Network APIs, frames and workers are unavailable; the initial viewport must settle before capture. Keep the real page and declare its scripts rather than removing behavior to pass review.

package/dist/builtin/workflows/skills/impeccable/reference/degraded/asset-producer.md

@@ -13,6 +13,10 @@ Do not redesign. Preserve the reference's visual role, silhouette, palette, ligh
 
 When the parent hands you a decision card packet instead of an approved mock, the job is one comp: one card, one file, written to the card's declared `comp` path the moment it renders. The parent runs several of you in parallel, one per card, so this card is your entire contract; generate first, plan never, because the file on disk is the deliverable and the decision page is waiting on it. Work from the card's structured fields and PRODUCT.md alone; report a card too thin to brief a comp, never pad it from imagination. Render the card's direction as a north-star comp at full fidelity: the requested surface's first viewport, prompt led by the surface's own structure (regions named in order with their scale relationships, never the world's atmosphere), fully committed in the card's own palette, type character, and material world. A native app or mobile-first surface is a portrait frame at its device viewport, never a landscape default. Every sibling renders at the same full fidelity in its own grammar, one surface, one aspect; equal commitment keeps the comparison honest. Real product name and real content only; never invent commercial claims, prices, benchmarks, or dates PRODUCT.md does not carry. Exclusions bind those claims, never a medium the card's own world has not excluded: a subject that lives in photographs keeps its photographs. Write the prompt sidecar beside the file. Return one line naming the path and any deviation, nothing more. Everything below this section is the asset-production job; none of it applies to a decision-comp run.
 
+## Review handoff
+
+Return the actual files and any unresolved drift to the parent for the user's plan and asset review in [component-review.md](../component-review.md). A parent or automatic visual check is not a substitute for that human checkpoint. The parent may call you again after it: for regions the user reclassified from code to raster (the spec now lists them with a plate path), or for plates the user asked to revise, with their feedback as the prompt notes. Produce only those, preserve unchanged assets, and hand off real files as before; never self-approve. This checkpoint does not apply to the Decision Comps job above.
+
 ## Input Contract
 
 Expect the measured spec (`.impeccable/build/spec.json`, written by `impeccable comp-spec` from the approved comp), the approved comp path, and the skill scripts path. Optionally: a subset of region ids to produce, extra prompt notes per region, and format or transparency needs. Everything else you need is in the spec: each raster region's id, kind (plate, image, texture), pixel box, sampled palette, aspect, note, and the plate path it must land on.
@@ -29,6 +33,7 @@ Per region, in the spec's order:
 2. Choose the background from the approved region: an isolated figure, object, or line drawing on the page ground is a **transparent cutout**; a photograph, full-frame illustration, or texture stays **opaque**. Save `.pi/skills/impeccable/scripts/impeccable comp-spec --plate-prompt <id> --background transparent` to a UTF-8 prompt file for a cutout; use `--background opaque` otherwise. The transparent prompt preserves reference placement and clear margins, white paint, fine edges, and interior holes.
 3. Produce the plate at its exact spec `plate` path. Create the output directory first and choose a supported output size matching the region's aspect, at least 1.5x its pixel dimensions. Prefer the harness-native image tool with the crop as input and the saved prompt; request a transparent PNG for cutouts, then run `.pi/skills/impeccable/scripts/impeccable embed-prompt <plate> --prompt-file <prompt.txt>` (if you refine the prompt, save and embed the exact text sent). With the API fallback, run `.pi/skills/impeccable/scripts/impeccable generate-image --ref <crop.png> --prompt-file <prompt.txt> --out <plate.png> --size <WxH> --quality high --background transparent` for a cutout, or `--background opaque` otherwise. The API fallback embeds the prompt and records the background in the sidecar. The output must be PNG; the fallback requests native alpha and performs no chroma-keying.
 4. Open the plate beside the crop and compare subject, placement, scale, palette, and style. For cutouts, verify a real alpha channel and inspect composites on light and dark grounds: white paint must stay solid, interior holes must clear, and fine edges must avoid halos. Inspect glass and soft shadows carefully; partial alpha alone does not ensure convincing translucency. Never chroma-key native transparent output or flatten it before saving. If a native tool returns opaque pixels or a painted checkerboard, retry with the API fallback when available; otherwise report the transparency blocker. On a visual miss, tighten the prompt and regenerate once. Two misses on one region: keep the better plate, mark it `needs_parent_review`, and name the drift. The parent runs the plates gate after all assets exist; report `unscored` until a gate score is available.
+5. A frame plate (a window, a doorway, an arch) is a transparent cutout with an opening: generate it with a transparent background and keep the opening fully transparent. Verify the alpha inside the opening before saving: no baked view, no glow or vignette halo across it. The content seen through the opening is its own image region; produce it separately at the opening's size.
 
 Do not redesign. Do not add objects, restyle, or reinterpret; the comp was approved as it is. Do not touch the page code, the spec, or the comp. Do not produce anything the spec does not list; a region the parent forgot goes back as a one-line note, not a plate.