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.

packages/cli/src/utils/command-failure-tracking.ts

@@ -1,4 +1,5 @@
 import type { CommandDef } from "citty";
+import { assertKnownFlags } from "./reject-unknown-flags.js";
 
 // citty types subcommands as `CommandDef<any>` (SubCommandsDef); mirror that so
 // each command's specific args type is accepted without per-command generics.
@@ -29,6 +30,11 @@ export function trackCommandFailures(
       return {
         ...cmd,
         run: async (ctx: Parameters<typeof run>[0]) => {
+          // Reject unknown flags before the command runs: citty silently ignores
+          // them otherwise, dropping the value (e.g. `render --out x` fell back
+          // to the default output path). A leaf command with a `run` is the right
+          // place — nested command groups delegate to their own subcommands.
+          assertKnownFlags(cmd, ctx?.rawArgs ?? []);
           try {
             return await run(ctx);
           } catch (err) {

packages/cli/src/utils/reject-unknown-flags.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest";
+import type { ArgsDef, CommandDef } from "citty";
+import { assertKnownFlags } from "./reject-unknown-flags.js";
+
+const cmd = {
+  args: {
+    output: { type: "string", alias: "o" },
+    gifLoop: { type: "string" },
+    docker: { type: "boolean" },
+    workers: { type: "string", alias: ["w"] },
+  },
+} as unknown as CommandDef<ArgsDef>;
+
+const ok = (raw: string[]) => () => assertKnownFlags(cmd, raw);
+
+describe("assertKnownFlags", () => {
+  it("accepts known long and short flags, positionals, and values", () => {
+    expect(ok(["."])).not.toThrow();
+    expect(ok([".", "--output", "out.mp4"])).not.toThrow();
+    expect(ok([".", "-o", "out.mp4"])).not.toThrow();
+    expect(ok(["--output=out.mp4"])).not.toThrow();
+    expect(ok(["--workers", "6", "-w", "6"])).not.toThrow();
+  });
+
+  it("rejects an unknown long flag (the --out bug)", () => {
+    expect(ok([".", "--out", "out.mp4"])).toThrow(/Unknown flag: --out/);
+  });
+
+  it("rejects an unknown short flag", () => {
+    expect(ok(["-z"])).toThrow(/Unknown flag: -z/);
+  });
+
+  it("matches camelCase args by their kebab-case flag spelling", () => {
+    expect(ok(["--gif-loop", "0"])).not.toThrow();
+    expect(ok(["--gifLoop", "0"])).not.toThrow();
+  });
+
+  it("accepts --no-<boolean> negation", () => {
+    expect(ok(["--no-docker"])).not.toThrow();
+  });
+
+  it("accepts global flags and stops at --", () => {
+    expect(ok(["--help"])).not.toThrow();
+    expect(ok(["--json"])).not.toThrow();
+    expect(ok(["--", "--anything-goes-here"])).not.toThrow();
+  });
+
+  it("checks each char of a combined short group", () => {
+    expect(ok(["-ow"])).not.toThrow(); // both known aliases
+    expect(ok(["-ox"])).toThrow(/Unknown flag: -x/); // x unknown
+  });
+});

packages/cli/src/utils/reject-unknown-flags.ts

@@ -0,0 +1,69 @@
+import type { ArgsDef, CommandDef } from "citty";
+
+// citty is permissive: an unrecognized flag (e.g. `render --out x` when the flag
+// is `--output`/`-o`) is silently ignored instead of rejected, so the value is
+// dropped and the command falls back to its default — a silent wrong result. We
+// reject unknown flags up front with a clear message.
+
+// Global flags citty / the CLI understand on every command.
+const ALWAYS_KNOWN = new Set(["help", "h", "version", "v", "json"]);
+
+// A camelCase arg name (`gifLoop`) is passed as `--gif-loop`; a kebab name is
+// passed as-is. Accept both spellings so the validator matches citty's parsing.
+function nameVariants(name: string): string[] {
+  const kebab = name.replace(/[A-Z]/g, (c) => "-" + c.toLowerCase());
+  const camel = name.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
+  return [name, kebab, camel];
+}
+
+function knownFlags(args: ArgsDef | undefined): Set<string> {
+  const known = new Set(ALWAYS_KNOWN);
+  for (const [name, def] of Object.entries(args ?? {})) {
+    for (const v of nameVariants(name)) known.add(v);
+    const alias = (def as { alias?: string | string[] })?.alias;
+    if (typeof alias === "string") known.add(alias);
+    else if (Array.isArray(alias)) for (const a of alias) known.add(a);
+  }
+  return known;
+}
+
+// The unknown flag a single token introduces, or null when it's fine
+// (positional, flag value, `--`, or all-known). `--no-foo` -> `foo`,
+// `--flag=value` -> `flag`; a combined short group (`-ab`) checks each char.
+// `--flag`, `--flag=value`, `--no-flag` -> the bare flag name.
+function longFlagName(tok: string): string {
+  const name = tok.slice(2).split("=")[0] ?? "";
+  return name.startsWith("no-") ? name.slice(3) : name;
+}
+
+function unknownFlagIn(tok: string, known: Set<string>): string | null {
+  if (tok === "-" || !tok.startsWith("-")) return null; // positional or flag value
+  if (tok.startsWith("--")) {
+    const name = longFlagName(tok);
+    return name && !known.has(name) ? `--${name}` : null;
+  }
+  for (const ch of tok.slice(1).split("=")[0] ?? "") {
+    if (!known.has(ch)) return `-${ch}`; // combined shorts: check each char
+  }
+  return null;
+}
+
+/**
+ * Throw on the first flag in `rawArgs` not declared by `cmd` (its args + aliases
+ * + the global set). Only dash-prefixed tokens are inspected, so positionals and
+ * flag values pass through untouched. Stops at `--`.
+ */
+export function assertKnownFlags(cmd: CommandDef<ArgsDef>, rawArgs: string[]): void {
+  if (!Array.isArray(rawArgs)) return;
+  // citty types `args` as Resolvable<ArgsDef> (it may be a fn/promise); every
+  // hyperframes command uses a static object, so treat anything else as "no
+  // declared args" and skip validation rather than risk a wrong rejection.
+  const rawDef = cmd.args;
+  const args = rawDef && typeof rawDef === "object" ? (rawDef as ArgsDef) : undefined;
+  const known = knownFlags(args);
+  for (const tok of rawArgs) {
+    if (tok === "--") break;
+    const bad = unknownFlagIn(tok, known);
+    if (bad) throw new Error(`Unknown flag: ${bad}`);
+  }
+}