dsh-hyperframes 0.10.1 → 0.11.0

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

@@ -0,0 +1,110 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { test } from "node:test";
+import { appendRecord } from "./manifest.mjs";
+import {
+  cacheGet,
+  cacheGetByEntity,
+  cachePut,
+  findGlobalBySha,
+  importFromCache,
+  readGlobalManifest,
+} from "./cache.mjs";
+
+function sandbox(t) {
+  const root = mkdtempSync(join(tmpdir(), "mu-cache-recovery-"));
+  const previous = process.env.HYPERFRAMES_MEDIA_HOME;
+  process.env.HYPERFRAMES_MEDIA_HOME = join(root, "library");
+  t.after(() => {
+    if (previous === undefined) delete process.env.HYPERFRAMES_MEDIA_HOME;
+    else process.env.HYPERFRAMES_MEDIA_HOME = previous;
+    rmSync(root, { recursive: true, force: true });
+  });
+  const source = join(root, "original.wav");
+  const bytes = "cache recovery fixture";
+  writeFileSync(source, bytes);
+  const record = {
+    id: "bgm_001",
+    type: "bgm",
+    entity: "Recovery",
+    provenance: { prompt: "cache recovery" },
+  };
+  return { root, source, bytes, record };
+}
+
+for (const invalid of [
+  "missing file",
+  "missing marker",
+  "missing directory",
+  "empty file",
+  "directory",
+]) {
+  test(`cachePut repairs a ${invalid} before deduplicating`, (t) => {
+    const { root, source, bytes, record } = sandbox(t);
+    const first = cachePut(source, record);
+    const entry = dirname(first.cached_path);
+    if (invalid === "missing marker") rmSync(join(entry, ".hf-complete"));
+    else if (invalid === "missing directory") rmSync(entry, { recursive: true });
+    else if (invalid === "empty file") writeFileSync(first.cached_path, "");
+    else {
+      rmSync(first.cached_path);
+      if (invalid === "directory") mkdirSync(first.cached_path);
+    }
+
+    const replacement = join(root, "replacement.wav");
+    writeFileSync(replacement, bytes);
+    const repaired = cachePut(replacement, record);
+
+    assert.equal(repaired.deduped, undefined);
+    assert.equal(repaired.sha, first.sha);
+    assert.equal(readFileSync(repaired.cached_path, "utf8"), bytes);
+    const cached = cacheGet("  Cache  Recovery ", "bgm");
+    assert.equal(cached?.sha, repaired.sha);
+    assert.equal(readFileSync(cached.cached_path, "utf8"), bytes);
+    assert.equal(cacheGetByEntity("recovery")?.sha, repaired.sha);
+    const imported = importFromCache(cached, join(root, "project"), "bgm_002", "restored.wav");
+    assert.equal(imported?.provenance.imported_from, first.sha);
+    assert.equal(readFileSync(join(root, "project", "restored.wav"), "utf8"), bytes);
+  });
+}
+
+test("an intact cache stays deduplicated without adding a manifest record", (t) => {
+  const { source, record } = sandbox(t);
+  const first = cachePut(source, record);
+  const second = cachePut(source, record);
+
+  assert.deepEqual(second, { ...first, deduped: true });
+  assert.equal(readGlobalManifest().length, 1);
+});
+
+test("prompt and entity lookups skip a stale entry for another complete match", (t) => {
+  const { root, source, record } = sandbox(t);
+  const first = cachePut(source, record);
+  rmSync(first.cached_path);
+  const secondSource = join(root, "second.wav");
+  writeFileSync(secondSource, "different reusable bytes");
+  const second = cachePut(secondSource, record);
+
+  assert.equal(cacheGet("cache recovery", "bgm")?.sha, second.sha);
+  assert.equal(cacheGetByEntity("RECOVERY")?.sha, second.sha);
+  assert.equal(cacheGet("cache recovery", "sfx"), null);
+});
+
+test("sha reuse counts distinct content and selects the repaired record", (t) => {
+  const { root, source, bytes, record } = sandbox(t);
+  const first = cachePut(source, record);
+  rmSync(first.cached_path);
+  const replacement = join(dirname(first.cached_path), "replacement.wav");
+  writeFileSync(replacement, bytes);
+  appendRecord(join(root, "library"), {
+    ...record,
+    sha: first.sha,
+    reusable: true,
+    cached_path: replacement,
+  });
+
+  assert.equal(findGlobalBySha(first.sha)?.cached_path, replacement);
+  assert.equal(findGlobalBySha(first.sha.slice(0, 16))?.cached_path, replacement);
+});

package/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 { currentRecords } 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(currentRecords(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/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 point HYPERFRAMES_MEDIA_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.HYPERFRAMES_MEDIA_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/);
+});

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

@@ -0,0 +1,161 @@
+import { execFileSync } from "node:child_process";
+import { copyFileSync, existsSync, readdirSync, statSync, unlinkSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+
+// Image generation via the OpenAI Codex CLI's built-in image tool (gpt-image-2)
+// on the user's ChatGPT subscription: the codex CLI owns auth, media-use holds
+// no key (CLI-only). The image UPSELL behind local mflux; skipped by --local-only.
+//
+// Retrieval mirrors illo-skill rather than trusting the model to save a file:
+// `--enable image_generation` makes the built-in tool drop the rendered artifact
+// into $CODEX_HOME/generated_images/, and we fetch the freshest file that
+// postdates this run. The save-to-path instruction is only a best-effort
+// verify-first.
+//
+// The flag was called `imagegenext` until Codex CLI ~0.145, which renamed it to
+// `image_generation` and dropped the old row from `codex features list`. Both
+// the gate below and the --enable arg track the new name, with a fallback to
+// the old one so older CLIs keep working.
+
+const TIMEOUT_MS = 600000; // codex exec round-trips the sub; first-run tool spin-up is slow
+const MTIME_SKEW_MS = 2000; // tolerate mtime granularity / clock skew (illo uses 2s)
+
+function codexGeneratedDir() {
+  // Codex relocates CODEX_HOME on some hosts, so resolve it at run time.
+  return join(process.env.CODEX_HOME || join(homedir(), ".codex"), "generated_images");
+}
+
+// Newest artifact that postdates `sinceMs` (minus skew), so a stale prior render
+// or a concurrent session's file can't be mistaken for this run's output.
+function freshestGeneratedImage(sinceMs) {
+  const dir = codexGeneratedDir();
+  if (!existsSync(dir)) return null;
+  const floor = sinceMs - MTIME_SKEW_MS;
+  let best = null;
+  for (const name of readdirSync(dir)) {
+    let st;
+    try {
+      st = statSync(join(dir, name));
+    } catch {
+      continue;
+    }
+    if (!st.isFile() || st.mtimeMs < floor) continue;
+    if (!best || st.mtimeMs > best.mtimeMs) best = { path: join(dir, name), mtimeMs: st.mtimeMs };
+  }
+  return best?.path ?? null;
+}
+
+// Short `codex` subcommand → combined stdout+stderr, or null if it can't run.
+function codexRun(args) {
+  try {
+    return execFileSync("codex", args, {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 10000,
+    });
+  } catch (err) {
+    return `${err.stdout?.toString() ?? ""}${err.stderr?.toString() ?? ""}` || null;
+  }
+}
+
+// Name of the feature flag this CLI uses for the extended image tool, or null if
+// it exposes neither. Newer CLIs list only `image_generation`; older ones list
+// `imagegenext` alongside it and reject the new name on --enable.
+export function imageGenFlag(feats) {
+  if (/\bimagegenext\b/.test(feats)) return "imagegenext";
+  if (/\bimage_generation\b/.test(feats)) return "image_generation";
+  return null;
+}
+
+// Fail-fast host check (mirrors illo): don't burn a minutes-long exec when Codex
+// isn't usable. Returns { flag } when ready, else { reason }. The flag ships
+// default-disabled, so we check the ROW is present (the capability signal) — the
+// exec enables it per-render with --enable.
+function codexUnavailableReason() {
+  try {
+    const which = process.platform === "win32" ? "where" : "which";
+    execFileSync(which, ["codex"], { stdio: ["ignore", "ignore", "ignore"], timeout: 5000 });
+  } catch {
+    // A shell alias (e.g. `codex → /Applications/Codex.app/...`) is NOT enough:
+    // aliases live only in the interactive shell, so a spawned subprocess's PATH
+    // lookup can't see them. Symlink the real binary onto PATH.
+    return {
+      reason:
+        'codex CLI not reachable on PATH (a shell alias won\'t work — spawned processes can\'t see aliases; symlink the real binary onto PATH, e.g. ln -s "$(readlink -f "$(command -v codex)")" ~/.local/bin/codex)',
+    };
+  }
+  // Auth marker: presence of the credentials file, NOT `codex login status`.
+  // That command prints "Logged in using ChatGPT" only to a human stream
+  // (stderr / TTY) and exits 0, so its piped stdout — how media-use spawns it —
+  // is empty, and the gate falsely reported "not logged in", blocking codex
+  // image gen in every headless / CI / agent run even when fully authed.
+  // auth.json is the durable, TTY-independent signal; token validity is proven
+  // by the exec itself, which fails cleanly if the login is stale.
+  const authPath = join(process.env.CODEX_HOME || join(homedir(), ".codex"), "auth.json");
+  if (!existsSync(authPath)) return { reason: "codex not logged in (run: codex login)" };
+  const feats = codexRun(["features", "list"]);
+  if (feats == null) return { reason: "could not read `codex features list`" };
+  const flag = imageGenFlag(feats);
+  if (!flag) return { reason: "codex image generation feature unavailable (upgrade Codex CLI)" };
+  return { flag };
+}
+
+export async function codexImageGenerate(intent) {
+  const { reason, flag } = codexUnavailableReason();
+  if (reason) {
+    console.error(`media-use: codex image upsell unavailable: ${reason}`);
+    return null;
+  }
+  const outPath = join(tmpdir(), `media-use-codex-${process.pid}-${Date.now()}.png`);
+  const prompt =
+    `${intent}\n\n` +
+    `Use your built-in image generation tool to render this, then save the image ` +
+    `to ${outPath} (overwrite if it exists). Do not ask for confirmation. ` +
+    `If you have no built-in image tool, do nothing (no PIL/matplotlib/SVG substitute).`;
+  try {
+    unlinkSync(outPath); // clear any prior file so verify-first can't accept a stale render
+  } catch {
+    /* no prior file */
+  }
+  const started = Date.now();
+  try {
+    execFileSync(
+      "codex",
+      [
+        "exec",
+        "--cd",
+        tmpdir(),
+        "-s",
+        "workspace-write",
+        "--skip-git-repo-check",
+        "--enable",
+        flag,
+        "-",
+      ],
+      { input: prompt, encoding: "utf8", timeout: TIMEOUT_MS, stdio: ["pipe", "pipe", "pipe"] },
+    );
+  } catch (err) {
+    console.error(
+      `media-use: \`codex exec\` image generation failed: ${err.stderr?.toString().trim().slice(-200) || err.message}`,
+    );
+    return null;
+  }
+  // Verify-first (save-to-path may have worked), else fetch the image-tool artifact.
+  const produced =
+    existsSync(outPath) && statSync(outPath).size > 0 ? outPath : freshestGeneratedImage(started);
+  if (!produced) return null;
+  if (produced !== outPath) {
+    try {
+      copyFileSync(produced, outPath);
+    } catch {
+      return null;
+    }
+  }
+  return {
+    localPath: outPath,
+    ext: ".png",
+    source: "generated",
+    metadata: { description: intent, provider: "codex.image_gen", provenance: { prompt: intent } },
+  };
+}

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

@@ -0,0 +1,34 @@
+import test from "node:test";
+import assert from "node:assert";
+import { imageGenFlag } from "./codex-provider.mjs";
+
+// Real `codex features list` output is three space-padded columns:
+//   <name> <stage> <enabled>
+const OLD_CLI = [
+  "image_detail_original               removed            false",
+  "image_generation                    stable             true",
+  "imagegenext                         under development  false",
+].join("\n");
+
+const NEW_CLI = [
+  "image_detail_original               removed            false",
+  "image_generation                    stable             true",
+].join("\n");
+
+test("older CLIs keep the old flag — they reject --enable image_generation", () => {
+  assert.equal(imageGenFlag(OLD_CLI), "imagegenext");
+});
+
+test("Codex CLI >=0.145 dropped the imagegenext row; fall back to its new name", () => {
+  // The regression this guards: gating on `imagegenext` alone made the provider
+  // report "unavailable" on every up-to-date CLI, without attempting a render.
+  assert.equal(imageGenFlag(NEW_CLI), "image_generation");
+});
+
+test("no image feature at all is unavailable, not a silent default", () => {
+  assert.equal(imageGenFlag("apps  stable  true\nhooks  stable  true"), null);
+});
+
+test("substring lookalikes do not count as the feature row", () => {
+  assert.equal(imageGenFlag("image_generation_v2  stable  true"), null);
+});

package/skills/media-use/scripts/lib/config-lock.d.mts

@@ -0,0 +1,3 @@
+import type * as fs from "node:fs";
+
+export function withFileLock<T>(lockPath: string, fsModule: typeof fs, task: () => T): T;

package/skills/media-use/scripts/lib/config-lock.test.mjs

@@ -0,0 +1,79 @@
+import { strict as assert } from "node:assert";
+import { spawn } from "node:child_process";
+import { test } from "node:test";
+import * as fs from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { withFileLock } from "./config-lock.mjs";
+
+function lockIn() {
+  const dir = fs.mkdtempSync(join(tmpdir(), "hf-config-lock-"));
+  return {
+    lock: join(dir, "config.json.lock"),
+    cleanup: () => fs.rmSync(dir, { recursive: true }),
+  };
+}
+
+test("returns the task's result even when the lock cannot be released", () => {
+  const { lock, cleanup } = lockIn();
+  try {
+    const refusing = {
+      ...fs,
+      rmSync(path, options) {
+        if (path === lock) throw Object.assign(new Error("EPERM"), { code: "EPERM" });
+        return fs.rmSync(path, options);
+      },
+    };
+    assert.equal(
+      withFileLock(lock, refusing, () => "saved"),
+      "saved",
+    );
+  } finally {
+    cleanup();
+  }
+});
+
+test("refuses a lock left by a process that stopped, names it, and never removes it", () => {
+  const { lock, cleanup } = lockIn();
+  try {
+    fs.writeFileSync(lock, "dead");
+    const past = new Date(Date.now() - 60_000);
+    fs.utimesSync(lock, past, past);
+    const started = Date.now();
+    let ran = false;
+
+    assert.throws(
+      () => withFileLock(lock, fs, () => (ran = true)),
+      (error) => error.code === "HF_SETTINGS_LOCKED" && error.message.includes(lock),
+    );
+    assert.ok(Date.now() - started < 1000);
+    assert.equal(ran, false);
+    assert.equal(fs.readFileSync(lock, "utf8"), "dead");
+  } finally {
+    cleanup();
+  }
+});
+
+test("waits for a process that holds the lock, then takes it", async () => {
+  const { lock, cleanup } = lockIn();
+  try {
+    const script = `
+      const fs = require("fs");
+      const lock = process.argv[1];
+      fs.writeFileSync(lock, "other", { flag: "wx" });
+      process.stdout.write("locked\\n");
+      setTimeout(() => {
+        fs.writeFileSync(lock + ".released", String(Date.now()));
+        fs.rmSync(lock);
+      }, 300);`;
+    const other = spawn(process.execPath, ["-e", script, lock]);
+    await new Promise((ready) => other.stdout.once("data", ready));
+
+    const ranAt = withFileLock(lock, fs, () => Date.now());
+
+    assert.ok(ranAt >= Number(fs.readFileSync(`${lock}.released`, "utf8")));
+    await new Promise((exited) => other.once("exit", exited));
+  } finally {
+    cleanup();
+  }
+});