hyperframes 0.8.57 → 0.8.59

package/dist/skills/media-use/scripts/lib/bundled-sfx-provider.mjs

@@ -0,0 +1,119 @@
+import { existsSync, readFileSync } from "node:fs";
+import { extname, join } from "node:path";
+import { rankMediaRows } from "./media-search.mjs";
+
+const LIB_DIR =
+  process.env.HYPERFRAMES_MEDIA_USE_SFX_DIR ||
+  [
+    join(import.meta.dirname, "..", "..", "audio", "assets", "sfx"),
+    join(
+      import.meta.dirname,
+      "..",
+      "..",
+      "..",
+      "..",
+      "..",
+      "skills",
+      "media-use",
+      "audio",
+      "assets",
+      "sfx",
+    ),
+  ].find((candidate) => existsSync(candidate)) ||
+  join(import.meta.dirname, "..", "..", "audio", "assets", "sfx");
+
+export const BUNDLED_SFX_RECOVERY_COMMAND = "npx hyperframes skills update media-use";
+
+export class BundledSfxAssetsError extends Error {
+  constructor(health) {
+    super(
+      `bundled SFX assets are missing or incomplete (${health.detail}). Repair the installed media-use skill: ${health.fix}`,
+    );
+    this.name = "BundledSfxAssetsError";
+    this.code = health.code;
+    this.fix = health.fix;
+  }
+}
+
+function unhealthy(detail) {
+  return {
+    ok: false,
+    code: "bundled_sfx_assets_missing",
+    detail,
+    fix: BUNDLED_SFX_RECOVERY_COMMAND,
+  };
+}
+
+export function inspectBundledSfxAssets(libraryDir = LIB_DIR) {
+  const manifestPath = join(libraryDir, "manifest.json");
+  if (!existsSync(manifestPath)) return unhealthy(`manifest not found: ${manifestPath}`);
+
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  } catch {
+    return unhealthy(`manifest is not valid JSON: ${manifestPath}`);
+  }
+  if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) {
+    return unhealthy(`manifest must contain an object: ${manifestPath}`);
+  }
+
+  const entries = Object.entries(manifest);
+  if (entries.length === 0) return unhealthy(`manifest contains no SFX entries: ${manifestPath}`);
+  for (const [key, entry] of entries) {
+    if (!entry?.file || typeof entry.file !== "string") {
+      return unhealthy(`manifest entry "${key}" has no file`);
+    }
+    const assetPath = join(libraryDir, entry.file);
+    if (!existsSync(assetPath)) return unhealthy(`asset not found: ${assetPath}`);
+  }
+
+  return {
+    ok: true,
+    count: entries.length,
+    detail: `${entries.length} bundled SFX asset${entries.length === 1 ? "" : "s"} available`,
+    fix: "",
+  };
+}
+
+export function extensionForBundledSfxFile(filename) {
+  return extname(filename) || ".mp3";
+}
+
+export const bundledSfxProvider = {
+  async search(intent, ctx = {}) {
+    const libraryDir = ctx.libraryDir || LIB_DIR;
+    const health = inspectBundledSfxAssets(libraryDir);
+    if (!health.ok) throw new BundledSfxAssetsError(health);
+    const manifest = JSON.parse(readFileSync(join(libraryDir, "manifest.json"), "utf8"));
+
+    const rows = Object.entries(manifest).map(([key, entry]) => ({
+      id: key,
+      kind: "sfx",
+      title: key,
+      description: entry?.description || key,
+      tags: ["sfx"],
+      file: entry?.file || "",
+      duration: entry?.duration,
+    }));
+    const bestRow = rankMediaRows(intent, rows)[0];
+    const best =
+      bestRow && manifest[bestRow.id]?.file
+        ? { key: bestRow.id, entry: manifest[bestRow.id] }
+        : null;
+    if (!best) return null;
+
+    const localPath = join(libraryDir, best.entry.file);
+    return {
+      localPath,
+      ext: extensionForBundledSfxFile(best.entry.file),
+      source: "bundled",
+      metadata: {
+        description: best.entry.description || best.key,
+        duration: best.entry.duration ?? null,
+        provider: "bundled.sfx",
+        provenance: { library_key: best.key },
+      },
+    };
+  },
+};

package/dist/skills/media-use/scripts/lib/bundled-sfx-provider.test.mjs

@@ -0,0 +1,139 @@
+import { strict as assert } from "node:assert";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import {
+  BUNDLED_SFX_RECOVERY_COMMAND,
+  BundledSfxAssetsError,
+  bundledSfxProvider,
+  extensionForBundledSfxFile,
+  inspectBundledSfxAssets,
+} from "./bundled-sfx-provider.mjs";
+import { rankMediaRows } from "./media-search.mjs";
+
+test("derives bundled SFX extension from the manifest filename", () => {
+  assert.equal(extensionForBundledSfxFile("impact.wav"), ".wav");
+  assert.equal(extensionForBundledSfxFile("whoosh.ogg"), ".ogg");
+  assert.equal(extensionForBundledSfxFile("extensionless"), ".mp3");
+});
+
+test("reports an agent-friendly recovery when the bundled SFX manifest is absent", () => {
+  const libraryDir = mkdtempSync(join(tmpdir(), "media-use-sfx-missing-"));
+  try {
+    const health = inspectBundledSfxAssets(libraryDir);
+    assert.equal(health.ok, false);
+    assert.equal(health.code, "bundled_sfx_assets_missing");
+    assert.match(health.detail, /manifest\.json/);
+    assert.match(health.fix, /hyperframes skills update media-use/);
+    assert.equal(health.fix, BUNDLED_SFX_RECOVERY_COMMAND);
+  } finally {
+    rmSync(libraryDir, { recursive: true, force: true });
+  }
+});
+
+test("reports the exact missing file from an incomplete bundled SFX install", () => {
+  const libraryDir = mkdtempSync(join(tmpdir(), "media-use-sfx-incomplete-"));
+  try {
+    writeFileSync(
+      join(libraryDir, "manifest.json"),
+      JSON.stringify({ whoosh: { file: "whoosh.mp3", description: "transition" } }),
+    );
+    const health = inspectBundledSfxAssets(libraryDir);
+    assert.equal(health.ok, false);
+    assert.equal(health.code, "bundled_sfx_assets_missing");
+    assert.match(health.detail, /whoosh\.mp3/);
+  } finally {
+    rmSync(libraryDir, { recursive: true, force: true });
+  }
+});
+
+test("bundled provider raises a typed install error instead of a generic catalog miss", async () => {
+  const libraryDir = mkdtempSync(join(tmpdir(), "media-use-sfx-provider-"));
+  try {
+    await assert.rejects(
+      () => bundledSfxProvider.search("whoosh", { libraryDir }),
+      (error) => {
+        assert.ok(error instanceof BundledSfxAssetsError);
+        assert.equal(error.code, "bundled_sfx_assets_missing");
+        assert.match(error.message, /hyperframes skills update media-use/);
+        return true;
+      },
+    );
+  } finally {
+    rmSync(libraryDir, { recursive: true, force: true });
+  }
+});
+
+test("accepts a complete bundled SFX library", () => {
+  const libraryDir = mkdtempSync(join(tmpdir(), "media-use-sfx-complete-"));
+  try {
+    mkdirSync(libraryDir, { recursive: true });
+    writeFileSync(
+      join(libraryDir, "manifest.json"),
+      JSON.stringify({ whoosh: { file: "whoosh.mp3", description: "transition" } }),
+    );
+    writeFileSync(join(libraryDir, "whoosh.mp3"), "audio");
+    assert.deepEqual(inspectBundledSfxAssets(libraryDir), {
+      ok: true,
+      count: 1,
+      detail: "1 bundled SFX asset available",
+      fix: "",
+    });
+  } finally {
+    rmSync(libraryDir, { recursive: true, force: true });
+  }
+});
+
+test("prefers an exact key over a longer key with the same words", async () => {
+  const libraryDir = mkdtempSync(join(tmpdir(), "media-use-sfx-exact-key-"));
+  try {
+    writeFileSync(
+      join(libraryDir, "manifest.json"),
+      JSON.stringify({
+        "whoosh-cinematic": { file: "whoosh-cinematic.mp3", description: "long whoosh" },
+        whoosh: { file: "whoosh.mp3", description: "short whoosh" },
+      }),
+    );
+    writeFileSync(join(libraryDir, "whoosh-cinematic.mp3"), "cinematic audio");
+    writeFileSync(join(libraryDir, "whoosh.mp3"), "exact audio");
+
+    const result = await bundledSfxProvider.search("whoosh", { libraryDir });
+    assert.equal(result?.localPath, join(libraryDir, "whoosh.mp3"));
+    assert.equal(result?.metadata.provenance.library_key, "whoosh");
+
+    const stemmed = await bundledSfxProvider.search("whooshes", { libraryDir });
+    assert.equal(stemmed?.localPath, join(libraryDir, "whoosh.mp3"));
+    assert.equal(stemmed?.metadata.provenance.library_key, "whoosh");
+  } finally {
+    rmSync(libraryDir, { recursive: true, force: true });
+  }
+});
+
+test("literal ids outrank distinct ids with the same stem", () => {
+  const rows = [
+    {
+      id: "cats",
+      title: "Cats Fighting",
+      description: "fighting cats",
+      tags: ["yowl", "fight"],
+      kind: "sfx",
+    },
+    {
+      id: "cat",
+      title: "Cat",
+      description: "single cat",
+      tags: ["meow"],
+      kind: "sfx",
+    },
+  ];
+
+  assert.deepEqual(
+    rankMediaRows("cat", rows).map((row) => row.id),
+    ["cat", "cats"],
+  );
+  assert.deepEqual(
+    rankMediaRows("cats", rows).map((row) => row.id),
+    ["cats", "cat"],
+  );
+});

package/dist/skills/media-use/scripts/lib/cache.mjs

@@ -0,0 +1,150 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync, copyFileSync } from "node:fs";
+import { join, basename } from "node:path";
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { readManifest, appendRecord, normalizePrompt } from "./manifest.mjs";
+
+const SCHEMA_PREFIX = "mu-v1-";
+const KEY_HEX_CHARS = 16;
+const COMPLETE_SENTINEL = ".hf-complete";
+
+export function globalMediaDir() {
+  return join(homedir(), ".media");
+}
+
+export function contentHash(filePath) {
+  const bytes = readFileSync(filePath);
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+function cacheEntryDir(rootDir, sha) {
+  return join(rootDir, SCHEMA_PREFIX + sha.slice(0, KEY_HEX_CHARS));
+}
+
+function isComplete(entryDir) {
+  return existsSync(join(entryDir, COMPLETE_SENTINEL));
+}
+
+function markComplete(entryDir) {
+  writeFileSync(join(entryDir, COMPLETE_SENTINEL), "", "utf8");
+}
+
+// The manifest helpers append their own ".media" to the dir they get, so the
+// global manifest must be addressed by HOME, not by globalMediaDir() — passing
+// the latter nested it at ~/.media/.media/manifest.jsonl, invisible to the
+// Studio /api/assets/global route (which reads the documented flat path).
+export function readGlobalManifest() {
+  return readManifest(homedir());
+}
+
+// Resolve a content-sha (full or unambiguous prefix) to a reusable global-cache
+// record, for `resolve --reuse <sha>`. Returns null on no match, or
+// { ambiguous: true, count } when a prefix matches multiple distinct entries.
+// Completeness (the .hf-complete sentinel) is left to importFromCache so the
+// caller can surface an "incomplete cache entry" error distinctly from a miss.
+export function findGlobalBySha(shaPrefix) {
+  const p = String(shaPrefix || "")
+    .toLowerCase()
+    .trim();
+  if (!p) return null;
+  const matches = readGlobalManifest().filter(
+    (r) => r.reusable && typeof r.sha === "string" && r.sha.startsWith(p),
+  );
+  if (matches.length === 0) return null;
+  if (matches.length > 1) {
+    const exact = matches.find((r) => r.sha === p);
+    if (exact) return exact;
+    return { ambiguous: true, count: matches.length };
+  }
+  return matches[0];
+}
+
+function validateCacheHit(match) {
+  if (!match?.sha) return null;
+  return isComplete(cacheEntryDir(globalMediaDir(), match.sha)) ? match : null;
+}
+
+export function cacheGet(prompt, type) {
+  const key = normalizePrompt(prompt);
+  if (!key) return null;
+  return validateCacheHit(
+    readGlobalManifest().find(
+      (r) =>
+        r.reusable &&
+        normalizePrompt(r.provenance?.prompt) === key &&
+        (type == null || r.type === type),
+    ),
+  );
+}
+
+export function cacheGetByEntity(entity) {
+  const lower = entity.toLowerCase();
+  return validateCacheHit(
+    readGlobalManifest().find((r) => r.reusable && r.entity && r.entity.toLowerCase() === lower),
+  );
+}
+
+export function cachePut(filePath, record) {
+  const sha = contentHash(filePath);
+  // Idempotent: same content already promoted -> don't duplicate the global
+  // record. ponytail: skips usage_count bump; add it when the metric is needed.
+  const existing = readGlobalManifest().find((r) => r.sha === sha);
+  if (existing) return { sha, cached_path: existing.cached_path, deduped: true };
+
+  const dir = globalMediaDir();
+  const entryDir = cacheEntryDir(dir, sha);
+  mkdirSync(entryDir, { recursive: true });
+
+  const dest = join(entryDir, basename(filePath));
+  copyFileSync(filePath, dest);
+  markComplete(entryDir);
+
+  const globalRecord = {
+    ...record,
+    sha,
+    reusable: true,
+    cached_path: dest,
+  };
+  appendRecord(homedir(), globalRecord);
+  return { sha, cached_path: dest };
+}
+
+export function importFromCache(cacheRecord, projectDir, localId, localPath) {
+  const sha = cacheRecord.sha;
+  const entryDir = cacheEntryDir(globalMediaDir(), sha);
+  if (!isComplete(entryDir)) return null;
+
+  const cachedFile = cacheRecord.cached_path;
+  if (!cachedFile || !existsSync(cachedFile)) return null;
+
+  mkdirSync(join(projectDir, ".media"), { recursive: true });
+  const fullDest = join(projectDir, localPath);
+  mkdirSync(join(fullDest, ".."), { recursive: true });
+  copyFileSync(cachedFile, fullDest);
+
+  const projectRecord = {
+    ...cacheRecord,
+    id: localId,
+    path: localPath,
+    provenance: {
+      ...cacheRecord.provenance,
+      imported_from: sha,
+    },
+  };
+  delete projectRecord.sha;
+  delete projectRecord.reusable;
+  delete projectRecord.cached_path;
+
+  return projectRecord;
+}
+
+export function promote(projectDir, id) {
+  const records = readManifest(projectDir);
+  const record = records.find((r) => r.id === id);
+  if (!record) throw new Error(`asset not found in project manifest: ${id}`);
+
+  const filePath = join(projectDir, record.path);
+  if (!existsSync(filePath)) throw new Error(`asset file not found: ${filePath}`);
+
+  return cachePut(filePath, record);
+}

package/dist/skills/media-use/scripts/lib/candidates.mjs

@@ -0,0 +1,91 @@
+// Reuse candidates: a side-effect-free view of assets already available to this
+// project (its own manifest) and across every project (the global ~/.media
+// cache), so the calling agent can judge semantic fit itself. No download, no
+// provider, no mutation. The ranker only *surfaces* — it orders by lexical
+// overlap but never filters a candidate out on zero overlap (that would
+// pre-empt the agent's judgment); the agent does the semantic call.
+
+import { readManifest } from "./manifest.mjs";
+import { readGlobalManifest } from "./cache.mjs";
+import { tokenOverlap, typesMatch } from "./match.mjs";
+
+export const CANDIDATE_CAP = 8;
+
+function shape(record, scope, intent) {
+  const description = record.description || record.provenance?.prompt || "";
+  const prompt = record.provenance?.prompt || null;
+  return {
+    id: record.id,
+    type: record.type,
+    scope,
+    description,
+    prompt,
+    provider: record.provenance?.provider || null,
+    duration: record.duration ?? null,
+    width: record.width ?? null,
+    height: record.height ?? null,
+    // Only global records carry a content sha — it is the stable reuse handle
+    // for `resolve --reuse <sha>`. Project assets are reused by referencing
+    // their path directly, so they need no handle.
+    sha: scope === "global" ? record.sha || null : null,
+    path: scope === "project" ? record.path : null,
+    score: intent ? tokenOverlap(intent, `${description} ${prompt || ""}`) : 0,
+  };
+}
+
+// Rank one scope: type-matched (icon<->image aware), newest-first within equal
+// overlap, ordered by overlap desc. Returns the full ranked list (uncapped).
+function rankScope(records, scope, type, intent) {
+  return records
+    .filter((r) => typesMatch(r.type, type))
+    .reverse() // manifest is append-order (oldest first); newest-first at equal score
+    .map((r) => shape(r, scope, intent))
+    .sort((a, b) => b.score - a.score); // Array.sort is stable → recency preserved
+}
+
+// List reuse candidates for `type`, capped per scope. Returns:
+//   candidates: capped project candidates followed by capped global candidates
+//   truncated:  true if either scope had more than `cap`
+//   total:      { project, global } counts before the cap (machine-readable)
+//   similar:    count of candidates with lexical overlap > 0 (drives the nudge)
+export function listCandidates({ projectDir, type, intent = "", cap = CANDIDATE_CAP }) {
+  const project = rankScope(readManifest(projectDir), "project", type, intent);
+  const global = rankScope(readGlobalManifest(), "global", type, intent);
+  const candidates = [...project.slice(0, cap), ...global.slice(0, cap)];
+  return {
+    candidates,
+    truncated: project.length > cap || global.length > cap,
+    total: { project: project.length, global: global.length },
+    similar: [...project, ...global].filter((c) => c.score > 0).length,
+  };
+}
+
+function meta(c) {
+  const parts = [];
+  if (c.duration != null) parts.push(`${c.duration}s`);
+  if (c.width && c.height) parts.push(`${c.width}x${c.height}`);
+  if (c.provider) parts.push(c.provider);
+  return parts.join(", ");
+}
+
+// Human-readable listing. The agent can read this directly; --json is for
+// programmatic use. Reuse handle differs by scope: path for project, sha for
+// global.
+export function formatCandidates(candidates, { truncated, total } = {}) {
+  if (candidates.length === 0) return "no reuse candidates found (project or global cache)";
+  const lines = [`${candidates.length} reuse candidate${candidates.length === 1 ? "" : "s"}:`, ""];
+  for (const c of candidates) {
+    const handle =
+      c.scope === "global" ? `--reuse ${String(c.sha).slice(0, 16)}` : c.path || `manifest:${c.id}`;
+    const m = meta(c);
+    lines.push(`  [${c.scope}] ${c.description}${m ? ` (${m})` : ""}`);
+    lines.push(`          ${handle}`);
+  }
+  if (truncated && total) {
+    lines.push("");
+    lines.push(
+      `  (showing top ${CANDIDATE_CAP} per scope; ${total.project} project / ${total.global} global total — refine --intent to narrow)`,
+    );
+  }
+  return lines.join("\n");
+}

package/dist/skills/media-use/scripts/lib/candidates.test.mjs

@@ -0,0 +1,155 @@
+import { test } from "node:test";
+import { strict as assert } from "node:assert";
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { listCandidates, formatCandidates, CANDIDATE_CAP } from "./candidates.mjs";
+import { findGlobalBySha } from "./cache.mjs";
+
+// candidates + findGlobalBySha are offline (no heygen), so we can override HOME
+// to a temp dir and seed a fake global ~/.media manifest deterministically.
+function sandbox() {
+  const root = mkdtempSync(join(tmpdir(), "mu-cand-"));
+  const project = join(root, "proj");
+  const home = join(root, "home");
+  process.env.HOME = home;
+  return { root, project, home };
+}
+function seedManifest(dir, records) {
+  const md = join(dir, ".media");
+  mkdirSync(md, { recursive: true });
+  writeFileSync(md + "/manifest.jsonl", records.map((r) => JSON.stringify(r)).join("\n") + "\n");
+}
+function proj(id, type, description, prompt) {
+  return { id, type, path: `.media/audio/bgm/${id}.wav`, description, provenance: { prompt } };
+}
+function glob(id, type, description, prompt, sha) {
+  return {
+    id,
+    type,
+    sha,
+    reusable: true,
+    cached_path: `/x/${sha}/${id}.wav`,
+    description,
+    provenance: { prompt, provider: "heygen.audio.sounds" },
+  };
+}
+
+test("ranks project + global by overlap, tags scope", () => {
+  const { root, project, home } = sandbox();
+  try {
+    seedManifest(project, [proj("bgm_001", "bgm", "calm ambient piano", "calm ambient piano")]);
+    seedManifest(home, [
+      glob("bgm_009", "bgm", "energetic tech launch", "energetic tech launch", "a".repeat(64)),
+      glob("bgm_010", "bgm", "sad corporate piano", "sad corporate piano", "b".repeat(64)),
+    ]);
+    const { candidates } = listCandidates({
+      projectDir: project,
+      type: "bgm",
+      intent: "tech launch",
+    });
+    assert.equal(candidates[0].scope, "project"); // project listed first
+    const g = candidates.filter((c) => c.scope === "global");
+    assert.equal(g[0].description, "energetic tech launch"); // higher overlap ranks first
+    assert.ok(g[0].score >= g[1].score);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("zero-overlap intent still lists candidates (no hard filter)", () => {
+  const { root, project, home } = sandbox();
+  try {
+    seedManifest(project, []);
+    seedManifest(home, [glob("bgm_009", "bgm", "driving synth", "driving synth", "c".repeat(64))]);
+    const { candidates, similar } = listCandidates({
+      projectDir: project,
+      type: "bgm",
+      intent: "totally unrelated words xyz",
+    });
+    assert.equal(candidates.length, 1, "listed despite zero overlap");
+    assert.equal(candidates[0].score, 0);
+    assert.equal(similar, 0, "similar counts only overlap>0");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("caps per scope and reports truncation + totals", () => {
+  const { root, project, home } = sandbox();
+  try {
+    const many = Array.from({ length: CANDIDATE_CAP + 3 }, (_, i) =>
+      glob(`bgm_${i}`, "bgm", `track ${i}`, `track ${i}`, String(i).padStart(64, "0")),
+    );
+    seedManifest(project, []);
+    seedManifest(home, many);
+    const { candidates, truncated, total } = listCandidates({ projectDir: project, type: "bgm" });
+    assert.equal(candidates.length, CANDIDATE_CAP);
+    assert.equal(truncated, true);
+    assert.equal(total.global, CANDIDATE_CAP + 3);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("honors icon<->image adjacency", () => {
+  const { root, project, home } = sandbox();
+  try {
+    seedManifest(project, []);
+    seedManifest(home, [glob("image_1", "image", "rocket logo", "rocket logo", "d".repeat(64))]);
+    const { candidates } = listCandidates({ projectDir: project, type: "icon", intent: "rocket" });
+    assert.equal(candidates.length, 1, "image asset surfaces for icon request");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("sha only on global, path only on project", () => {
+  const { root, project, home } = sandbox();
+  try {
+    seedManifest(project, [proj("bgm_001", "bgm", "x", "x")]);
+    seedManifest(home, [glob("bgm_009", "bgm", "y", "y", "e".repeat(64))]);
+    const { candidates } = listCandidates({ projectDir: project, type: "bgm" });
+    const p = candidates.find((c) => c.scope === "project");
+    const g = candidates.find((c) => c.scope === "global");
+    assert.ok(p.path && !p.sha);
+    assert.ok(g.sha && !g.path);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("findGlobalBySha resolves unique prefix, flags ambiguity, misses cleanly", () => {
+  const { root, project, home } = sandbox();
+  try {
+    seedManifest(project, []);
+    seedManifest(home, [
+      glob("bgm_1", "bgm", "a", "a", "abc" + "0".repeat(61)),
+      glob("bgm_2", "bgm", "b", "b", "abd" + "0".repeat(61)),
+      glob("bgm_3", "bgm", "c", "c", "fff" + "0".repeat(61)),
+    ]);
+    assert.equal(findGlobalBySha("fff").id, "bgm_3", "unique prefix resolves");
+    assert.deepEqual(
+      { ambiguous: findGlobalBySha("ab").ambiguous, count: findGlobalBySha("ab").count },
+      { ambiguous: true, count: 2 },
+      "ambiguous prefix flagged",
+    );
+    assert.equal(findGlobalBySha("zzz"), null, "miss returns null");
+    assert.equal(findGlobalBySha(""), null, "empty returns null");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("formatCandidates shows reuse handles by scope; empty message", () => {
+  const { candidates } = {
+    candidates: [
+      { scope: "project", description: "p", path: ".media/audio/bgm/bgm_001.wav" },
+      { scope: "global", description: "g", sha: "f".repeat(64) },
+    ],
+  };
+  const out = formatCandidates(candidates, {});
+  assert.match(out, /\.media\/audio\/bgm\/bgm_001\.wav/);
+  assert.match(out, /--reuse ffffffffffffffff/);
+  assert.match(formatCandidates([], {}), /no reuse candidates/);
+});