dsh-hyperframes 0.10.1 → 0.11.0

package/skills/media-use/scripts/lib/media-fetch.test.mjs

@@ -0,0 +1,197 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { fetchMedia, isPublicMediaUrl, readCappedBody } from "./media-fetch.mjs";
+import { freezeUrl } from "./freeze.mjs";
+import { downloadTo } from "../../audio/scripts/lib/heygen.mjs";
+import { synthesizeHeygen } from "../../audio/scripts/lib/tts.mjs";
+import { faviconSearch } from "./logo-provider.mjs";
+
+test("blocks private, reserved, alternate-encoded and mapped hosts", () => {
+  for (const host of [
+    "localhost",
+    "localhost.",
+    "a.localhost",
+    "svc.internal",
+    "svc.local",
+    "127.1",
+    "2130706433",
+    "0x7f000001",
+    "10.0.0.1",
+    "169.254.169.254",
+    "100.100.100.200",
+    "192.168.1.1",
+    "172.31.0.1",
+    "224.0.0.1",
+    "[::]",
+    "[::1]",
+    "[::ffff:127.0.0.1]",
+    "[::ffff:a00:1]",
+    "[fe80::1]",
+    "[fd00::1]",
+    "[ff02::1]",
+  ]) {
+    assert.equal(isPublicMediaUrl(`https://${host}/asset`), false, host);
+  }
+  for (const url of [
+    "https://cdn.example/asset.cube",
+    "http://example.com/clip.mp4",
+    "https://8.8.8.8/a",
+    "https://[::ffff:8.8.8.8]/a",
+  ])
+    assert.equal(isPublicMediaUrl(url), true, url);
+  assert.equal(isPublicMediaUrl("file:///tmp/a.mp4"), false);
+});
+
+test("follows public relative redirects manually and forwards cancellation", async () => {
+  const calls = [];
+  const signal = new AbortController().signal;
+  const response = await fetchMedia("https://cdn.example/a", {
+    method: "HEAD",
+    signal,
+    fetchImpl: async (url, options) => {
+      calls.push(url);
+      assert.equal(options.redirect, "manual");
+      assert.equal(options.signal, signal);
+      assert.equal(options.method, "HEAD");
+      return calls.length === 1
+        ? new Response(null, { status: 302, headers: { location: "/b" } })
+        : new Response("media");
+    },
+  });
+  assert.deepEqual(calls, ["https://cdn.example/a", "https://cdn.example/b"]);
+  assert.equal(await response.text(), "media");
+});
+
+test("rejects private redirect targets before requesting them and cancels redirect bodies", async () => {
+  let calls = 0;
+  let cancelled = false;
+  await assert.rejects(
+    fetchMedia("https://cdn.example/a", {
+      fetchImpl: async () => {
+        calls++;
+        return new Response(
+          new ReadableStream({
+            cancel() {
+              cancelled = true;
+            },
+          }),
+          {
+            status: 302,
+            headers: { location: "http://169.254.169.254/latest/meta-data" },
+          },
+        );
+      },
+    }),
+    /blocked/,
+  );
+  assert.equal(calls, 1);
+  assert.equal(cancelled, true);
+});
+
+test("bounds redirect loops", async () => {
+  let calls = 0;
+  await assert.rejects(
+    fetchMedia("https://cdn.example/a", {
+      fetchImpl: async () => {
+        calls++;
+        return new Response(null, { status: 302, headers: { location: "/a" } });
+      },
+    }),
+    /redirect limit/,
+  );
+  assert.equal(calls, 6);
+});
+
+test("freeze refuses a public-to-private redirect without writing response bytes", async (t) => {
+  const dir = mkdtempSync(join(tmpdir(), "hf-freeze-redirect-"));
+  t.mock.method(globalThis, "fetch", async (_url, options) =>
+    options?.redirect === "manual"
+      ? new Response(null, { status: 302, headers: { location: "http://127.0.0.1/private.mp4" } })
+      : new Response("private response"),
+  );
+  try {
+    await assert.rejects(freezeUrl("https://cdn.example/a.mp4", join(dir, "out.mp4")), /blocked/);
+    assert.deepEqual(readdirSync(dir), []);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+for (const entry of ["heygen audio", "tts mp3", "tts wav", "favicon"]) {
+  test(`${entry} blocks private redirects before saving or transcoding`, async (t) => {
+    const dir = mkdtempSync(join(tmpdir(), "hf-provider-redirect-"));
+    const requests = [];
+    const fetchImpl = t.mock.method(globalThis, "fetch", async (url, options) => {
+      requests.push(url);
+      return options?.redirect === "manual"
+        ? new Response(null, {
+            status: 302,
+            headers: { location: "http://169.254.169.254/private" },
+          })
+        : new Response(new Uint8Array(600));
+    });
+    try {
+      if (entry === "heygen audio") {
+        await assert.rejects(
+          downloadTo("https://cdn.example/audio", join(dir, "audio.mp3")),
+          /blocked/,
+        );
+      } else if (entry === "favicon") {
+        assert.equal(await faviconSearch("GitHub logo"), null);
+      } else {
+        const result = await synthesizeHeygen(
+          {
+            text: "hi",
+            voiceId: "v1",
+            lang: "en",
+            speed: 1,
+            wavAbs: join(dir, entry === "tts wav" ? "audio.wav" : "audio.mp3"),
+          },
+          {
+            heygenAuthHeaders: () => ({}),
+            heygenJSON: async () => ({ data: { audio_url: "https://cdn.example/audio" } }),
+            fetch: fetchImpl,
+            transcodeToWav: () => assert.fail("private bytes must not reach ffmpeg"),
+          },
+        );
+        assert.equal(result.ok, false);
+        assert.match(result.error, /blocked/);
+      }
+      assert.equal(requests.length, 1);
+      assert.deepEqual(readdirSync(dir), []);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+}
+
+function streamed(sizes, contentLength = null) {
+  let pulled = 0;
+  const body = (async function* () {
+    for (const n of sizes) {
+      pulled++;
+      yield new Uint8Array(n);
+    }
+  })();
+  return { res: { headers: { get: () => contentLength }, body }, pulled: () => pulled };
+}
+
+test("readCappedBody refuses a declared oversize body before reading a byte", async () => {
+  const { res, pulled } = streamed([10], "101");
+  await assert.rejects(readCappedBody(res, 100, "t"), /t: 101 bytes exceeds 100 cap/);
+  assert.equal(pulled(), 0);
+});
+
+test("readCappedBody aborts a chunked body the moment it crosses the cap", async () => {
+  const { res, pulled } = streamed([60, 60, 60]);
+  await assert.rejects(readCappedBody(res, 100, "t"), /t: stream exceeds 100 cap/);
+  assert.equal(pulled(), 2);
+});
+
+test("readCappedBody returns every byte of a body at the cap", async () => {
+  const { res } = streamed([60, 40]);
+  assert.equal((await readCappedBody(res, 100, "t")).byteLength, 100);
+});

package/skills/media-use/scripts/lib/media-home.test.mjs

@@ -0,0 +1,61 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+
+import { cachePut } from "./cache.mjs";
+import { globalMediaDir } from "./media-home.mjs";
+
+const HOME = mkdtempSync(join(tmpdir(), "media-home-"));
+process.env.HYPERFRAMES_MEDIA_HOME = HOME;
+
+test("the global cache writes into the media home a test points it at", () => {
+  const work = mkdtempSync(join(tmpdir(), "media-home-src-"));
+  const file = join(work, "clip.wav");
+  writeFileSync(file, "media-home regression bytes");
+  cachePut(file, { id: "bgm_001", type: "bgm", provenance: { prompt: "media home probe" } });
+  const manifest = join(HOME, ".media", "manifest.jsonl");
+  assert.ok(existsSync(manifest), "the temp media home holds the global manifest");
+  assert.match(readFileSync(manifest, "utf8"), /media home probe/);
+  assert.equal(globalMediaDir(), join(HOME, ".media"));
+});
+
+// A child process that resolves the media dir, with only the given media-home variables set.
+function runProbe(env) {
+  const lib = new URL("./media-home.mjs", import.meta.url).href;
+  const childEnv = { ...process.env };
+  delete childEnv.HYPERFRAMES_MEDIA_HOME;
+  delete childEnv.HYPERFRAMES_MEDIA_HOME_REQUIRED;
+  delete childEnv.NODE_TEST_CONTEXT;
+  const run = spawnSync(
+    process.execPath,
+    [
+      "--input-type=module",
+      "-e",
+      `const m = await import(${JSON.stringify(lib)}); console.log("dir=" + m.globalMediaDir());`,
+    ],
+    { encoding: "utf8", env: { ...childEnv, ...env } },
+  );
+  return { status: run.status, output: `${run.stdout}${run.stderr}` };
+}
+
+test("a repo test run that never points the media home anywhere fails instead of writing", () => {
+  const { status, output } = runProbe({ HYPERFRAMES_MEDIA_HOME_REQUIRED: "1" });
+  assert.notEqual(status, 0, output);
+  assert.match(output, /set HYPERFRAMES_MEDIA_HOME to a temp dir/);
+});
+
+// Node sets NODE_TEST_CONTEXT for every project's test runs, so another project whose own tests
+// spawn this CLI must get the person's real library, not the guard.
+test("another project's node --test run still resolves the real media home", () => {
+  const home = mkdtempSync(join(tmpdir(), "media-home-user-"));
+  const { status, output } = runProbe({
+    HOME: home,
+    USERPROFILE: home,
+    NODE_TEST_CONTEXT: "child-v8",
+  });
+  assert.equal(status, 0, output);
+  assert.ok(output.includes(`dir=${join(home, ".media")}`), output);
+});

package/skills/media-use/scripts/lib/media-search.d.mts

@@ -0,0 +1,9 @@
+export function rankMediaRows<
+  T extends {
+    id: string;
+    kind: string;
+    title: string;
+    description: string;
+    tags: string[];
+  },
+>(query: string, rows: T[]): T[];

package/skills/media-use/scripts/lib/media-search.mjs

@@ -0,0 +1,107 @@
+const STOP = new Set(
+  (
+    "the a an and or of to in on at is are be it its for with that this as by from into " +
+    "one two must not no all over under across while when where which who whom whose they " +
+    "them their we our you your he she his her but if then than so such can may might will " +
+    "would should each other another same both few more most some any every"
+  ).split(" "),
+);
+
+const PLURAL_RULES = [
+  [/([^aeiou])ies$/, "$1y"],
+  [/(ch|sh|ss|x)es$/, "$1"],
+  [/(ss|us|is)$/, "$&"],
+  [/s$/, ""],
+];
+const STRONG_FIELD_WEIGHT = 3;
+const INFERRED_TOKEN_WEIGHT = 0.35;
+
+function singularize(word) {
+  if (word.length <= 3) return word;
+  for (const [pattern, replacement] of PLURAL_RULES) {
+    if (pattern.test(word)) return word.replace(pattern, replacement);
+  }
+  return word;
+}
+
+function tokenize(text) {
+  const words =
+    String(text)
+      .toLowerCase()
+      .match(/[a-z]+/g) || [];
+  return words.filter((word) => word.length > 2 && !STOP.has(word)).map(singularize);
+}
+
+export function rankMediaRows(query, rows) {
+  const asked = tokenize(query);
+  const normalizedLiteralQuery = String(query).trim().toLowerCase();
+  const normalizedQuery = asked.join(" ");
+  const want = new Map(asked.map((token) => [token, 1]));
+  if (want.size === 0) return [];
+
+  const parsed = rows.map((row) => {
+    const strongTokens = new Set(tokenize(`${row.id} ${row.title}`));
+    const allTokens = new Set([
+      ...strongTokens,
+      ...tokenize(`${row.description} ${row.tags.join(" ")} ${row.kind}`),
+    ]);
+    return {
+      row,
+      strongTokens,
+      allTokens,
+      literalId: row.id.trim().toLowerCase() === normalizedLiteralQuery,
+      stemmedId: tokenize(row.id).join(" ") === normalizedQuery,
+    };
+  });
+  const vocabulary = new Set(parsed.flatMap(({ allTokens }) => [...allTokens]));
+  for (const token of asked) {
+    if (token.length < 6) continue;
+    for (let cut = 3; cut <= token.length - 3; cut++) {
+      const head = token.slice(0, cut);
+      const tail = token.slice(cut);
+      if (vocabulary.has(head) && vocabulary.has(tail)) {
+        want.set(head, INFERRED_TOKEN_WEIGHT);
+        want.set(tail, INFERRED_TOKEN_WEIGHT);
+        break;
+      }
+    }
+  }
+  for (let index = 0; index < asked.length - 1; index++) {
+    const joined = `${asked[index]}${asked[index + 1]}`;
+    if (vocabulary.has(joined)) want.set(joined, INFERRED_TOKEN_WEIGHT);
+  }
+
+  const idf = new Map();
+  for (const token of want.keys()) {
+    const documentFrequency = parsed.filter(({ allTokens }) => allTokens.has(token)).length;
+    idf.set(token, Math.log((parsed.length + 1) / (documentFrequency + 1)) + 1);
+  }
+  return parsed
+    .map(({ row, strongTokens, allTokens, literalId, stemmedId }) => {
+      let score = 0;
+      for (const [token, asking] of want) {
+        const weight = (idf.get(token) || 1) * asking;
+        if (strongTokens.has(token)) score += STRONG_FIELD_WEIGHT * weight;
+        else if (allTokens.has(token)) score += weight;
+      }
+      return { row, score, literalId, stemmedId };
+    })
+    .filter(({ score }) => score > 0)
+    .sort(
+      (a, b) =>
+        Number(b.literalId) - Number(a.literalId) ||
+        Number(b.stemmedId) - Number(a.stemmedId) ||
+        b.score - a.score,
+    )
+    .map(({ row }) => row);
+}
+
+export async function rankMediaRowsWithVectors(query, rows, semanticRanking) {
+  const words = rankMediaRows(query, rows);
+  if (words.length > 0) return { rows: words, tier: "words" };
+  if (!semanticRanking) return { rows: [], tier: "words" };
+  const semantic = await semanticRanking(query, rows);
+  return semantic
+    ? { rows: semantic.map(({ row }) => row), tier: "on-device" }
+    : { rows: [], tier: "words" };
+}

package/skills/media-use/scripts/lib/mflux-provider.mjs

@@ -0,0 +1,128 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, unlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describeDownload, probeSpecs } from "./specs.mjs";
+import { buildArgv, selectModelLadder } from "./local-models.mjs";
+
+// Local image generation via mflux (FLUX-on-MLX), the Mac-native runner.
+// Spec-gated: selectModelLadder("imagegen", specs) returns every FLUX-class
+// model the machine's AVAILABLE RAM can actually run (medium FLUX-schnell
+// --low-ram on ~24GB, up to Qwen-Image on 64GB+), best first. When nothing
+// local fits, or no fitting tier can actually run here, this returns null so
+// the registry falls through to the codex image upsell.
+//
+// The official FLUX repos are HF-gated, so the model entries point --path at
+// non-gated community 4-bit re-uploads; the repo is resolved to a local snapshot
+// (hf download, idempotent) because a bare repo id breaks mlx unflatten.
+
+// Resolve an HF repo to its local snapshot dir. `hf download` is idempotent and
+// prints the snapshot path as its last line.
+function resolveSnapshot(repo, execFn, pathExists) {
+  const out = execFn("hf", ["download", repo], {
+    encoding: "utf8",
+    timeout: 1_800_000,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  const path = out?.trim().split(/\r?\n/).pop()?.trim();
+  return path && pathExists(path) ? path : null;
+}
+
+export async function mfluxImageGenerate(
+  intent,
+  ctx,
+  execFn = execFileSync,
+  pathExists = existsSync,
+  unlinkFn = unlinkSync,
+) {
+  const specs = ctx?.specs || probeSpecs();
+  const ladder = selectModelLadder("imagegen", specs, { preferTier: ctx?.preferTier });
+  if (!ladder.length) return null; // no local model fits -> codex upsell/fallback
+
+  // Each attempt mints its own timestamped output path, so a partial artifact
+  // from a failed tier is orphaned rather than overwritten - and a lower tier
+  // then succeeding hides it. Discard it before demoting. Best-effort: a
+  // partial we cannot remove must never mask the real failure.
+  const discardPartial = (path) => {
+    try {
+      if (pathExists(path)) unlinkFn(path);
+    } catch {
+      // nothing actionable: the generate failure below is the real story
+    }
+  };
+
+  // Best tier first, demoting past any tier that cannot run here (runner off
+  // PATH, a snapshot that won't download, an OOM) rather than failing local
+  // image gen outright. Every demotion is reported, so a quietly smaller model
+  // is never mistaken for the tier the machine nominally qualified for.
+  for (const model of ladder) {
+    const bin = model.invoke.trim().split(/\s+/)[0];
+    // Not installed? Surface the exact enable-command (before the model
+    // download) so the agent learns the free local path is available instead of
+    // silently taking the codex upsell.
+    try {
+      execFn("which", [bin], { stdio: ["ignore", "ignore", "ignore"] });
+    } catch {
+      console.error(
+        `media-use: local image gen not enabled (\`${bin}\` not on PATH). Install for free on-device FLUX: ${model.install}. Heads up: ${model.id} ${describeDownload(model.sizeMB)}.`,
+      );
+      continue;
+    }
+
+    const outPath = join(tmpdir(), `media-use-mflux-${process.pid}-${Date.now()}.png`);
+    const vars = {
+      prompt: intent,
+      w: ctx?.width || 512,
+      h: ctx?.height || 512,
+      seed: ctx?.seed ?? 42,
+      out: outPath,
+    };
+    if (model.repo && model.invoke.includes("{model_path}")) {
+      let snap = null;
+      let why = `could not resolve a local snapshot of ${model.repo}`;
+      try {
+        snap = resolveSnapshot(model.repo, execFn, pathExists);
+      } catch (err) {
+        why = `hf download failed: ${err.stderr?.toString().trim().slice(-200) || err.message}`;
+      }
+      if (!snap) {
+        console.error(`media-use: local image gen (${model.id}): ${why}`);
+        continue;
+      }
+      vars.model_path = snap;
+    }
+
+    const argv = buildArgv(model.invoke, vars);
+    argv.shift(); // drop the bin (already validated)
+    try {
+      execFn(bin, argv, {
+        encoding: "utf8",
+        timeout: 1_800_000,
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+    } catch (err) {
+      discardPartial(outPath);
+      console.error(
+        `media-use: local image gen (${model.id}) failed: ${err.stderr?.toString().trim().slice(-200) || err.message}`,
+      );
+      continue;
+    }
+    if (!pathExists(outPath)) {
+      console.error(
+        `media-use: local image gen (${model.id}) exited cleanly but wrote no output file`,
+      );
+      continue;
+    }
+    return {
+      localPath: outPath,
+      ext: ".png",
+      source: "generated",
+      metadata: {
+        description: intent,
+        provider: `mflux.${model.id}`,
+        provenance: { model: model.id, tier: model.tier, prompt: intent },
+      },
+    };
+  }
+  return null;
+}

package/skills/media-use/scripts/lib/mflux-provider.test.mjs

@@ -0,0 +1,174 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mfluxImageGenerate } from "./mflux-provider.mjs";
+
+// 40GB clears the 32GB klein tier and the 8GB schnell tier below it; the 64GB
+// qwen tier stays out of reach. Two rungs is what makes demotion observable.
+const bothTiersSpecs = { availableRamMB: 40000, gpu: { present: true } };
+const SNAPSHOT = "/tmp/hf-snapshot";
+
+// exec stub covering all three shells-out mflux does: the PATH probe, the
+// idempotent `hf download`, and the generate itself.
+function stubExec({ failGenerateFor = [], failWhichFor = [] } = {}) {
+  const calls = [];
+  const exec = (...call) => {
+    calls.push(call);
+    const [bin, argv] = call;
+    if (bin === "which") {
+      if (failWhichFor.includes(argv[0])) throw new Error("not found");
+      return "";
+    }
+    if (bin === "hf") return `Fetching 6 files...\n${SNAPSHOT}\n`;
+    if (failGenerateFor.some((id) => argv.join(" ").includes(id))) {
+      const err = new Error("exit 1");
+      err.stderr = "mlx.core.metal: out of memory";
+      throw err;
+    }
+    return "";
+  };
+  return { calls, exec };
+}
+
+const generateCalls = (calls) =>
+  calls.filter(([bin]) => bin !== "which" && bin !== "hf").map(([, argv]) => argv.join(" "));
+
+test("no local model fits: falls through to the upsell without shelling out", async () => {
+  const { calls, exec } = stubExec();
+
+  const result = await mfluxImageGenerate(
+    "a red bicycle",
+    { specs: { availableRamMB: 100, gpu: { present: true } } },
+    exec,
+    () => true,
+  );
+
+  assert.equal(result, null);
+  assert.deepEqual(calls, []);
+});
+
+test("a top tier that cannot run demotes to the next fitting tier", async (t) => {
+  const errors = [];
+  t.mock.method(console, "error", (message) => errors.push(message));
+  const { calls, exec } = stubExec({ failGenerateFor: ["flux2-klein-4b"] });
+
+  const result = await mfluxImageGenerate(
+    "a red bicycle",
+    { specs: bothTiersSpecs },
+    exec,
+    () => true,
+  );
+
+  assert.ok(result, "the schnell tier still produced an image");
+  assert.equal(result.metadata.provider, "mflux.flux-schnell-mflux-q4");
+  const generated = generateCalls(calls);
+  assert.equal(generated.length, 2, "klein attempted first, then schnell");
+  assert.match(generated[0], /flux2-klein-4b/);
+  assert.match(generated[1], /--model schnell/);
+  assert.equal(errors.length, 1, "the demotion is reported, not silent");
+  assert.match(errors[0], /flux2-klein-mflux-q4\) failed/);
+});
+
+test("a snapshot that will not resolve demotes rather than failing outright", async (t) => {
+  const errors = [];
+  t.mock.method(console, "error", (message) => errors.push(message));
+  const calls = [];
+  const exec = (...call) => {
+    calls.push(call);
+    const [bin, argv] = call;
+    if (bin === "which") return "";
+    // klein's weights won't download; schnell's do
+    if (bin === "hf") {
+      if (argv[1].includes("FLUX.2-klein")) throw new Error("403 Forbidden");
+      return `${SNAPSHOT}\n`;
+    }
+    return "";
+  };
+
+  const result = await mfluxImageGenerate(
+    "a red bicycle",
+    { specs: bothTiersSpecs },
+    exec,
+    () => true,
+  );
+
+  assert.ok(result, "demoted past the ungettable weights");
+  assert.equal(result.metadata.provider, "mflux.flux-schnell-mflux-q4");
+  assert.equal(errors.length, 1);
+  assert.match(errors[0], /hf download failed/);
+});
+
+test("runner missing from PATH reports the install hint per tier and returns null", async (t) => {
+  const errors = [];
+  t.mock.method(console, "error", (message) => errors.push(message));
+  const { exec } = stubExec({ failWhichFor: ["mflux-generate"] });
+
+  const result = await mfluxImageGenerate(
+    "a red bicycle",
+    { specs: bothTiersSpecs },
+    exec,
+    () => true,
+  );
+
+  assert.equal(result, null);
+  assert.equal(errors.length, 2, "both fitting tiers reported");
+  assert.match(errors[0], /uv pip install mflux/);
+  // each hint states that tier's download cost before the user commits
+  assert.match(errors[0], /GB of weights to/);
+  assert.match(errors[1], /GB of weights to/);
+});
+
+// Same per-attempt temp path, same orphaning risk as the LTX provider: a
+// partial png from a failed tier must not survive a lower tier succeeding.
+const outputOf = (argv) => argv[argv.indexOf("--output") + 1];
+const attemptedOutputs = (calls) =>
+  calls.filter(([bin]) => bin !== "which" && bin !== "hf").map(([, argv]) => outputOf(argv));
+
+test("a failed attempt's partial output is discarded before demoting", async (t) => {
+  t.mock.method(console, "error", () => {});
+  const unlinked = [];
+  const { calls, exec } = stubExec({ failGenerateFor: ["flux2-klein-4b"] });
+
+  const result = await mfluxImageGenerate(
+    "a red bicycle",
+    { specs: bothTiersSpecs },
+    exec,
+    () => true,
+    (path) => unlinked.push(path),
+  );
+
+  assert.ok(result, "the schnell tier still produced an image");
+  assert.deepEqual(unlinked, [attemptedOutputs(calls)[0]], "the failed klein partial is removed");
+});
+
+test("every tier failing discards every partial, one per attempt", async (t) => {
+  t.mock.method(console, "error", () => {});
+  const unlinked = [];
+  const { calls, exec } = stubExec({ failGenerateFor: ["flux2-klein-4b", "schnell"] });
+
+  const result = await mfluxImageGenerate(
+    "a red bicycle",
+    { specs: bothTiersSpecs },
+    exec,
+    () => true,
+    (path) => unlinked.push(path),
+  );
+
+  assert.equal(result, null);
+  assert.deepEqual(unlinked, attemptedOutputs(calls), "nothing is left behind");
+});
+
+test("a successful generation is never discarded", async () => {
+  const unlinked = [];
+  const { exec } = stubExec();
+
+  const result = await mfluxImageGenerate(
+    "a red bicycle",
+    { specs: bothTiersSpecs },
+    exec,
+    () => true,
+    (path) => unlinked.push(path),
+  );
+
+  assert.ok(result);
+  assert.deepEqual(unlinked, [], "the returned artifact must survive");
+});