@gentbajko/slopify 2.0.1 → 2.0.3

package/dist/adapters/alignment/cache.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { createReadStream, createWriteStream } from "node:fs";
-import { mkdir, mkdtemp, rename, rm, stat } from "node:fs/promises";
+import { chmod, copyFile, mkdir, mkdtemp, rename, rm, stat } from "node:fs/promises";
 import { join } from "node:path";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
@@ -18,6 +18,8 @@ export async function prepareModel(input, deps = { model: alignmentModel, fetch:
     const target = join(input.cacheDir, deps.model.filename);
     if (await verified(target, deps.model, input.signal))
         return target;
+    if (input.seed !== undefined && (await verified(input.seed, deps.model, input.signal)))
+        return seedModel(input, input.seed, target);
     let lastFailure;
     for (let attempt = 1; attempt <= 3; attempt += 1) {
         try {
@@ -127,6 +129,20 @@ async function downloadModel(input, deps, target) {
         await rm(staging, { recursive: true, force: true });
     }
 }
+async function seedModel(input, seed, target) {
+    const staging = await mkdtemp(join(input.cacheDir, ".alignment-seed-"));
+    try {
+        const part = join(staging, "model.part");
+        await copyFile(seed, part);
+        await chmod(part, 0o600);
+        input.signal.throwIfAborted();
+        await rename(part, target);
+        return target;
+    }
+    finally {
+        await rm(staging, { recursive: true, force: true });
+    }
+}
 function interrupted(cause) {
     const error = new Error("The subtitle model download was interrupted.", { cause });
     error.name = "SubtitleModelDownloadInterrupted";

package/dist/adapters/alignment/prefetch.js

@@ -0,0 +1,35 @@
+import { mkdir, readFile, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { prepareModel } from "./cache.js";
+import { claimWorker } from "./lock.js";
+// Readies the subtitle model when the app starts, so the first captioned render never waits
+// on a 95 MB download in the middle of a run. It takes the worker lock, so a render that
+// starts meanwhile waits for this copy rather than fetching a second one.
+export async function prefetchModel(input, deps) {
+    await mkdir(input.cacheDir, { recursive: true, mode: 0o700 });
+    await clearOwnLock(input.cacheDir);
+    const release = await claimWorker(input.cacheDir, input.signal);
+    try {
+        return await prepareModel({ cacheDir: input.cacheDir, seed: input.seed, signal: input.signal }, deps);
+    }
+    finally {
+        await release();
+    }
+}
+// The lock names its holder by pid. A lock that names this process when the app has only
+// just started was left by an earlier run: in a container the app is always pid 1, so the
+// liveness check in claimWorker would take it for a live holder and wait forever.
+async function clearOwnLock(cacheDir) {
+    const path = join(cacheDir, "alignment-worker.lock");
+    let owner;
+    try {
+        owner = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return;
+        throw error;
+    }
+    if (Number(owner) === process.pid)
+        await rm(path, { force: true });
+}

package/dist/adapters/alignment/protocol.js

@@ -24,5 +24,15 @@ export const workerMessage = z.discriminatedUnion("type", [
         })),
     }),
     omissionSchema.extend({ type: z.literal("omission") }),
-    z.object({ type: z.literal("error"), message: z.string() }),
+    z.object({
+        type: z.literal("error"),
+        message: z.string(),
+        mismatch: z
+            .object({
+            at: z.number().finite().nonnegative(),
+            expected: z.string().max(2000),
+            heard: z.string().max(2000),
+        })
+            .optional(),
+    }),
 ]);

package/dist/adapters/alignment/runner.js

@@ -1,4 +1,5 @@
 import { fork } from "node:child_process";
+import { SubtitleMismatch, } from "../../kernel/ports/subtitles.js";
 import { workerMessage } from "./protocol.js";
 export async function runAlignmentWorker(input, signal, onProgress, worker = new URL("./worker.js", import.meta.url), onOmission) {
     signal.throwIfAborted();
@@ -65,7 +66,9 @@ export async function runAlignmentWorker(input, signal, onProgress, worker = new
                 }
             }
             else if (message.type === "error")
-                finish(new Error(message.message));
+                finish(message.mismatch === undefined
+                    ? new Error(message.message)
+                    : new SubtitleMismatch(message.message, message.mismatch.at, message.mismatch.expected, message.mismatch.heard));
             else
                 finish(undefined, message.words.map(({ confidence, ...word }) => ({
                     ...word,

package/dist/adapters/alignment/worker.js

@@ -1,5 +1,6 @@
 import { open, readFile, stat } from "node:fs/promises";
 import * as ort from "onnxruntime-web/wasm";
+import { SubtitleMismatch } from "../../kernel/ports/subtitles.js";
 import { mismatch } from "./ctc.js";
 import { workerInput } from "./protocol.js";
 import { speechWords } from "./text.js";
@@ -13,7 +14,13 @@ process.once("message", (raw) => {
         send({ type: "error", message: "The subtitle worker received an invalid request." });
         return;
     }
-    run(input.data).then((words) => send({ type: "done", words }), (error) => send({ type: "error", message: error instanceof Error ? error.message : String(error) }));
+    run(input.data).then((words) => send({ type: "done", words }), (error) => send({
+        type: "error",
+        message: error instanceof Error ? error.message : String(error),
+        ...(error instanceof SubtitleMismatch
+            ? { mismatch: { at: error.at, expected: error.expected, heard: error.heard } }
+            : {}),
+    }));
 });
 function send(message) {
     process.send?.(message);
@@ -64,11 +71,20 @@ async function run(input) {
             const finalWindow = sampleAt + count >= totalSamples;
             const complete = finalWindow && cursor + candidate.length === source.length;
             const cutoff = finalWindow ? count / sampleRate : count / sampleRate - overlapSeconds;
-            const recovered = alignSpeechWindow(logits.data, frames, candidate, complete, cutoff, cursor === 0 ? 0 : omissionBudget - omitted);
+            const stuck = () => new SubtitleMismatch(mismatch, sampleAt / sampleRate, snippet(candidate.map((word) => word.text)), snippet(observed.split(/\s+/)));
+            let recovered;
+            try {
+                recovered = alignSpeechWindow(logits.data, frames, candidate, complete, cutoff, cursor === 0 ? 0 : omissionBudget - omitted);
+            }
+            catch (error) {
+                if (error instanceof Error && error.message === mismatch)
+                    throw stuck();
+                throw error;
+            }
             const accepted = recovered.words;
             const last = accepted.at(-1);
             if (last === undefined)
-                throw new Error(mismatch);
+                throw stuck();
             if (recovered.skipped > 0) {
                 omitted += recovered.skipped;
                 send({
@@ -95,7 +111,7 @@ async function run(input) {
                 tensor.dispose();
         }
         if (cursor !== source.length || output.length === 0)
-            throw new Error(mismatch);
+            throw new SubtitleMismatch(mismatch, sampleAt / sampleRate, snippet(source.slice(cursor).map((word) => word.text)), "");
         // A substantial spoken tail absent from the transcript is a mismatch too.
         while (sampleAt + sampleRate < totalSamples) {
             const count = Math.min(windowSeconds * sampleRate, totalSamples - sampleAt);
@@ -110,7 +126,7 @@ async function run(input) {
                 if (logits !== undefined &&
                     logits.data instanceof Float32Array &&
                     greedy(logits.data, logits.dims[1] ?? 0).replace(/[^A-Z]/g, "").length > 8)
-                    throw new Error(mismatch);
+                    throw new SubtitleMismatch(mismatch, sampleAt / sampleRate, "", snippet(greedy(logits.data, logits.dims[1] ?? 0).split(/\s+/)));
                 for (const tensor of Object.values(result))
                     tensor.dispose();
             }
@@ -140,6 +156,13 @@ function candidates(source, cursor, observed) {
     }
     return selected;
 }
+// A dozen words: enough to find the place in the text, short enough for an error row.
+function snippet(words) {
+    return words
+        .filter((word) => word !== "")
+        .slice(0, 12)
+        .join(" ");
+}
 function normalize(audio) {
     let mean = 0;
     for (const value of audio)

package/dist/adapters/explain.js

@@ -0,0 +1,93 @@
+// The sentences a failed provider call shows. Whatever an adapter throws becomes the stage's
+// failure reason on the project page, read by someone who only wants the video, so each one
+// says what failed, the likely cause and the next step, using the names on screen. The
+// provider's own words stay in, quoted after the plain sentence, because they are often the
+// only clue to a problem Slopify cannot see. Keys never reach here: callers redact first.
+// A provider's error body can be a whole HTML page; the first few hundred characters say why.
+const detailMax = 300;
+export function missingKey(provider) {
+    return `No ${provider} API key is saved. Add one in Settings → Providers, then use Retry stage.`;
+}
+export const refreshList = "refresh the list";
+export const checkChoice = "Check the provider and model chosen in the Providers section of Edit project, then use Retry stage.";
+export function httpFailure(failure) {
+    const { provider, status } = failure;
+    const said = quoted(failure.label ?? `error ${String(status)}`, failure.detail);
+    const next = failure.next ?? "use Retry stage";
+    if (status === 401) {
+        return `${provider} did not accept the API key${said}. The key may be wrong, expired or revoked: paste a current key in Settings → Providers, then ${next}.`;
+    }
+    if (status === 403) {
+        return `${provider} refused access${said}. The API key may not be allowed to use this model, or the account needs attention: check your ${provider} account and the key in Settings → Providers, then ${next}.`;
+    }
+    if (status === 402) {
+        return `${provider} says the account is out of credits${said}. Add credits on the ${provider} website, then ${next}.`;
+    }
+    if (status === 429) {
+        return `${provider} is limiting requests${said}. Too many requests were sent at once or the plan's quota is used up: wait a few minutes or check your ${provider} usage and billing, then ${next}.`;
+    }
+    if (status >= 400 && status < 500) {
+        return `${provider} rejected the ${failure.subject ?? "request"}${said}. ${failure.fix ?? (failure.next === undefined ? checkChoice : `Check the key in Settings → Providers, then ${next}.`)}`;
+    }
+    if (status >= 500) {
+        return `${provider} had a problem on its side${said}. This is usually temporary: wait a few minutes, then ${next}.`;
+    }
+    return `${provider} answered with an unexpected error${said}. ${failure.next === undefined ? "Use Retry stage" : "Try again"}; if it keeps failing, use Download diagnostics in Settings and report it.`;
+}
+// A failure the provider reported inside an otherwise successful answer, with no status.
+export function providerSaid(provider, what, detail, next) {
+    return `${provider} ${what}${quoted("", detail)}. ${next}`;
+}
+export function unreadable(provider) {
+    return `${provider} sent back an answer Slopify could not read. This is usually temporary: use Retry stage; if it keeps happening, use Download diagnostics in Settings and report it.`;
+}
+export function droppedStream(provider) {
+    return `The connection to ${provider} dropped before the answer was complete. Check your internet connection, then use Retry stage.`;
+}
+export function noAudio(provider) {
+    return `${provider} finished without sending any audio. Use Retry stage; if it keeps happening, check the voice in Settings → Voices.`;
+}
+export function noImage(provider) {
+    return `${provider} finished without sending an image. Use Retry stage; if it keeps happening, reword the image prompt in the Images section of Edit project or choose another image model in its Providers section.`;
+}
+export function refusedImage(provider, detail) {
+    return `${provider} refused to make this image under its content rules${quoted("", detail)}. Reword the image prompt in the Images section of Edit project, or choose another image provider in its Providers section.`;
+}
+// A narration request the provider turned down is most often a voice that no longer exists
+// or a part longer than the model takes.
+export function voiceFix(voiceId) {
+    return `Check that voice "${voiceId}" still exists in Settings → Voices and that each narration part fits the model's length limit (Chunking, in the Providers section of Edit project), then use Retry stage.`;
+}
+export function internalError(what) {
+    return `Slopify hit an internal error (${what}). Use Retry stage; if it happens again, use Download diagnostics in Settings and report it.`;
+}
+const cliNames = {
+    claude: "Claude Code CLI",
+    "claude-code": "Claude Code CLI",
+    codex: "Codex CLI",
+    gemini: "Gemini CLI",
+};
+// A configured path (`/opt/bin/claude`, `C:\\tools\\codex.cmd`) still names the CLI the user chose.
+export function cliName(binary) {
+    const base = commandOf(binary);
+    return cliNames[base] ?? `"${base}" CLI`;
+}
+// What to type in a terminal to run it.
+export function commandOf(binary) {
+    return (binary.split(/[\\/]/).at(-1) ?? binary).replace(/\.(?:cmd|exe|bat|js|mjs)$/i, "");
+}
+// An error the CLI itself reported, in its own words, with the step that most often fixes it.
+export function cliReported(binary, detail, next) {
+    return `The ${cliName(binary)} reported an error${quoted("", detail)}. ${next}`;
+}
+export function cliCheck(binary) {
+    return `Use Retry stage; if it keeps failing, run ${commandOf(binary)} in a terminal to check it works and is signed in, or choose another model in the Providers section of Edit project.`;
+}
+// ` (error 401: "Unauthorized")`, ` (error 401)`, ` ("Unauthorized")`, or nothing.
+export function quoted(label, detail) {
+    const text = detail.trim();
+    const clipped = text.length > detailMax ? `${text.slice(0, detailMax)}…` : text;
+    if (clipped === "")
+        return label === "" ? "" : ` (${label})`;
+    return label === "" ? ` ("${clipped}")` : ` (${label}: "${clipped}")`;
+}

package/dist/adapters/ffmpeg.js

@@ -15,7 +15,7 @@ export async function prepareFfmpeg(deps) {
         return override;
     }
     if (typeof deps.bundled !== "string" || deps.bundled === "") {
-        throw new Error(`No ffmpeg build is available for this platform. ${remedy}`);
+        throw new Error(`Slopify has no built-in copy of ffmpeg (the tool it uses to make video) for this kind of computer. Install ffmpeg, then restart Slopify. ${remedy}`);
     }
     if (existsSync(deps.bundled)) {
         await verify(deps.bundled);
@@ -58,7 +58,7 @@ export async function prepareFfmpeg(deps) {
         rmSync(staging, { recursive: true, force: true });
     }
 }
-const remedy = "You can also set SLOPIFY_FFMPEG (or FFMPEG_BIN) to a working ffmpeg executable.";
+const remedy = "You can also set the SLOPIFY_FFMPEG (or FFMPEG_BIN) environment variable to the full path of a working ffmpeg.";
 async function verify(bin) {
     try {
         const { stdout } = await promisify(execFile)(bin, ["-version"], {
@@ -70,7 +70,7 @@ async function verify(bin) {
             throw new Error("the executable did not identify itself as ffmpeg");
     }
     catch (error) {
-        throw new Error(`ffmpeg at ${bin} could not be started. ${remedy} ${detail(error)}`);
+        throw new Error(`ffmpeg at ${bin} could not be started. Reinstall ffmpeg or check your antivirus has not quarantined it, then restart Slopify. ${remedy} ${detail(error)}`);
     }
 }
 function detail(error) {

package/dist/adapters/host-cli/index.js

@@ -3,6 +3,7 @@ import { bridgeLimits, hostFaultSchema, hostFrameSchema, hostHealthSchema, hostI
 import { isProviderError, providerError } from "../../kernel/ports/model.js";
 import { sniffImage } from "../image/bytes.js";
 import { hostRequest, hostUnavailable, readHostBytes, } from "./transport.js";
+const tooBigForHost = "Slopify could not send this request to the host helper because it is larger than, or shaped differently from, what the helper accepts. Make the inputs shorter in Edit project, then use Retry stage; if it happens again, use Download diagnostics in Settings and report it.";
 export function createHostCliClient(options) {
     async function request(input) {
         if (!options.directory)
@@ -88,7 +89,10 @@ export function createHostCliClient(options) {
                     ...(req.webSearch === undefined ? {} : { webSearch: req.webSearch }),
                 });
                 if (!parsed.success)
-                    throw providerError({ kind: "unsupported", message: "Invalid host LLM request." });
+                    throw providerError({
+                        kind: "unsupported",
+                        message: tooBigForHost,
+                    });
                 await ready(req.signal);
                 const response = await request({
                     path: `/v1/llm/${id}`,
@@ -122,7 +126,10 @@ export function createHostCliClient(options) {
                     aspect: req.aspect,
                 });
                 if (!parsed.success)
-                    throw providerError({ kind: "unsupported", message: "Invalid host image request." });
+                    throw providerError({
+                        kind: "unsupported",
+                        message: tooBigForHost,
+                    });
                 await ready(req.signal);
                 const response = await request({
                     path: "/v1/image",

package/dist/adapters/host-cli/transport.js

@@ -8,8 +8,8 @@ export function hostUnavailable(submitted = false) {
     return providerError({
         kind: "unavailable",
         message: submitted
-            ? "The host CLI connection ended without a reliable result; the result may be uncertain. Review the affected rebuild before retrying."
-            : "Host helper unavailable. Run npx @gentbajko/slopify@latest --docker on the host to set it up or check its service.",
+            ? "The connection to the host helper dropped before the CLI's answer arrived, so Slopify cannot tell whether it finished (it may already have used your quota). Check the host helper is still running, then use Retry stage."
+            : "Slopify cannot reach its host helper, which runs the Claude Code, Codex and Gemini CLIs outside Docker. On the host computer, run npx @gentbajko/slopify@latest --docker to set it up or restart it, then use Retry stage.",
     });
 }
 async function tokenAt(directory) {
@@ -33,7 +33,7 @@ export async function hostRequest(options) {
     if (options.body && options.body.byteLength > bridgeLimits.request)
         throw providerError({
             kind: "unsupported",
-            message: "The host provider request exceeds 16 MiB.",
+            message: "This request is larger than the host helper accepts (16 MB), so nothing was sent. Make the inputs shorter in Edit project, or choose an API provider such as OpenRouter in its Providers section, then use Retry stage.",
         });
     let token;
     try {
@@ -121,7 +121,7 @@ export async function readHostBytes(response, maximum) {
             if (length > maximum)
                 throw providerError({
                     kind: "unavailable",
-                    message: "Host response exceeded its size limit.",
+                    message: "The host helper sent back more data than Slopify accepts, so the answer was dropped. Use Retry stage; if it happens again, use Download diagnostics in Settings and report it.",
                 });
             chunks.push(value);
         }

package/dist/adapters/image/bytes.js

@@ -40,7 +40,7 @@ export async function downloadImage(download) {
         // quoted back - a fal or Replicate delivery link carries its own signature.
         throw providerError({
             kind: "other",
-            message: `${download.provider} answered ${String(response.status)} for the image it said it had made`,
+            message: `${download.provider} made the image, but Slopify could not download it (error ${String(response.status)}). Check your internet connection, then use Retry stage.`,
         });
     }
     const bytes = new Uint8Array(await response.arrayBuffer());
@@ -48,7 +48,7 @@ export async function downloadImage(download) {
     if (mime === undefined) {
         throw providerError({
             kind: "other",
-            message: `${download.provider}'s image link answered with ${describeBytes(bytes)} rather than a PNG or a JPEG`,
+            message: `${download.provider} sent back something that is not a PNG or JPEG image (${describeBytes(bytes)}). Use Retry stage; if it keeps happening, choose another image model in the Providers section of Edit project.`,
         });
     }
     return { bytes, mime };

package/dist/adapters/image/codex-output.js

@@ -8,23 +8,23 @@ const maxOutputBytes = 32 * 1024 * 1024;
 function unavailable(detail) {
     return providerError({
         kind: "unavailable",
-        message: `Codex finished, but ${detail}. An image may already exist in Codex; review before retrying.`,
+        message: `The Codex CLI finished, but Slopify could not collect the image: ${detail}. Use Retry stage to make it again (this uses your Codex quota again).`,
     });
 }
 export function codexGeneratedImage(env, threadId, startedAt) {
     if (!z.uuid().safeParse(threadId).success || threadId === undefined)
-        throw unavailable("its image session could not be identified");
+        throw unavailable("the image job could not be identified");
     const root = join(resolve(env.CODEX_HOME || join(env.HOME || homedir(), ".codex")), "generated_images");
     const directory = join(root, threadId);
     try {
         for (const path of [root, directory]) {
             const entry = lstatSync(path);
             if (!entry.isDirectory() || entry.isSymbolicLink())
-                throw unavailable("its image directory is unsafe");
+                throw unavailable("Codex's image folder is not a plain folder");
         }
         const canonical = realpathSync(directory);
         if (canonical !== join(realpathSync(root), threadId))
-            throw unavailable("its image directory changed");
+            throw unavailable("Codex's image folder moved while it was being read");
         // Codex 0.155.1 omits image items from exec JSONL. Its artifact contract is
         // generated_images/<thread.started ID>/<sanitized tool call ID>.png.
         const dir = opendirSync(directory);
@@ -32,11 +32,11 @@ export function codexGeneratedImage(env, threadId, startedAt) {
         try {
             const entry = dir.readSync();
             if (entry === null)
-                throw unavailable("no image was saved for this session");
+                throw unavailable("no image was saved");
             if (dir.readSync() !== null)
-                throw unavailable("more than one output was saved for this session");
+                throw unavailable("more than one file was saved");
             if (!entry.isFile() || !/^[a-zA-Z0-9_-]+\.png$/.test(entry.name))
-                throw unavailable("its image output is unsafe");
+                throw unavailable("the saved file is not a plain image file");
             name = entry.name;
         }
         finally {
@@ -45,7 +45,7 @@ export function codexGeneratedImage(env, threadId, startedAt) {
         const path = join(directory, name);
         const before = lstatSync(path);
         if (!before.isFile() || before.isSymbolicLink() || realpathSync(path) !== join(canonical, name))
-            throw unavailable("its image output is unsafe");
+            throw unavailable("the saved file is not a plain image file");
         const fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
         try {
             const stat = fstatSync(fd);
@@ -56,7 +56,7 @@ export function codexGeneratedImage(env, threadId, startedAt) {
                 stat.size === 0 ||
                 stat.size > maxOutputBytes ||
                 stat.mtimeMs < Math.floor(startedAt / 1000) * 1000)
-                throw unavailable("its image output is stale or unsafe");
+                throw unavailable("the saved file is empty, too large, older than this job, or not a plain file");
             const bytes = Buffer.alloc(stat.size + 1);
             let length = 0;
             while (length < bytes.length) {
@@ -71,11 +71,11 @@ export function codexGeneratedImage(env, threadId, startedAt) {
                 after.mtimeMs !== stat.mtimeMs ||
                 after.ctimeMs !== stat.ctimeMs ||
                 realpathSync(directory) !== canonical)
-                throw unavailable("its image changed while being collected");
+                throw unavailable("the file changed while it was being read");
             const image = bytes.subarray(0, length);
             const mime = sniffImage(image);
             if (mime === undefined)
-                throw unavailable("its output is not a PNG or JPEG image");
+                throw unavailable("the saved file is not a PNG or JPEG image");
             return { bytes: image, mime };
         }
         finally {
@@ -85,6 +85,6 @@ export function codexGeneratedImage(env, threadId, startedAt) {
     catch (error) {
         if (isProviderError(error))
             throw error;
-        throw unavailable("its saved image could not be read");
+        throw unavailable("the saved file could not be read");
     }
 }

package/dist/adapters/image/codex.js

@@ -4,6 +4,7 @@ import { join } from "node:path";
 import { z } from "zod";
 import { redact } from "../../kernel/log.js";
 import { providerError } from "../../kernel/ports/model.js";
+import { cliReported, quoted, refusedImage } from "../explain.js";
 import { cliLoginError } from "../llm/cli-login-error.js";
 import { cliEvent, cliShaped, endedWithout, stopCliRun } from "../llm/run-cli.js";
 import { lines } from "../llm/sse-lines.js";
@@ -87,7 +88,10 @@ export function codexImage(deps) {
         models: async () => [codexImageModel],
         generate: async (req) => {
             if (req.model !== codexImageModel.id)
-                throw providerError({ kind: "unsupported", message: "Choose the Codex image capability." });
+                throw providerError({
+                    kind: "unsupported",
+                    message: "The Codex CLI makes images only with its own image model. Choose that model for images in the Providers section of Edit project, then use Retry stage.",
+                });
             req.signal.throwIfAborted();
             const directory = mkdtempSync(join(tmpdir(), "slopify-codex-image-"));
             const env = imageEnvironment(directory, deps.env ?? process.env);
@@ -102,7 +106,10 @@ export function codexImage(deps) {
                     });
                 }
                 catch {
-                    throw providerError({ kind: "unsupported", message: "Could not start the Codex CLI." });
+                    throw providerError({
+                        kind: "unsupported",
+                        message: "The Codex CLI could not be started. Check it is installed and set up in Settings → Providers, then use Retry stage.",
+                    });
                 }
                 let completed = false;
                 let unavailable = false;
@@ -115,7 +122,7 @@ export function codexImage(deps) {
                         if (threadId !== undefined)
                             throw providerError({
                                 kind: "unavailable",
-                                message: "Codex reported more than one image session. Review before retrying.",
+                                message: "The Codex CLI started more than one image job for one image, so Slopify cannot tell which result is right (both may have used your quota). Use Retry stage to make the image again.",
                             });
                         threadId = cliShaped(binary, z.object({ thread_id: z.string() }), event.value).thread_id;
                     }
@@ -128,7 +135,9 @@ export function codexImage(deps) {
                             throw login;
                         throw providerError({
                             kind: /refus|content.policy|safety/i.test(message) ? "refusal" : "other",
-                            message: redact(message),
+                            message: /refus|content.policy|safety/i.test(message)
+                                ? refusedImage("The Codex CLI", redact(message))
+                                : cliReported(binary, redact(message), imageNext),
                         });
                     }
                     else if (event.type === "error") {
@@ -140,7 +149,9 @@ export function codexImage(deps) {
                             kind: /image.generation|image tool|feature.*unavailable/i.test(message)
                                 ? "unsupported"
                                 : "other",
-                            message: redact(message),
+                            message: /image.generation|image tool|feature.*unavailable/i.test(message)
+                                ? `The Codex CLI cannot make images${quoted("", redact(message))}. ${cannotDraw}`
+                                : cliReported(binary, redact(message), imageNext),
                         });
                     }
                     else if (event.type === "item.completed") {
@@ -154,7 +165,10 @@ export function codexImage(deps) {
                 const ended = await run.ended;
                 req.signal.throwIfAborted();
                 if (ended.error !== null)
-                    throw providerError({ kind: "unsupported", message: "Could not start the Codex CLI." });
+                    throw providerError({
+                        kind: "unsupported",
+                        message: "The Codex CLI could not be started. Check it is installed and set up in Settings → Providers, then use Retry stage.",
+                    });
                 if (ended.code !== 0 || !completed)
                     throw (cliLoginError("codex", run.stderr()) ??
                         providerError({
@@ -164,7 +178,7 @@ export function codexImage(deps) {
                 if (unavailable)
                     throw providerError({
                         kind: "unsupported",
-                        message: "This Codex install cannot generate images.",
+                        message: `The Codex CLI cannot make images. ${cannotDraw}`,
                     });
                 return codexGeneratedImage(env, threadId, startedAt);
             }
@@ -191,11 +205,13 @@ async function* bounded(source, maximum) {
         if (size > maximum)
             throw providerError({
                 kind: "other",
-                message: "Codex wrote too much image progress output.",
+                message: "The Codex CLI sent far more output than an image job should, so Slopify stopped it. Use Retry stage; if it keeps happening, update the Codex CLI to the latest version.",
             });
         yield chunk;
     }
 }
+const imageNext = "Use Retry stage; if it keeps failing, run codex in a terminal to check it works and is signed in, or choose another image provider in the Providers section of Edit project.";
+const cannotDraw = "Update the Codex CLI and check your ChatGPT plan includes image generation, or choose another image provider in the Providers section of Edit project.";
 function imageEnvironment(directory, source) {
     const env = { PWD: directory };
     const allowed = [

package/dist/adapters/image/fal.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { redact } from "../../kernel/log.js";
 import { providerError } from "../../kernel/ports/model.js";
+import { httpFailure, missingKey, noImage, unreadable } from "../explain.js";
 import { retryAfter } from "../retry-after.js";
 import { downloadImage } from "./bytes.js";
 // The HTTP gateway adapter for fal.ai: `fetch` and the downloader beside this file, no SDK.
@@ -88,12 +89,12 @@ export function falImage(deps) {
             refused(answer, req.prompt);
             const first = answer.images[0];
             if (first === undefined) {
-                throw providerError({ kind: "other", message: "fal answered with no image" });
+                throw providerError({ kind: "other", message: noImage("fal.ai") });
             }
             // The download rides inside the attempt: a link that 404s is a failed attempt.
             return await downloadImage({
                 fetch: deps.fetch,
-                provider: "fal",
+                provider: "fal.ai",
                 url: first.url,
                 signal: req.signal,
             });
@@ -104,7 +105,7 @@ function keyOf(deps) {
     // `missing_key`, not `auth`, because that rule makes it terminal.
     const key = deps.key();
     if (key === undefined || key === "") {
-        throw providerError({ kind: "missing_key", message: "no fal key is stored" });
+        throw providerError({ kind: "missing_key", message: missingKey("fal.ai") });
     }
     return key;
 }
@@ -116,7 +117,7 @@ function refused(answer, prompt) {
     if (flags.length > 0 && flags.every((flagged) => flagged)) {
         throw providerError({
             kind: "refusal",
-            message: `fal's safety checker rejected every image for this prompt: ${redact(prompt)}`,
+            message: `fal.ai's safety checker blocked the image for this prompt: "${redact(prompt)}". Reword the image prompt in the Images section of Edit project, or choose another image provider in its Providers section.`,
         });
     }
 }
@@ -140,7 +141,12 @@ async function failure(response) {
     const retryAfterMs = retryAfter(response.headers.get("retry-after"));
     return providerError({
         kind: kindOf(response.status),
-        message: `fal answered ${String(response.status)}: ${message}`,
+        message: httpFailure({
+            provider: "fal.ai",
+            status: response.status,
+            detail: message,
+            subject: "image request",
+        }),
         ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
     });
 }
@@ -160,7 +166,7 @@ function parse(text) {
     if (!parsed.success) {
         throw providerError({
             kind: "other",
-            message: "fal's answer was not in the shape this app can read",
+            message: unreadable("fal.ai"),
         });
     }
     return parsed.data;