fix: media-use bug-bash fixes (codex gate, id race, provider/reuse/adopt guards) + CLI unknown-flag rejection (#2033)

* fix(media-use): codex gate misfires as 'not logged in' when piped

codexUnavailableReason() gated generation on parsing `codex login status`
stdout, but that command prints 'Logged in using ChatGPT' to stderr and
exits 0 — so the piped stdout media-use captures (execFileSync returns
stdout only on success) was empty, and the gate falsely reported 'not
logged in'. Every headless / CI / agent run was blocked from codex image
gen even when fully authed.

Gate on the durable credentials file ($CODEX_HOME/auth.json) instead of
the TTY/stderr-only human text. Token validity is still proven by the
exec, which fails cleanly on a stale login. The stdout `features list`
capability check is unchanged.

Verified: reproduced the false 'not logged in' block, then after the fix
generated end-to-end via `resolve -t image --provider codex` (valid
1254x1254 PNG, source=generated, provider=codex.image_gen).

* fix(media-use): bug-bash fixes — id race, provider/reuse/adopt guards

From the bug-bash against main:

- MU-23 (HIGH): concurrent resolves raced on nextId (read-max-then-append,
  non-atomic), so parallel agents got duplicate ids and clobbered each
  other's files. Add allocateId(): a coarse per-project lock (.media/.lock,
  15s stale-steal) around id allocation that scans the manifest AND the
  type dir for reserved ids, then O_EXCL-creates a placeholder file so the
  slow download between allocate and append can't collide. 5 parallel
  resolves now yield 5 distinct ids + files.
- X4: --reuse imported across a type mismatch (bgm asset under images/).
  Apply typesMatch on the --reuse path; reject mismatches (icon<->image
  still interchangeable).
- X5: --provider silently overrode --local-only and made a network call.
  --local-only is now a hard guard: network providers are skipped even
  under a forced provider; the miss message explains the conflict.
- BUG-2: --provider ignored the exact-cache floor and could hand back an
  asset from a different provider. A forced --provider now bypasses all
  reuse rungs (regenerate with THIS provider); the unforced floor is intact.
- MU-26/X6: 0-byte assets accepted. --adopt skips 0-byte files (loud); ingest
  refuses a 0-byte local file (freezeUrl already rejects empty responses).
- BUG-4: unknown/unavailable --provider now errors with the available list
  instead of a generic 'no provider could resolve' (typo != catalog miss).
- BUG-5: --reuse "" gave the wrong 'type and intent required' error; it now
  routes to a clear empty-sha message.
- BUG-3: voice duration leaked an unrounded float into index.md; round all
  durations to 0.1s centrally at record build (matches probe).
- Nits: whitespace-only --intent is rejected; nudge grammar (exists/exist).

Tests: allocateId reservation + registry local-only-wins added; full
media-use suite green. All fixes verified e2e.

* fix(cli): reject unknown flags instead of silently ignoring them

citty is permissive: an unrecognized flag was dropped, not rejected — so
`render . --out x` (the flag is --output/-o) silently ignored --out and
rendered to the default renders/<name>.mp4 path. A mistyped flag read as a
render/catalog miss.

Add assertKnownFlags(): validate every dash-prefixed token against the
command's declared args + aliases + the global set (help/version/json)
before the command runs, in the shared trackCommandFailures run-wrapper so
every leaf command is covered. Handles --flag=value, --no-<bool> negation,
camelCase<->kebab arg names, and combined shorts; stops at --; positionals
and flag values pass through.

Verified: `render . --out x` -> 'Error: Unknown flag: --out'; --output/-o/
--json/--help still accepted. Unit tests added.

* docs(skills): install with --full-depth so agents get current main

The documented `npx skills add heygen-com/hyperframes` fetched the
skills.sh registry blob, which lags GitHub main by hours — so users
following the docs got a stale skill (e.g. media-use v1: no --candidates,
voice stubbed). The CLI's own `hyperframes skills` command already forces
a full clone via --full-depth to bypass this; the docs didn't pass it.

Add --full-depth to every documented install command (README, CLAUDE.md,
docs/guides/skills.mdx) with a one-line note on the lag. Addresses the
user-facing half of the publish/registry lag (#2034).

* chore(media-use): collapse resolve.mjs import to satisfy oxfmt --check

* fix(cli): extract longFlagName to keep flag validator under complexity gate

Also regenerate skills-manifest.json (resolve.mjs formatting change re-hashed
the media-use skill). Fixes the Fallow audit + skills-manifest-in-sync CI gates.

skills/media-use/scripts/lib/manifest.mjs

@@ -1,4 +1,15 @@
-import { readFileSync, appendFileSync, mkdirSync, existsSync } from "node:fs";
+import {
+  readFileSync,
+  appendFileSync,
+  mkdirSync,
+  existsSync,
+  readdirSync,
+  openSync,
+  closeSync,
+  writeFileSync,
+  rmSync,
+  statSync,
+} from "node:fs";
 import { join } from "node:path";
 
 const MANIFEST_FILE = "manifest.jsonl";
@@ -103,3 +114,75 @@ export function nextId(projectDir, type) {
   }
   return `${prefix}_${String(max + 1).padStart(3, "0")}`;
 }
+
+// Sync sleep (no busy-spin) for the allocation lock retry.
+function sleepMs(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+// Coarse per-project lock so concurrent resolves don't race on id allocation.
+// ponytail: one lock file with a 15s stale-steal (a crashed holder can't wedge
+// the project); fine for agent-scale concurrency — revisit if throughput needs
+// finer locking. Date.now() is available here (a normal Node CLI, not a
+// workflow DSL), so mtime-based staleness is safe.
+const LOCK_STALE_MS = 15000;
+const LOCK_TIMEOUT_MS = 20000;
+
+function withLock(dir, fn) {
+  const lock = join(dir, ".lock");
+  const start = Date.now();
+  for (;;) {
+    try {
+      closeSync(openSync(lock, "wx")); // O_EXCL: atomic acquire
+      break;
+    } catch (err) {
+      if (err.code !== "EEXIST") throw err;
+      try {
+        if (Date.now() - statSync(lock).mtimeMs > LOCK_STALE_MS) {
+          rmSync(lock, { force: true }); // steal a stale lock from a dead holder
+          continue;
+        }
+      } catch {
+        continue; // lock vanished between check and stat — retry the acquire
+      }
+      if (Date.now() - start > LOCK_TIMEOUT_MS) {
+        throw new Error("media-use: timed out acquiring .media/.lock");
+      }
+      sleepMs(25);
+    }
+  }
+  try {
+    return fn();
+  } finally {
+    rmSync(lock, { force: true });
+  }
+}
+
+// Atomically allocate the next free id for `type` AND reserve its file, so a
+// slow download/copy between allocation and appendRecord can't let a concurrent
+// caller grab the same id (the MU-23 clobber). Under the lock we take the max id
+// across BOTH the manifest and any already-reserved files in the type dir, then
+// O_EXCL-create an empty placeholder at the target path; freeze/copy overwrites
+// it. Returns { id, localPath }.
+export function allocateId(projectDir, type, ext) {
+  mkdirSync(mediaDir(projectDir), { recursive: true });
+  const typeDir = typeDirPath(projectDir, type);
+  mkdirSync(typeDir, { recursive: true });
+  return withLock(mediaDir(projectDir), () => {
+    const re = new RegExp(`^${type}_(\\d+)`);
+    let max = 0;
+    for (const r of readManifest(projectDir)) {
+      if (r.type !== type) continue;
+      const m = r.id?.match(re);
+      if (m) max = Math.max(max, parseInt(m[1], 10));
+    }
+    for (const f of readdirSync(typeDir)) {
+      const m = f.match(re);
+      if (m) max = Math.max(max, parseInt(m[1], 10)); // skip ids reserved but not yet appended
+    }
+    const id = `${type}_${String(max + 1).padStart(3, "0")}`;
+    const localPath = `.media/${typeSubdir(type)}/${id}${ext}`;
+    writeFileSync(join(projectDir, localPath), "", { flag: "wx" }); // durable reservation
+    return { id, localPath };
+  });
+}