@gentbajko/slopify 2.0.2 → 2.1.0

package/SUBTITLES.md

@@ -16,7 +16,7 @@ Fonts are copied into the completed project's caption assets, so an existing exp
 
 ## Local model and licenses
 
-Speech inference uses MIT-licensed `onnxruntime-web@1.24.3` in a separate WASM process. The runtime is installed with the package (about 138 MB on disk); model weights are downloaded lazily into `<data-dir>/models/english-subtitles/`.
+Speech inference uses MIT-licensed `onnxruntime-node@1.30.0` (native CPU) in a separate process, with `min(8, CPUs − 1)` threads; set `SLOPIFY_SUBTITLE_THREADS` to override. The npm package bundles CPU builds for Linux x64/arm64, Windows x64/arm64 and Apple silicon macOS (about 220 MB unpacked); Intel Macs have no build, so subtitle timing falls back to the slower single-threaded `onnxruntime-web` there. Its postinstall script only fetches optional CUDA files on Linux x64 and is not needed (the Docker image installs with `--ignore-scripts`); model weights are downloaded lazily into `<data-dir>/models/english-subtitles/`.
 
 Model: [Xenova/wav2vec2-base-960h](https://huggingface.co/Xenova/wav2vec2-base-960h/tree/a19f851b3d42865797e410752b4c570c871e4825), an ONNX conversion of [facebook/wav2vec2-base-960h](https://huggingface.co/facebook/wav2vec2-base-960h), licensed Apache-2.0. Pinned revision: `a19f851b3d42865797e410752b4c570c871e4825`. The quantized model is 95,286,046 bytes, SHA256 `cd5040c147381580ed73258143dd8e0c28e800a09e74ee42ee2b3e8cb4d760a3`; every cached/downloaded model is verified before use.
 

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/threads.js

@@ -0,0 +1,11 @@
+import { availableParallelism } from "node:os";
+// Measured on a 32-thread machine, 5 min of narration in 12 s windows: one native CPU session with
+// 8 intra-op threads ran 37× realtime; 16 threads 31×, 32 threads 20×, 1 thread 20×, and the old
+// single-threaded WASM runtime 4.8×. More threads in one session gets slower, so 8 is the ceiling.
+const maxThreads = 8;
+export function subtitleThreads(env = process.env, cpus = availableParallelism()) {
+    const override = env.SLOPIFY_SUBTITLE_THREADS?.trim();
+    if (override !== undefined && /^[1-9]\d*$/.test(override))
+        return Number(override);
+    return Math.min(maxThreads, Math.max(1, cpus - 1));
+}

package/dist/adapters/alignment/worker.js

@@ -1,8 +1,9 @@
 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";
+import { subtitleThreads } from "./threads.js";
 import { alignSpeechWindow, greedy } from "./window.js";
 const sampleRate = 16000;
 const windowSeconds = 12;
@@ -13,15 +14,19 @@ 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);
 }
 async function run(input) {
-    ort.env.wasm.numThreads = 1;
-    const model = new Uint8Array(await readFile(input.modelPath));
-    const session = await ort.InferenceSession.create(model, { executionProviders: ["wasm"] });
+    const { ort, session } = await openSession(input.modelPath);
     const file = await open(input.pcmPath, "r");
     try {
         const totalSamples = (await stat(input.pcmPath)).size / 4;
@@ -64,11 +69,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 +109,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 +124,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();
             }
@@ -123,6 +137,42 @@ async function run(input) {
         await session.release();
     }
 }
+// One native CPU session per job, as benchmarked; threads.ts records the measured speeds. The
+// native runtime loads its binary on import, so a missing or foreign binary fails there; that
+// system (an Intel Mac has no 1.24 build) falls back to the single-threaded WebAssembly runtime,
+// about 7× slower but the same model, rather than losing captions.
+async function openSession(modelPath) {
+    let native;
+    try {
+        native = await import("onnxruntime-node");
+    }
+    catch (nativeError) {
+        try {
+            const web = await import("onnxruntime-web/wasm");
+            web.env.wasm.numThreads = 1;
+            const session = await web.InferenceSession.create(new Uint8Array(await readFile(modelPath)), {
+                executionProviders: ["wasm"],
+            });
+            return {
+                ort: web,
+                session: session,
+            };
+        }
+        catch {
+            const system = `${process.platform} ${process.arch}`;
+            const reason = nativeError instanceof Error
+                ? (nativeError.message.split("\n")[0] ?? "")
+                : String(nativeError);
+            throw new Error(`Subtitle timing could not start: neither of its speech engines loaded on this computer (${system}): ${reason}. Reinstall Slopify so npm installs the engine for this system, then try again; if it keeps failing, turn subtitles off for this project.`);
+        }
+    }
+    const session = await native.InferenceSession.create(modelPath, {
+        executionProviders: ["cpu"],
+        intraOpNumThreads: subtitleThreads(),
+        interOpNumThreads: 1,
+    });
+    return { ort: native, session };
+}
 function candidates(source, cursor, observed) {
     const selected = [];
     let length = 0;
@@ -140,6 +190,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

@@ -1,8 +1,9 @@
 import { redact } from "../../kernel/log.js";
-import { bridgeLimits, hostFaultSchema, hostFrameSchema, hostHealthSchema, hostImageSchema, hostLlmSchema, hostModelsSchema, hostStatusSchema, } from "../../kernel/ports/host-cli.js";
+import { bridgeLimits, hostFaultSchema, hostFrameSchema, hostHealthSchema, hostImageSchema, hostLlmSchema, hostModelsSchema, hostOpenedSchema, hostOpenFolderSchema, hostStatusSchema, } from "../../kernel/ports/host-cli.js";
 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)
@@ -49,6 +50,30 @@ export function createHostCliClient(options) {
         ...(model.thinkingModes === undefined ? {} : { thinkingModes: model.thinkingModes }),
     }));
     return {
+        openFolder: async (path, signal) => {
+            const parsed = hostOpenFolderSchema.safeParse({ path });
+            if (!parsed.success || !options.directory)
+                return false;
+            // An older helper answers 404 and a refused folder 403; either way the caller shows the path.
+            try {
+                const response = await hostRequest({
+                    directory: options.directory,
+                    path: "/v1/open-folder",
+                    method: "POST",
+                    kind: "metadata",
+                    body: Buffer.from(JSON.stringify(parsed.data)),
+                    signal,
+                });
+                if (response.statusCode !== 200) {
+                    response.destroy();
+                    return false;
+                }
+                return hostOpenedSchema.safeParse(JSON.parse((await readHostBytes(response, bridgeLimits.status)).toString("utf8"))).success;
+            }
+            catch {
+                return false;
+            }
+        },
         status: async (id) => {
             try {
                 const status = await metadata(`/v1/status/${id}`, hostStatusSchema);
@@ -88,7 +113,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 +150,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 = [