ossclip 0.1.26 → 0.1.28

package/src/program.ts

@@ -3,13 +3,13 @@ import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { Command, InvalidArgumentError } from "commander";
 import { z } from "zod/v4";
-import { CleanupLevelSchema, SceneComponentIdSchema } from "@ossclip/core";
+import { CleanupLevelSchema, COVER_MAX_WORDS, SceneComponentIdSchema } from "@ossclip/core";
 import { STUDIO_ENTRY } from "@ossclip/renderer";
 import { loadEnvFiles } from "./env";
 import { ExportFormatSchema, runAnalyze } from "./analyze";
 import { expandHome } from "./paths";
 import { phaseBucketProps } from "./phase-timing";
-import { dictionaryFlag, jumpCutsFlag, produce } from "./produce";
+import { dictionaryFlag, jumpCutsFlag, produce, reviewFlag } from "./produce";
 // The one interactive import that is STATIC rather than `await import()`: the
 // `resetInputSource()` run boundary in `buildProgram` has to run synchronously
 // while the program is being built, and `buildProgram` cannot await. The graph
@@ -60,6 +60,42 @@ export function concurrencyFlag(v: string): number {
   return n;
 }
 
+/**
+ * `<command> [workdir]` → the workdir the user meant.
+ *
+ * ONE spelling of the probe → resolve → pick ladder, because `edit` and
+ * `cover` both need it and two copies drift: the reported failure it exists
+ * for is `ossclip edit <video folder>` when produce wrote into
+ * `<video folder>/.ossclip/<name>/`, and a `cover` that resolved differently
+ * would rebuild a cover for a run the user is not looking at.
+ *
+ * `command` is threaded so the no-TTY candidate list names the command that
+ * was actually run, not always `edit`.
+ *
+ * Every import here is dynamic on purpose: the interactive stack is not
+ * loaded on invocations that never reach a picker, which is what keeps CLI
+ * startup cheap.
+ */
+async function resolveWorkdirArgument(typed: string, command: string): Promise<string> {
+  const { probeWorkdir } = await import("./interactive/workdir-probe");
+  const { resolveWorkdir, candidateListMessage } = await import("./interactive/resolve-workdir");
+  const { isInteractive } = await import("./interactive/tty");
+  const { dir, probe } = await probeWorkdir(typed);
+  const resolution = resolveWorkdir(dir, probe);
+  if (resolution.kind === "none") throw new Error(resolution.message);
+  if (resolution.kind === "choose") {
+    if (!isInteractive()) {
+      throw new Error(candidateListMessage(dir, resolution.candidates, command));
+    }
+    const { pickWorkdir } = await import("./interactive/pick-workdir");
+    return await pickWorkdir(resolution.candidates);
+  }
+  // Say so when the path was not the one typed — a silent redirect leaves the
+  // user with the wrong mental model of where things live.
+  if (resolution.via === "nested") console.log(`▸ resolved ${typed} → ${resolution.workdir}`);
+  return resolution.workdir;
+}
+
 /**
  * Every command this CLI has, built onto a fresh instance.
  *
@@ -298,6 +334,10 @@ export function buildProgram(): Command {
         "if ANTHROPIC_API_KEY is set, else claude-cli",
     )
     .option("--llm-model <id>", "override the provider's default model")
+    .option(
+      "--llm-effort <level>",
+      "reasoning effort for the antigravity provider (low|medium|high)",
+    )
     .option(
       "--llm-fast-model <id>",
       "model for mechanical calls (repair, scene props); 'same' disables tiering",
@@ -432,11 +472,23 @@ export function buildProgram(): Command {
         "any motion crops the head. Per-scene control stays in the editor (autoZoom)",
     )
     .option("--cover <path>", "cover image output path (default: <out>.cover.jpg)")
+    .option(
+      "--cover-text-reset",
+      "use this run's generated cover headline even if `ossclip cover --text` set one — " +
+        "that headline is user-owned and kept by default (deleting cover.json does the same)",
+    )
     .option("--open-editor", "open the editor when the run finishes")
     .option(
       "--no-open-editor",
       "don't open the editor, and don't ask (overrides openEditorAfterProduce)",
     )
+    // Implies --no-render and forces the editor open — resolved by reviewFlag
+    // in the action, where typing --no-render alongside it is agreement and
+    // --no-open-editor is the loud contradiction.
+    .option(
+      "--review",
+      "produce without rendering, then open the editor to review the cut before rendering once",
+    )
     .option("--editor-port <n>", "port for the editor started by --open-editor",
       (v) => Number.parseInt(v, 10), 5174)
     // No default: undefined = "not typed" is what lets the config's
@@ -498,6 +550,13 @@ export function buildProgram(): Command {
       const provider = opts.llm
         ? z.enum(["antigravity", "claude", "claude-cli", "gemini", "mock"]).parse(opts.llm)
         : undefined;
+      // Parsed like --llm above: a typo'd `--llm-effort hgh` must die here
+      // naming the allowed values, not silently run at agy's default — the
+      // knob exists because of a hang (§143), and a user reaching for it is
+      // mid-investigation.
+      const llmEffort = opts.llmEffort
+        ? z.enum(["low", "medium", "high"]).parse(opts.llmEffort)
+        : undefined;
       const forceComponent = opts.forceComponent
         ? SceneComponentIdSchema.parse(opts.forceComponent)
         : undefined;
@@ -528,6 +587,15 @@ export function buildProgram(): Command {
         opts.addJumpCuts,
         command.getOptionValueSource("jumpCuts") === "cli",
       );
+      // --review resolved BEFORE produce runs: it implies --no-render (typed
+      // alongside is agreement) and forces the end-of-run editor open, so the
+      // one render happens from the editor's Render button. reviewFlag throws
+      // on --no-open-editor, the jumpCutsFlag contradiction posture.
+      const { render, openEditor } = reviewFlag(
+        opts.review === true,
+        opts.render,
+        opts.openEditor,
+      );
       // Wall clock around produce() only — the editor offer below can sit at
       // an interactive prompt for as long as the user thinks, and think-time
       // would poison the duration metric (FINDINGS §134).
@@ -537,7 +605,12 @@ export function buildProgram(): Command {
           out: opts.out,
           cleanup,
           transcript: opts.transcript,
-          render: opts.render,
+          // The reviewFlag resolution, not opts.render: --review implies off.
+          render,
+          // Only phrases the no-render exit ("the editor is opening" instead
+          // of the --no-render skip + edit hint) — the render/openEditor
+          // consequences are already resolved above.
+          review: opts.review === true,
           mezzanine: opts.mezzanine,
           workdir: opts.workdir,
           sort,
@@ -549,6 +622,9 @@ export function buildProgram(): Command {
           provider,
           llmModel: opts.llmModel,
           llmFastModel: opts.llmFastModel,
+          // The zod-parsed union above; untyped = undefined lets the config's
+          // `llmEffort` supply it (resolveLlmEffort at the use site).
+          llmEffort,
           speaker: opts.speaker,
           scenes: opts.scenes,
           repair: opts.repair,
@@ -586,6 +662,9 @@ export function buildProgram(): Command {
           jumpCuts,
           cover: opts.cover !== false,
           coverPath: typeof opts.cover === "string" ? opts.cover : undefined,
+          // A separate key from --cover: this one is about the TEXT, and the
+          // cover/coverPath pair already shares one.
+          coverTextReset: opts.coverTextReset === true,
           clip: opts.clip,
           clipWindow: opts.clipWindow,
           // Validated by concurrencyFlag at parse time; undefined = "not
@@ -601,7 +680,10 @@ export function buildProgram(): Command {
           produced: opts.produce === true,
           aspect: opts.aspect === "16:9" ? "16:9" : "9:16",
           clip: opts.clip !== undefined,
-          render: opts.render !== false,
+          // The reviewFlag resolution, spelled `key:` and not shorthand — a
+          // --review run must report render: false, and telemetry.test.ts's
+          // source-drift scan (§136) only sees `key:`-form props.
+          render: render,
           source_duration_bucket: durationBucket(result.sourceDurationSec),
           scenes: result.sceneCount,
           // Per-phase buckets (§140), one `<phase>_bucket` per phase that
@@ -624,7 +706,13 @@ export function buildProgram(): Command {
           }
         }
         const { offerEditor } = await import("./interactive/offer-editor");
-        await offerEditor(result, { flag: opts.openEditor, port: opts.editorPort });
+        // The reviewFlag resolution: --review forces flag=true, and
+        // decideOpenEditor already documents that an explicit flag beats
+        // `rendered` — the editor reads render-props.json, which a no-render
+        // run does write. Reusing this path is what gives --review the edit
+        // command's whole posture (resolveEditorPageDir's loud "run pnpm
+        // build" degrade, startEditServer, openInBrowser) for free.
+        await offerEditor(result, { flag: openEditor, port: opts.editorPort });
         // Deliberately LAST — after the render summary and the editor offer —
         // so the one question ossclip ever asks is the last thing on screen.
         await maybeAskRating(telemetry);
@@ -829,27 +917,8 @@ export function buildProgram(): Command {
       // With no argument the editor opens on its own project picker (R17 §83).
       // With one, resolve what the user MEANT: `ossclip edit <video folder>`
       // was the reported failure, and produce's output lives one level down.
-      let target: string | undefined = workdir;
-      if (workdir !== undefined) {
-        const { probeWorkdir } = await import("./interactive/workdir-probe");
-        const { resolveWorkdir, candidateListMessage } = await import("./interactive/resolve-workdir");
-        const { isInteractive } = await import("./interactive/tty");
-        const { dir, probe } = await probeWorkdir(workdir);
-        const resolution = resolveWorkdir(dir, probe);
-        if (resolution.kind === "none") throw new Error(resolution.message);
-        if (resolution.kind === "choose") {
-          if (!isInteractive()) {
-            throw new Error(candidateListMessage(dir, resolution.candidates));
-          }
-          const { pickWorkdir } = await import("./interactive/pick-workdir");
-          target = await pickWorkdir(resolution.candidates);
-        } else {
-          target = resolution.workdir;
-          // Say so when the path was not the one typed — a silent redirect
-          // leaves the user with the wrong mental model of where things live.
-          if (resolution.via === "nested") console.log(`▸ resolved ${workdir} → ${target}`);
-        }
-      }
+      const target =
+        workdir === undefined ? undefined : await resolveWorkdirArgument(workdir, "edit");
 
       const server = await startEditServer(target, { port: opts.port, pageDir });
       console.log(`▸ editor at ${server.url}`);
@@ -864,6 +933,64 @@ export function buildProgram(): Command {
       void telemetry.flush();
     });
 
+  program
+    .command("cover")
+    .description(
+      "regenerate a produced workdir's cover image — a new headline or a new frame, " +
+        "in seconds, with no video re-render",
+    )
+    // Optional, like `edit`'s: with no argument this resolves the run under
+    // the CURRENT directory, so `cd`-ing to the video's folder is enough.
+    .argument("[workdir]", "a work directory, or the folder you produced in")
+    .option(
+      "--text <headline>",
+      `banner headline. Capped at ${COVER_MAX_WORDS} words like produce's (§35), and the ` +
+        "trimmed result is printed. Omitted keeps the headline this cover already has",
+    )
+    .option(
+      "--at <seconds>",
+      "take the frame from this timestamp. Omitted re-uses the still the last cover was " +
+        "built from — the cheap path, which runs no ffmpeg at all",
+    )
+    .option(
+      "--from <video>",
+      "which video --at reads: `final` (default) is the FINISHED render, so the frame " +
+        "carries the burned-in captions, graphics and watermark; `source` is the original " +
+        "take, framed the way produce framed it",
+      "final",
+    )
+    .option(
+      "--out <path>",
+      "write the JPEG here for THIS run only; a one-off destination that does not change " +
+        "where this project's cover lives (that stays where this workdir's last cover went, " +
+        "else <out>.cover.jpg)",
+    )
+    .action(async (workdir: string | undefined, opts) => {
+      const { parseCoverFlags, regenerateCover } = await import("./cover");
+      // Parsed before anything touches disk: a typo'd `--from finall` must be
+      // an error naming the flag, not a cover quietly rebuilt from the wrong
+      // video (the --source-fit rule above).
+      const flags = parseCoverFlags(opts);
+
+      // The `edit` action's ladder, literally the same one: produce writes
+      // into <video's folder>/.ossclip/<name>/, and `ossclip cover
+      // ~/Downloads/MyClips` has to find that nested run exactly as `edit`
+      // does. With no argument, the current directory is the target.
+      const target = await resolveWorkdirArgument(workdir ?? ".", "cover");
+
+      // A thin shell by design: every decision lives in regenerateCover, so
+      // the editor's /api/cover/regenerate is the same code and not a second
+      // spelling of it.
+      await regenerateCover(target, {
+        text: flags.text,
+        atSec: flags.atSec,
+        from: flags.from,
+        // Raw: `coverDestination` owns the tilde expansion and the cwd
+        // anchor, so there is one site applying `expandHome` to the user half.
+        outPath: flags.outPath,
+      });
+    });
+
   program
     .command("setup")
     .description(

package/src/replay-argv.ts

@@ -54,6 +54,8 @@ export function consumeReplayArgv(): string[] | null {
  */
 export function recordedProduceArgs(pins: {
   llm?: string;
+  /** The RESOLVED §143 effort — flag or valid config, never a raw config string. */
+  llmEffort?: "low" | "medium" | "high";
   clipWindow?: string;
   watermark?: boolean;
   captions?: boolean;
@@ -68,10 +70,29 @@ export function recordedProduceArgs(pins: {
   /** The RESOLVED thumbnail brief — pinned only when non-empty. */
   thumbnailBrief?: string;
 }): string[] {
-  const args = consumeReplayArgv() ?? process.argv.slice(2);
+  // --review and --no-render are stripped at record (cut-review step 1):
+  // command.json exists for exactly one consumer — the editor's Render
+  // button, which replays this argv to produce the video — and a record
+  // carrying --no-render would replay as a run that skips the render again,
+  // while a recorded --review would ALSO spawn a second editor from inside
+  // the replay child. Record the invocation the user wants Render to run.
+  // Both are bare boolean flags, so a value-free filter cannot orphan an
+  // option's argument.
+  const args = (consumeReplayArgv() ?? process.argv.slice(2)).filter(
+    (a) => a !== "--review" && a !== "--no-render",
+  );
   if (pins.llm !== undefined && !args.includes("--llm")) {
     args.push("--llm", pins.llm);
   }
+  // The effort pin (§143), the dictionary's rationale: the resolved level may
+  // have come from ~/.ossclip/config.json's `llmEffort`, and it steers the
+  // editorial call — an unpinned record would replay a DIFFERENT plan the
+  // moment that config is edited. Unset stays unpinned: there is no flag
+  // spelling for "agy's own default", and an argv without the flag replays as
+  // "config decides" — the same accepted cost as the dictionary's empty case.
+  if (pins.llmEffort !== undefined && !args.includes("--llm-effort")) {
+    args.push("--llm-effort", pins.llmEffort);
+  }
   if (pins.clipWindow !== undefined && !args.includes("--clip-window")) {
     args.push("--clip-window", pins.clipWindow);
   }

package/src/setup/download.ts

@@ -12,6 +12,28 @@ import { dirname } from "node:path";
  * before renaming into place — a `.part` never becomes a `dest` unverified.
  */
 
+/**
+ * A pinned asset is gone from the host — distinguished from every other HTTP
+ * failure because it is OURS, not the user's: the manifest names an exact
+ * upstream release, and hosts rotate releases out from under a pin (BtbN
+ * prunes daily autobuilds after ~2 weeks — #6, §145). A stale pin reported as
+ * a bare "download failed: HTTP 404" reads as a broken network and leaves the
+ * user nowhere; the caller catches this type and adds the manual install for
+ * their platform, which turns a dead end into a two-minute detour.
+ *
+ * Deliberately generic: this module downloads models and whisper builds too,
+ * so it names the problem and lets the caller name the remedy.
+ */
+export class PinnedAssetGoneError extends Error {
+  constructor(readonly url: string) {
+    super(
+      `the pinned download is gone upstream (HTTP 404)\n  ${url}\n` +
+        "  This is a stale pin in ossclip's manifest, not a problem on your machine.",
+    );
+    this.name = "PinnedAssetGoneError";
+  }
+}
+
 export interface DownloadOptions {
   /** hex digest; algorithm chosen by which field is set */
   sha256?: string;
@@ -39,6 +61,8 @@ export async function download(url: string, dest: string, opts: DownloadOptions
   const res = await fetchImpl(url, { headers, redirect: "follow" });
   if (res.status === 200) {
     offset = 0; // server ignored the range — start over
+  } else if (res.status === 404) {
+    throw new PinnedAssetGoneError(url);
   } else if (res.status !== 206) {
     throw new Error(`download failed: HTTP ${res.status} for ${url}`);
   }

package/src/setup/manifest.ts

@@ -11,6 +11,10 @@
  * `checksums.sha256` per release; ggml-org assets are hashed by hand), and
  * re-run the setup-e2e workflow. The manifest test asserts every supported
  * platform×arch resolves to either an asset or an explicit manual hint.
+ *
+ * A pinned URL can also rot without anything here changing, so the `manifest
+ * urls` CI job HEADs every one of them on every setup PR and weekly (§145,
+ * §146) — a shape assertion in the unit suite cannot see a 404.
  */
 
 import { basename, isAbsolute, join } from "node:path";
@@ -29,9 +33,23 @@ export interface BinaryAsset {
   version: string;
 }
 
+/**
+ * PIN A MONTH-END TAG ONLY. BtbN's `autobuild-*` releases are not all equal:
+ * the dailies are pruned after roughly two weeks, but the LAST autobuild of
+ * each month is retained indefinitely — verified 2026-08-22 against tags going
+ * back to `autobuild-2024-09-30-15-36`, still serving all 48 assets.
+ *
+ * The previous pin here was a daily (`autobuild-2026-07-29-13-36`) and took
+ * the whole tag with it when it rotated, so `ossclip setup` could not install
+ * ffmpeg on ANY platform it provisions for — every non-darwin branch below
+ * interpolates this one base (#6, §145). Picking the month-end tag costs
+ * nothing and cannot rot the same way; picking `latest` would fix the 404 but
+ * forfeit the checksum guarantee this whole file exists for, since the asset
+ * behind it changes daily.
+ */
 const BTBN =
-  "https://github.com/BtbN/FFmpeg-Builds/releases/download/autobuild-2026-07-29-13-36";
-const FFMPEG_VER = "n8.1.2-31-g8c9502e9b0";
+  "https://github.com/BtbN/FFmpeg-Builds/releases/download/autobuild-2026-07-31-14-10";
+const FFMPEG_VER = "n8.1.2-34-g9b6c8969e0";
 
 const WHISPER =
   "https://github.com/ggml-org/whisper.cpp/releases/download/v1.9.1";
@@ -50,7 +68,7 @@ export function ffmpegAsset(platform: NodeJS.Platform, arch: string): BinaryAsse
     return {
       ...common,
       url: `${BTBN}/ffmpeg-${FFMPEG_VER}-win64-gpl-8.1.zip`,
-      sha256: "106d3f8e72b70e29f83983dbaa65efdfc5355716a5df675dc846e441929f7890",
+      sha256: "cc4156d51387566ea8ba653fc3a04897bdf812fddf652428d9030bbf7ae24835",
       archive: "zip",
       sizeMB: 160,
     };
@@ -59,7 +77,7 @@ export function ffmpegAsset(platform: NodeJS.Platform, arch: string): BinaryAsse
     return {
       ...common,
       url: `${BTBN}/ffmpeg-${FFMPEG_VER}-winarm64-gpl-8.1.zip`,
-      sha256: "ac46bdb0c9c619b107c7281a0cc6932a9419c4d6c3c8c36a259550f7fcee1a1a",
+      sha256: "abf3b41c200ce5346b9bb5be6fe634c4720d891778d8921f7b36b76d002b3c96",
       archive: "zip",
       sizeMB: 107,
     };
@@ -68,16 +86,16 @@ export function ffmpegAsset(platform: NodeJS.Platform, arch: string): BinaryAsse
     return {
       ...common,
       url: `${BTBN}/ffmpeg-${FFMPEG_VER}-linux64-gpl-8.1.tar.xz`,
-      sha256: "9fb60ff01e6574258dc76efdf94f901a651582da67b8edcfd10e8860233b7ef4",
+      sha256: "09fc77be269c7053e438b7e96548e4af97604faf96a42c4a3c56a1ad74c22c0a",
       archive: "tar.xz",
-      sizeMB: 120,
+      sizeMB: 119,
     };
   }
   if (platform === "linux" && arch === "arm64") {
     return {
       ...common,
       url: `${BTBN}/ffmpeg-${FFMPEG_VER}-linuxarm64-gpl-8.1.tar.xz`,
-      sha256: "d8f9598a885db3deabd06af7f0f70c8565af27d29fadbcf746598c9306a0c3fa",
+      sha256: "177e40c91564dec3840096f3bf1ffe696b94330585972462cfc739fa29fe0e1a",
       archive: "tar.xz",
       sizeMB: 102,
     };
@@ -163,13 +181,13 @@ export const MODELS: Record<string, ModelInfo> = {
   "base.en": { sizeMB: 142, sha1: "137c40403d78fd54d454da0f9bd998f78703390c" },
   "small.en": { sizeMB: 466, sha1: "db8a495a91d927739e50b3fc1cc4c6b8f6c2d022" },
   "medium.en": { sizeMB: 1536, sha1: "8c30f0e44ce9560643ebd10bbe50cd20eafd3723" },
-  // URL pending the author's upload (2026-08-17) — sha1 added when the file
-  // is published; setup already warns-and-continues without a checksum.
   "medium-urdu": {
     sizeMB: 1463,
-    // sha1 computed 2026-08-17 from the author's converted file BEFORE the HF
-    // upload — same bytes, so the pin is valid the moment the file publishes,
-    // and a corrupted/tampered mirror download fails the checksum loudly.
+    // sha1 was computed 2026-08-17 from the author's converted file before the
+    // HF upload, then the published file was checked byte-identical to it
+    // (exact size + head/mid/tail ranges) rather than trusted — so a corrupted
+    // or tampered mirror download fails the checksum loudly. Live since that
+    // date; `pnpm check:urls` re-probes this URL with the rest of the table.
     sha1: "59769d590f62eeeb3bc3f5b82ce8c03b6e96831e",
     language: "ur",
     note: "community Urdu fine-tune (Abdul145/whisper-medium-urdu-custom, Apache-2.0), converted to GGML",

package/src/setup/setup.ts

@@ -11,8 +11,15 @@ import {
   whisperModelPath,
   type BinaryAsset,
 } from "./manifest";
-import { formatPlan, managedBinDir, planSetup, type SetupProbes, type SetupStep } from "./plan";
-import { download, progressLine } from "./download";
+import {
+  formatPlan,
+  managedBinDir,
+  planSetup,
+  type SetupProbes,
+  type SetupStep,
+  type StepKind,
+} from "./plan";
+import { PinnedAssetGoneError, download, progressLine } from "./download";
 import { extractArchive, findFile, markExecutable } from "./extract";
 import { promptForProvider } from "./provider";
 
@@ -37,6 +44,35 @@ export interface SetupCliOptions {
   yes: boolean;
 }
 
+/**
+ * The hand-install to fall back to when setup's own pinned download is gone
+ * (§145). Pure, and exported so the platform matrix is assertable — the whole
+ * point is that a Windows or Linux user is never the one who finds out the
+ * command was wrong (§136).
+ *
+ * Deliberately NOT doctor's `installHint`: doctor imports from this directory,
+ * and pointing setup back at doctor would invert that. These are the same
+ * commands doctor prints, and doctor.test.ts pins those independently.
+ */
+export function manualInstall(kind: StepKind, platform: NodeJS.Platform): string {
+  if (kind === "model") return "download it by hand — `ossclip doctor` prints the exact curl";
+  if (kind === "provider") return "set an API key, or install the agy or claude CLI";
+  const pkg = kind === "ffmpeg" ? "ffmpeg" : "whisper-cpp";
+  if (platform === "darwin") return `brew install ${pkg}`;
+  if (platform === "linux") {
+    // apt has no whisper.cpp package; building it is the documented path.
+    return kind === "ffmpeg" ? "sudo apt install ffmpeg" : WHISPER_BUILD_HINT;
+  }
+  if (platform === "win32") {
+    return kind === "ffmpeg"
+      ? "winget install ffmpeg — then point OSSCLIP_FFMPEG/OSSCLIP_FFPROBE (or config.json) at the binaries"
+      : WHISPER_BUILD_HINT;
+  }
+  return kind === "ffmpeg"
+    ? "install ffmpeg from https://ffmpeg.org and set OSSCLIP_FFMPEG"
+    : WHISPER_BUILD_HINT;
+}
+
 const probeBin = (bin: string, arg: string): Promise<boolean> =>
   new Promise((resolve) => {
     // Existence is the question, not exit code (same contract as doctor).
@@ -92,8 +128,15 @@ export async function setup(
         await runStep(step);
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        failures.push(`${step.kind}: ${msg}`);
-        console.error(`✗ ${step.kind} failed: ${msg}`);
+        // A rotated-away pin is ossclip's bug, and the user still needs a
+        // working toolchain today — so name the hand-install for their
+        // platform instead of leaving them on a bare 404 (#6, §145).
+        const detour =
+          err instanceof PinnedAssetGoneError
+            ? `\n  Until it is re-pinned, install it yourself: ${manualInstall(step.kind, probes.platform)}`
+            : "";
+        failures.push(`${step.kind}: ${msg}${detour}`);
+        console.error(`✗ ${step.kind} failed: ${msg}${detour}`);
       }
     }