@ishlabs/cli 0.27.0 → 0.28.0

package/dist/lib/local-sim/types.d.ts

@@ -27,7 +27,7 @@ export interface LocalSimInitResponse {
     participant_background: Record<string, unknown> | null;
     participant_language: string | null;
     config: Record<string, unknown>;
-    context_values: ContextValue[];
+    context_values: WireContextValue[];
     max_interactions: number;
     agent_model: string;
     dom_model: string;
@@ -40,6 +40,32 @@ export interface LocalSimAssignment {
     instructions: string;
     sequence: number;
 }
+/**
+ * Wire shape of a context value exactly as the backend serializes it
+ * (ish-backend `app/runs/values.py` `ContextValue` → `/simulation/local/init`):
+ * the identifier field is `key` (NOT `name`), and `requires_resolution` is the
+ * secret-vs-variable discriminator (NO `type` field). The CLI normalizes this
+ * into the internal {@link ContextValue} shape at ingestion via
+ * {@link normalizeContextValues}.
+ *
+ * History: the internal shape below has used `name`/`type` since v0.7.0 while the
+ * backend has always sent `key`/`requires_resolution`. Because the two were
+ * assumed identical and consumed without mapping, every `resolveTextValue`
+ * lookup (`find(v => v.name === action.value)`) silently missed and the agent
+ * typed the literal key (e.g. `LOGIN_USERNAME`) into the field on every
+ * platform. Keep this interface faithful to the wire so the mismatch can't
+ * recur unnoticed.
+ */
+export interface WireContextValue {
+    key: string;
+    description?: string | null;
+    value: string | null;
+    requires_resolution: boolean;
+}
+/**
+ * Internal context-value shape used by the executors / {@link resolveTextValue}.
+ * Produced from {@link WireContextValue} by {@link normalizeContextValues}.
+ */
 export interface ContextValue {
     name: string;
     type: "var" | "secret";

package/dist/lib/local-sim/xcuitest.d.ts

@@ -18,6 +18,19 @@
  * and reuses an already-running runner.
  */
 import { type IosScreen } from "./simctl.js";
+/**
+ * The Return keystroke we feed to WDA's `/wda/keys` for a submit.
+ *
+ * NOT the W3C ENTER code (U+E007): WDA's `/wda/keys` does NOT interpret the
+ * WebDriver special-key PUA codepoints \u2014 it types them LITERALLY. On the
+ * simulator U+E007 renders as a running-shoe emoji, so a submit appended a
+ * stray `\uD83D\uDC5F` to the field (e.g. a search for `Photos` became `Photos\uD83D\uDC5F`,
+ * returning no results and derailing the run) AND never actually submitted.
+ * A plain newline is what WDA's keyboard treats as Return \u2014 it submits
+ * single-line fields and inserts a line break in multiline ones, with no glyph.
+ * Verified on a booted iOS 18 simulator (Settings search).
+ */
+export declare const WDA_RETURN = "\n";
 interface Session {
     port: number;
     baseUrl: string;
@@ -38,6 +51,7 @@ export declare function resolveWdaBundle(): Promise<string>;
  */
 export declare function ensureWda(udid: string, opts?: {
     bundleId?: string;
+    port?: number;
 }): Promise<Session>;
 /** Tear down the WDA session for `udid` (the runner is left for the next run). */
 export declare function closeWda(udid: string): Promise<void>;
@@ -59,9 +73,33 @@ export declare function uiSwipe(udid: string, x1: number, y1: number, x2: number
 export declare function uiText(udid: string, text: string): Promise<void>;
 /**
  * Press a key. Only the idb HID Return keycode (40) is used by ios.ts today;
- * map it to W3C ENTER. Unknown codes are a no-op-safe error.
+ * map it to a newline (see WDA_RETURN). Unknown codes are a no-op-safe error.
  */
 export declare function uiKey(udid: string, keycode: number): Promise<void>;
+/**
+ * Extract the element id from a WDA active-element payload, accepting both the
+ * W3C key and the legacy `ELEMENT` alias. Pure + exported for unit testing the
+ * (fiddly) key handling without a live runner. Returns null when the shape has
+ * no usable id (nothing focused / non-element response).
+ */
+export declare function parseActiveElementId(value: unknown): string | null;
+/**
+ * Clear the currently-focused text field via WDA's native element clear — the
+ * same select-all+delete Appium's `clear()` performs, so it handles multiline
+ * and arbitrary cursor positions correctly.
+ *
+ * Why this exists: `uiText` posts to `/wda/keys`, which APPENDS to the focused
+ * field. Without a clear, re-typing a field (a retry, or a field the app
+ * pre-filled) accumulates text (e.g. `LOGIN_USERNAMELOGIN_USERNAME…`). The
+ * coordinate/vision typing path has no element uuid up front, so we resolve the
+ * focused element with `GET …/element/active`, then `POST …/element/:uuid/clear`.
+ *
+ * Best-effort by design: a non-editable focus (or any WDA hiccup) just returns
+ * false and the caller falls back to the prior append behavior — clearing is an
+ * improvement, never a hard precondition for typing. Returns true when a clear
+ * was actually issued.
+ */
+export declare function uiClearActiveField(udid: string): Promise<boolean>;
 /** Re-export so a future ios.ts can drop the simctl HID constant. */
 export declare const HID_KEY_RETURN = 40;
 export {};

package/dist/lib/local-sim/xcuitest.js

@@ -31,8 +31,19 @@ const WDA_BUNDLE_ID = "com.facebook.WebDriverAgentRunner.xctrunner";
 const DEFAULT_PORT = Number(process.env.ISH_WDA_PORT) || 8100;
 /** WDA's XCTest runtime cold-starts slowly; poll /status up to this long. */
 const STARTUP_TIMEOUT_MS = 75_000;
-/** W3C ENTER key (maps the idb HID Return keycode 40 used by ios.ts). */
-const W3C_ENTER = "\uE007"; // idb HID Return (40) -> W3C ENTER
+/**
+ * The Return keystroke we feed to WDA's `/wda/keys` for a submit.
+ *
+ * NOT the W3C ENTER code (U+E007): WDA's `/wda/keys` does NOT interpret the
+ * WebDriver special-key PUA codepoints \u2014 it types them LITERALLY. On the
+ * simulator U+E007 renders as a running-shoe emoji, so a submit appended a
+ * stray `\uD83D\uDC5F` to the field (e.g. a search for `Photos` became `Photos\uD83D\uDC5F`,
+ * returning no results and derailing the run) AND never actually submitted.
+ * A plain newline is what WDA's keyboard treats as Return \u2014 it submits
+ * single-line fields and inserts a line break in multiline ones, with no glyph.
+ * Verified on a booted iOS 18 simulator (Settings search).
+ */
+export const WDA_RETURN = "\n";
 const sessions = new Map();
 // ── WDA bundle resolution (fetch is wired in the distribution phase) ──────────
 /** Appium's prebuilt WebDriverAgent simulator release we fetch + pin. */
@@ -178,7 +189,10 @@ export async function ensureWda(udid, opts = {}) {
     const existing = sessions.get(udid);
     if (existing && (await statusOk(existing.port)))
         return existing;
-    const port = DEFAULT_PORT;
+    // Each device gets its own WDA runner on its own port so N pooled simulators
+    // don't collide on 8100. The pool allocates the port and passes it in; the
+    // single-device path falls back to DEFAULT_PORT (8100 / $ISH_WDA_PORT).
+    const port = opts.port ?? DEFAULT_PORT;
     if (!(await statusOk(port))) {
         const app = await resolveWdaBundle();
         await simctlRun(["install", udid, app]);
@@ -211,7 +225,9 @@ async function getSession(udid) {
     const s = sessions.get(udid);
     if (s && (await statusOk(s.port)))
         return s;
-    return ensureWda(udid);
+    // Re-ensure on the SAME port if this device had one (a WDA restart mid-run
+    // must not migrate a pooled device back to DEFAULT_PORT).
+    return ensureWda(udid, s ? { port: s.port } : {});
 }
 /** Tear down the WDA session for `udid` (the runner is left for the next run). */
 export async function closeWda(udid) {
@@ -307,13 +323,61 @@ export async function uiText(udid, text) {
 }
 /**
  * Press a key. Only the idb HID Return keycode (40) is used by ios.ts today;
- * map it to W3C ENTER. Unknown codes are a no-op-safe error.
+ * map it to a newline (see WDA_RETURN). Unknown codes are a no-op-safe error.
  */
 export async function uiKey(udid, keycode) {
     if (keycode !== 40)
         throw new IosError(`unsupported WDA keycode: ${keycode}`);
     const s = await getSession(udid);
-    await wdaCall(s.port, "POST", `/session/${s.sessionId}/wda/keys`, { value: [W3C_ENTER] });
+    await wdaCall(s.port, "POST", `/session/${s.sessionId}/wda/keys`, { value: [WDA_RETURN] });
+}
+/**
+ * The W3C WebDriver element-reference key. `GET …/element/active` returns the
+ * focused element under this key (WDA also historically mirrors it as `ELEMENT`).
+ */
+const W3C_ELEMENT_KEY = "element-6066-11e4-a52e-4f735466cecf";
+/**
+ * Extract the element id from a WDA active-element payload, accepting both the
+ * W3C key and the legacy `ELEMENT` alias. Pure + exported for unit testing the
+ * (fiddly) key handling without a live runner. Returns null when the shape has
+ * no usable id (nothing focused / non-element response).
+ */
+export function parseActiveElementId(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const obj = value;
+    const id = obj[W3C_ELEMENT_KEY] ?? obj.ELEMENT;
+    return typeof id === "string" && id.length > 0 ? id : null;
+}
+/**
+ * Clear the currently-focused text field via WDA's native element clear — the
+ * same select-all+delete Appium's `clear()` performs, so it handles multiline
+ * and arbitrary cursor positions correctly.
+ *
+ * Why this exists: `uiText` posts to `/wda/keys`, which APPENDS to the focused
+ * field. Without a clear, re-typing a field (a retry, or a field the app
+ * pre-filled) accumulates text (e.g. `LOGIN_USERNAMELOGIN_USERNAME…`). The
+ * coordinate/vision typing path has no element uuid up front, so we resolve the
+ * focused element with `GET …/element/active`, then `POST …/element/:uuid/clear`.
+ *
+ * Best-effort by design: a non-editable focus (or any WDA hiccup) just returns
+ * false and the caller falls back to the prior append behavior — clearing is an
+ * improvement, never a hard precondition for typing. Returns true when a clear
+ * was actually issued.
+ */
+export async function uiClearActiveField(udid) {
+    try {
+        const s = await getSession(udid);
+        const active = unwrap(await wdaCall(s.port, "GET", `/session/${s.sessionId}/element/active`));
+        const uuid = parseActiveElementId(active);
+        if (!uuid)
+            return false;
+        await wdaCall(s.port, "POST", `/session/${s.sessionId}/element/${uuid}/clear`, {});
+        return true;
+    }
+    catch {
+        return false;
+    }
 }
 /** Re-export so a future ios.ts can drop the simctl HID constant. */
 export const HID_KEY_RETURN = 40;

package/dist/lib/output.d.ts

@@ -46,7 +46,17 @@ export declare class ValidationError extends Error {
     hint?: string | undefined;
     constructor(message: string, valid_options: string[], hint?: string | undefined);
 }
-export declare function outputError(err: unknown, json: boolean): void;
+/**
+ * Whether an error is worth nudging the user to report via `ish feedback`.
+ * Excludes user-actionable failures — usage/validation, auth (login),
+ * not-found, and usage-limit (upgrade) — so the hint stays high-signal and
+ * agents don't reflexively report their own input mistakes. Genuine faults
+ * (5xx, unexpected client errors, unknown throws) get the nudge.
+ */
+export declare function shouldSuggestReport(err: unknown): boolean;
+export declare function outputError(err: unknown, json: boolean, opts?: {
+    suggestReport?: boolean;
+}): void;
 export declare function printTable(headers: string[], rows: string[][]): void;
 export declare function printKeyValue(obj: Record<string, unknown>, indent?: string): void;
 export declare function formatWorkspaceList(workspaces: Record<string, unknown>[], json: boolean): void;

package/dist/lib/output.js

@@ -562,8 +562,48 @@ function remapEntityName(message) {
         .replace(/\bAttachment not found\b/g, "Source not found")
         .replace(/\battachment not found\b/g, "source not found");
 }
-export function outputError(err, json) {
+// Shown after a genuine fault so the operating agent (the CLI's primary user)
+// knows it can hand the failure straight to the ish team. Kept short.
+const REPORT_HINT_HUMAN = 'Looks like a bug? Report it: ish feedback "what you were trying to do" (add --health for setup/sim issues)';
+const REPORT_HINT_JSON = 'ish feedback "<what you were trying to do>" — add --health for setup/sim issues';
+/**
+ * Whether an error is worth nudging the user to report via `ish feedback`.
+ * Excludes user-actionable failures — usage/validation, auth (login),
+ * not-found, and usage-limit (upgrade) — so the hint stays high-signal and
+ * agents don't reflexively report their own input mistakes. Genuine faults
+ * (5xx, unexpected client errors, unknown throws) get the nudge.
+ */
+export function shouldSuggestReport(err) {
+    if (err instanceof ValidationError)
+        return false;
+    if (err instanceof ApiError) {
+        if (err.status === 400 ||
+            err.status === 401 ||
+            err.status === 402 || // insufficient credits — buy credits, not a bug
+            err.status === 403 ||
+            err.status === 404 ||
+            err.status === 422) {
+            return false;
+        }
+        if (err.error_code === "usage_limit_reached")
+            return false;
+        return true;
+    }
+    if (err instanceof Error) {
+        const tagged = err;
+        if (err.name === "ValidationError")
+            return false;
+        if (tagged.error_code === "auth_failed")
+            return false;
+        if (tagged.error_kind === "ConfirmationRequired")
+            return false;
+        return true;
+    }
+    return true;
+}
+export function outputError(err, json, opts = {}) {
     const suggestions = suggestionsForError(err);
+    const report = opts.suggestReport === true;
     if (err instanceof ApiError) {
         // Surface backend-structured fields when present in the response body
         // (e.g. 422 errors return `errors: [{loc, msg, type, input, allowed_values}]`,
@@ -621,6 +661,7 @@ export function outputError(err, json) {
                 ...(seededAliases && { seeded_but_not_dispatched_aliases: seededAliases }),
                 ...(bodyErrors !== undefined && { errors: bodyErrors }),
                 ...(mergedSuggestions.length > 0 && { suggestions: mergedSuggestions }),
+                ...(report && { report: REPORT_HINT_JSON }),
             }));
         }
         else {
@@ -724,6 +765,7 @@ export function outputError(err, json) {
                 ...(seededIds && { seeded_but_not_dispatched_ids: seededIds }),
                 ...(seededAliases && { seeded_but_not_dispatched_aliases: seededAliases }),
                 ...(mergedSuggestions.length > 0 && { suggestions: mergedSuggestions }),
+                ...(report && { report: REPORT_HINT_JSON }),
             }));
         }
         else {
@@ -736,12 +778,24 @@ export function outputError(err, json) {
     }
     else {
         if (json) {
-            console.error(JSON.stringify({ error: String(err), error_code: "unknown_error", retryable: false }));
+            console.error(JSON.stringify({
+                error: String(err),
+                error_code: "unknown_error",
+                retryable: false,
+                ...(report && { report: REPORT_HINT_JSON }),
+            }));
         }
         else {
             console.error(`Error: ${err}`);
         }
     }
+    // A single human-mode nudge for genuine faults (gated by the caller via
+    // shouldSuggestReport). The JSON branches above carry the same hint as a
+    // `report` field. ValidationError's own JSON branch intentionally omits it
+    // (usage errors aren't bugs); the caller never sets suggestReport there.
+    if (!json && report) {
+        console.error(`  ${c.dim}→ ${REPORT_HINT_HUMAN}${c.reset}`);
+    }
 }
 // --- Entity-specific formatters (human mode) ---
 export function printTable(headers, rows) {

package/dist/lib/paths.d.ts

@@ -27,3 +27,4 @@ export declare function wdaVersionFile(): string;
  */
 export declare function adbBin(): string;
 export declare function connectLockPath(): string;
+export declare function devicePoolLockPath(): string;

package/dist/lib/paths.js

@@ -58,3 +58,6 @@ export function adbBin() {
 export function connectLockPath() {
     return path.join(rootDir(), "connect.lock");
 }
+export function devicePoolLockPath() {
+    return path.join(rootDir(), "device-pool.lock");
+}

package/dist/lib/skill-content.js

@@ -230,8 +230,11 @@ To hand a study to someone **without an ish account** — a prospect, a stakehol
 - **\`ish person create\` accepts inline flags** (mirrors \`person update\`): the file-only API (\`--file <path>\`) is preserved as an escape hatch but the common path is \`ish person create --name "X" --type ai --country US ...\` — \`--type\` defaults to \`ai\` when \`--file\` is omitted. See \`ish person create --help\` for the full inline-flag set including \`--household\` (MECE rule applies) and \`--accessibility-profile\`.
 - **\`ish status\` now surfaces \`chat_endpoint\`** alongside \`workspace\`/\`study\`/\`ask\`. Stale or orphan active refs get a \`warning\` + \`hint\` field on the affected ref (instead of silently dropping the \`name\`). On \`workspace use <other>\`, the CLI cascade-clears \`study\`/\`ask\`/\`chat_endpoint\` (they belong to the previous workspace).
 - **Share link URL host ≠ API host**: \`ish study share\` prints the backend-built \`share_url\` (the web frontend host). Use it verbatim — never reconstruct the URL from the API host or app URL; they differ. \`ish study unshare\` takes the **raw token** (from \`study share\` / \`study share --list\`), not a study id or alias.
-- **Native app iterations (ios/android) name the app, not a URL**: \`ish iteration create --platform ios --app <bundle-id>\` stores the target as \`app_artifact\` (no URL). The iteration remembers it, so \`ish study run --local\` needs **no \`--app\` on reruns** (it defaults from the iteration). Pass \`--app <path-to.app|.apk>\` only to override with a fresh local build. \`--app\` is optional at create time (omit it for "chosen at run time"). Only \`browser\`/\`figma\` iterations require \`--url\`.
-- **Local runs have no server-side screenshots**: \`ish study run --local\` (including ios/android) writes a per-step HTML debug report to \`~/.ish/debug/sim-*.html\` (path printed at the end of the run) instead of pushing screenshots to the server. \`ish study screenshots list\` on a local-only study finds none — open the debug report instead.
+- **Native app iterations (ios/android) name the app, not a URL**: \`ish iteration create --platform ios --app <bundle-id>\` stores the target as \`app_artifact\` (no URL). \`screen_format\` defaults to **mobile_portrait** for native (vs desktop for browser). The iteration remembers it, so \`ish study run --local\` needs **no \`--app\` on reruns** (it defaults from the iteration). Pass \`--app <path-to.app|.apk>\` only to override with a fresh local build. \`--app\` is optional at create time (omit it for "chosen at run time"). Only \`browser\`/\`figma\` iterations require \`--url\`. Full walkthrough: \`ish docs get-page guides/native-app\`.
+- **Native runs reset state per participant only with a local .app**: with a local \`.app\`/\`.apk\` the runner uninstall+reinstalls before each participant (no state leak). A bare bundle-id / system app (e.g. \`com.apple.reminders\`) can't be reinstalled — it relaunches and warns once that earlier-participant state may persist; pass \`--app <.app>\` or run one participant per study for a clean start.
+- **Parallel native runs**: \`ish study run --local --platform ios|android --parallel N\` drives a **pool of N devices** (iOS: reuses booted simulators + auto-creates the shortfall; Android: reuses online emulators + auto-launches headless emulators from your AVDs), one participant per device, and tears down only what it started. N auto-sizes to host RAM; default 1, max 5 — small machines run fewer + queue, never error. Android needs just **one AVD** (the pool clones it via file-copy — no JDK — and deletes the clones). Browser \`--parallel\` is unchanged.
+- **Local runs still capture per-interaction screenshots**: \`ish study run --local\` (including ios/android) does NOT populate the remote frame-grouped index (\`ish study screenshots list\` reads that and won't show local frames), but per-interaction screenshots ARE captured — read them via \`ish study get <id>\` (each interaction carries \`screenshot_url\`) or the per-step HTML debug report at \`~/.ish/debug/sim-*.html\` (path printed at the end of the run).
+- **\`<entity> use --json\` is capturable**: \`study use\`/\`workspace use\`/\`ask use\` print the human confirmation to stderr and an \`{id, alias, name, active}\` object to stdout under \`--json\`, so \`ish study use s-… --json --get alias\` works.
 
 ## When in doubt
 
@@ -1140,6 +1143,14 @@ table, projection shapes, and the defensive null-handling rules.
   confirmed. The orphan-tunnel-on-startup-404 bug is fixed.
 - The \`Warning: Could not verify token (network error). Proceeding
   anyway.\` stderr line is gone on green runs.
+- On a **genuine fault** (uncategorized client error, 5xx/\`server\`,
+  network, unknown throw) the error envelope adds a \`report\` field and
+  human mode prints a \`→ Looks like a bug? Report it: …\` line. File it
+  with \`ish feedback "what you were doing"\` (add \`--health\` for
+  local/native-run bugs). The nudge is deliberately silent on
+  user-actionable errors (usage, validation, auth, not-found,
+  usage-limit), so when you see it, it's worth reporting. See
+  guides/feedback.
 
 ## Common reshaping → use the CLI, not jq/python
 
@@ -1208,6 +1219,7 @@ ish <command> --help
 |             | study, ask, token validity) — alias \`whoami\`    |                             |
 | \`connect\`   | Cloudflare tunnel exposing localhost            | —                           |
 | \`upgrade\`   | Self-update                                     | —                           |
+| \`feedback\`  | Report a bug / feature request / note to the ish team. \`--health\` attaches setup checks + local-sim logs. | guides/feedback |
 
 ## Discovering flags safely
 

package/dist/lib/upload.d.ts

@@ -16,6 +16,14 @@ export declare function validateFile(filePath: string): Promise<{
     size: number;
     mime: string;
 }>;
+/**
+ * Upload raw bytes to Supabase Storage via the backend's signed URL flow.
+ * Returns the public content_url. The bytes-level core shared by file uploads
+ * and HTML image archiving (no temp file needed).
+ */
+export declare function uploadStudyContentBytes(client: ApiClient, studyId: string, data: Buffer, mime: string, name: string, opts?: {
+    quiet?: boolean;
+}): Promise<string>;
 /**
  * Upload a local file to Supabase Storage via the backend's signed URL flow.
  * Returns the public content_url for use in iteration details.
@@ -40,6 +48,25 @@ export declare function resolveContentUrls(client: ApiClient, studyId: string, c
     mimeTypeOverride?: string;
     quiet?: boolean;
 }): Promise<string[]>;
+/**
+ * Archive every external `<img>` in a text iteration's `content_html` onto the
+ * workspace storage origin, rewriting each `src` to the uploaded URL.
+ *
+ * Why: the render-to-image worker that lets a participant SEE the page
+ * default-denies egress to every origin except workspace storage (SSRF guard).
+ * An `<img>` pointing at the open web is therefore aborted and renders broken.
+ * The frontend's paste pipeline (`cacheHtmlAssets`) already archives images;
+ * this is the CLI-side equivalent so `ish iteration create --content-html`
+ * produces content whose images actually render. It is a focused subset (just
+ * `<img src>` via regex — the CLI has no HTML-parser dependency); inline
+ * `data:` images, relative paths, and non-image responses are left untouched.
+ *
+ * Best-effort: a single image that cannot be fetched/uploaded is left as-is
+ * with a warning rather than failing the whole create.
+ */
+export declare function archiveHtmlImages(client: ApiClient, studyId: string, html: string, opts?: {
+    quiet?: boolean;
+}): Promise<string>;
 /**
  * Resolve text content. If the value starts with '@', read the file at
  * the path that follows (curl-style convention). Otherwise return as-is.

package/dist/lib/upload.js

@@ -96,29 +96,30 @@ export async function validateFile(filePath) {
 // Core upload: 3-step backend-mediated flow
 // ---------------------------------------------------------------------------
 /**
- * Upload a local file to Supabase Storage via the backend's signed URL flow.
- * Returns the public content_url for use in iteration details.
+ * Upload raw bytes to Supabase Storage via the backend's signed URL flow.
+ * Returns the public content_url. The bytes-level core shared by file uploads
+ * and HTML image archiving (no temp file needed).
  */
-export async function uploadStudyContent(client, studyId, filePath, opts) {
-    const resolved = resolvePath(filePath);
-    const { size, mime: detectedMime } = await validateFile(filePath);
-    const mime = opts?.mimeTypeOverride || detectedMime;
-    const name = basename(filePath);
+export async function uploadStudyContentBytes(client, studyId, data, mime, name, opts) {
+    const size = data.byteLength;
     const sizeMB = (size / (1024 * 1024)).toFixed(1);
     const log = (msg) => { if (!opts?.quiet)
         process.stderr.write(msg); };
     // Step 1: Request a signed upload URL from the backend
     log(`Uploading ${name} (${sizeMB} MB)...`);
     const uploadResp = await client.post(`/studies/${studyId}/content/upload`, { content_type: mime, file_size_bytes: size }, { timeout: 60_000 });
-    // Step 2: PUT the raw file bytes to the signed URL
-    const fileBuffer = await readFile(resolved);
+    // Step 2: PUT the raw bytes to the signed URL
     const putResp = await fetch(uploadResp.upload_info.signed_upload_url, {
         method: "PUT",
         headers: {
             "Content-Type": mime,
-            "Content-Length": String(fileBuffer.byteLength),
+            "Content-Length": String(size),
         },
-        body: fileBuffer,
+        // Zero-copy view as Uint8Array<ArrayBuffer>: a Node Buffer's generic
+        // ArrayBufferLike (which includes SharedArrayBuffer) is not a valid fetch
+        // BodyInit, but a plain-ArrayBuffer-backed view is. Node buffers are never
+        // SharedArrayBuffer-backed, so the cast is safe.
+        body: new Uint8Array(data.buffer, data.byteOffset, data.byteLength),
         signal: AbortSignal.timeout(300_000), // 5 min timeout for large files
     });
     if (!putResp.ok) {
@@ -133,6 +134,17 @@ export async function uploadStudyContent(client, studyId, filePath, opts) {
     log(" done.\n");
     return uploadResp.content_url;
 }
+/**
+ * Upload a local file to Supabase Storage via the backend's signed URL flow.
+ * Returns the public content_url for use in iteration details.
+ */
+export async function uploadStudyContent(client, studyId, filePath, opts) {
+    const resolved = resolvePath(filePath);
+    const { mime: detectedMime } = await validateFile(filePath);
+    const mime = opts?.mimeTypeOverride || detectedMime;
+    const fileBuffer = await readFile(resolved);
+    return uploadStudyContentBytes(client, studyId, fileBuffer, mime, basename(filePath), { quiet: opts?.quiet });
+}
 // ---------------------------------------------------------------------------
 // High-level resolvers (URL passthrough or upload)
 // ---------------------------------------------------------------------------
@@ -157,6 +169,91 @@ export async function resolveContentUrls(client, studyId, commaSeparated, opts)
     }
     return results;
 }
+// ---------------------------------------------------------------------------
+// HTML image archiving (text modality)
+// ---------------------------------------------------------------------------
+const MAX_ARCHIVED_IMAGE_BYTES = 15 * 1024 * 1024; // 15 MB per image
+const IMAGE_FETCH_TIMEOUT_MS = 15_000;
+/**
+ * Archive every external `<img>` in a text iteration's `content_html` onto the
+ * workspace storage origin, rewriting each `src` to the uploaded URL.
+ *
+ * Why: the render-to-image worker that lets a participant SEE the page
+ * default-denies egress to every origin except workspace storage (SSRF guard).
+ * An `<img>` pointing at the open web is therefore aborted and renders broken.
+ * The frontend's paste pipeline (`cacheHtmlAssets`) already archives images;
+ * this is the CLI-side equivalent so `ish iteration create --content-html`
+ * produces content whose images actually render. It is a focused subset (just
+ * `<img src>` via regex — the CLI has no HTML-parser dependency); inline
+ * `data:` images, relative paths, and non-image responses are left untouched.
+ *
+ * Best-effort: a single image that cannot be fetched/uploaded is left as-is
+ * with a warning rather than failing the whole create.
+ */
+export async function archiveHtmlImages(client, studyId, html, opts) {
+    const log = (msg) => { if (!opts?.quiet)
+        process.stderr.write(msg); };
+    const imgTags = html.match(/<img\b[^>]*>/gi);
+    if (!imgTags)
+        return html;
+    let result = html;
+    let archived = 0;
+    let failed = 0;
+    const seen = new Map(); // original src -> archived url
+    for (const tag of imgTags) {
+        const srcMatch = tag.match(/\bsrc\s*=\s*("([^"]*)"|'([^']*)')/i);
+        if (!srcMatch)
+            continue;
+        const src = srcMatch[2] ?? srcMatch[3] ?? "";
+        // Only archive remote http(s) images; leave data:/blob:/relative as-is.
+        if (!/^https?:\/\//i.test(src))
+            continue;
+        let archivedUrl = seen.get(src);
+        if (archivedUrl === undefined) {
+            try {
+                archivedUrl = await fetchAndUploadImage(client, studyId, src, archived, opts);
+                seen.set(src, archivedUrl);
+                archived += 1;
+            }
+            catch (e) {
+                failed += 1;
+                const reason = e instanceof Error ? e.message : String(e);
+                log(`  ! could not archive image ${src}: ${reason} (it will not render)\n`);
+                continue;
+            }
+        }
+        // Rewrite this tag: point src at the archived URL and drop srcset so the
+        // browser uses the archived src, not an un-archived srcset candidate.
+        let newTag = tag.replace(srcMatch[0], `src="${archivedUrl}"`);
+        newTag = newTag.replace(/\s+srcset\s*=\s*("[^"]*"|'[^']*')/gi, "");
+        if (newTag !== tag)
+            result = result.replace(tag, newTag);
+    }
+    if (archived > 0 || failed > 0) {
+        log(`Archived ${archived} image(s) to workspace storage${failed ? `, ${failed} failed` : ""}.\n`);
+    }
+    return result;
+}
+async function fetchAndUploadImage(client, studyId, url, index, opts) {
+    const resp = await fetch(url, {
+        signal: AbortSignal.timeout(IMAGE_FETCH_TIMEOUT_MS),
+        redirect: "follow",
+    });
+    if (!resp.ok)
+        throw new Error(`HTTP ${resp.status}`);
+    const ctype = (resp.headers.get("content-type") || "").split(";")[0].trim().toLowerCase();
+    if (!ctype.startsWith("image/")) {
+        throw new Error(`not an image (content-type: ${ctype || "unknown"})`);
+    }
+    const bytes = Buffer.from(await resp.arrayBuffer());
+    if (bytes.byteLength === 0)
+        throw new Error("empty response");
+    if (bytes.byteLength > MAX_ARCHIVED_IMAGE_BYTES) {
+        throw new Error(`image too large (${(bytes.byteLength / (1024 * 1024)).toFixed(1)} MB)`);
+    }
+    const ext = ctype.split("/")[1]?.split("+")[0] || "img";
+    return uploadStudyContentBytes(client, studyId, bytes, ctype, `imported-image-${index}.${ext}`, { quiet: opts?.quiet });
+}
 /**
  * Resolve text content. If the value starts with '@', read the file at
  * the path that follows (curl-style convention). Otherwise return as-is.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ishlabs/cli",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "The command-line interface for ish",
   "type": "module",
   "bin": {
@@ -47,7 +47,7 @@
     "@sentry/node": "^10.13.0",
     "commander": "^13.0.0",
     "http-proxy": "^1.18.1",
-    "playwright-core": "^1.58.2"
+    "playwright-core": "1.59.1"
   },
   "devDependencies": {
     "@types/http-proxy": "^1.17.17",