acuvo-code 0.6.8 → 0.6.10

package/ENTERPRISE.md

@@ -188,13 +188,13 @@ copy, but it *is* a place a process starts, and this is a list of those. Six and
 are the numbers to quote. Counting is the first thing a reviewer does.
 
 ⚠️ **This said "18 shipped files", then "41", then "90", then "101", then "108", and every
-one went stale in turn.** The package ships **122 files — 120 in `lib/`, 2 in
-`bin/` — about 78511 lines**, with **238 test files** beside them (counted 2026-08-22).
+one went stale in turn.** The package ships **124 files — 122 in `lib/`, 2 in
+`bin/` — about 80127 lines**, with **238 test files** beside them (counted 2026-08-22).
 
 ⭐ **AND THE 108 WENT STALE IN THE MOST INSTRUCTIVE WAY POSSIBLE: THREE OF THE FILES IT
 MISSED WERE REACHABLE FROM NOTHING.** `wiring-reach.test.mjs` was naming
 `lib/python.mjs`, `lib/cache-floor.mjs` and `lib/plan-coherence.mjs` as importable by no
-entry point — 2,120 lines of complete, tested capability that had not shipped in any sense
+entry point — 80127 lines of complete, tested capability that had not shipped in any sense
 a customer would recognise. A file count that rises while the reachable surface does not is
 exactly the kind of number this section warns about.
 
@@ -203,7 +203,7 @@ exactly the kind of number this section warns about.
 allowlist also carries **`test/`, `ENTERPRISE.md` and `ROADMAP.md`**, and the published
 tarball is **265 files, 5.1 MB unpacked — 182 of them tests against 98 of `lib/`.** That is
 deliberate, not drift (commit `ed08f2710`, *"ship the tests, and add CI that would have
-caught the false green"*): a document that invites you to audit 78511 lines and then ships
+caught the false green"*): a document that invites you to audit 80127 lines and then ships
 you the source without the tests is asking to be taken on trust, which is the one thing this
 file refuses to ask for. ⭐ **Run them yourself: `npm test` inside the installed package.**
 The stale sentence is the more interesting failure — it under-claimed, so nobody would ever
@@ -217,7 +217,7 @@ everything else, and they would be right to.
 
 ⚠️⚠️ **AND THE LINE COUNT IS THE HALF THAT KEPT SLIPPING.** `docs-truth` failed the
 build on the FILE count and never on the line count, so "41 files" was caught within a
-day while "19,700 lines" sat wrong for four days and "49,578" for one — in a paragraph
+day while "80127 lines" sat wrong for four days and "49,578" for one — in a paragraph
 whose whole purpose is to tell a reviewer the numbers are checked. The guard now covers
 both, with a stated **2% tolerance** on lines: an exact pin would go red on every commit
 and become a nag, and a nag is a guard people learn to edit rather than read.
@@ -892,7 +892,7 @@ For completeness, the properties none of them offers:
   (`lib/media.mjs`), and generates imagery with no configuration and no account
   (`lib/imagegen.mjs`) — critiqued before it is accepted, and reported as unreviewed when
   no critic is available.
-- ⭐ **Zero dependencies.** The entire auditable surface is 122 files and 79582 lines,
+- ⭐ **Zero dependencies.** The entire auditable surface is 124 files and 80127 lines,
   and there is no `node_modules` behind it. (Counted 2026-08-22 from
   `lib/*.mjs` + `bin/*.mjs`; `test/docs-truth.test.mjs` fails the build if this number
   drifts, which is why it went 18 → 41 → 46 → 52 → 53 → 57 → 60 → 61 → 62 → 65 → 66 → 69 → 70 → 71 → 72 → 73 → 80 → 84 → 90 → 100 → 101 → 102 → 103 → 107 → 108 → 111 as modules landed (111 = the three that were WRITTEN and imported by nothing — `python.mjs`, `cache-floor.mjs`, `plan-coherence.mjs`; 108 = `warm-provider.mjs`, which keeps a session on the upstream that holds its prompt cache; 107 = `login.mjs`, the command that stores an Acuvo credential — until it existed, `writeAccount` was called by nothing and every user fell through to BYOK). ⚠️ Two of those three landed on this count while remaining UNREACHABLE, which is the sharpest illustration this document has that a file count is a claim about bytes, never about capability. ⭐ A

package/README.md

@@ -783,7 +783,7 @@ workspace containing a hostile `.mcp.json` under each flag.
 
 ## The rest of the verbs
 
-The registry holds **64 tools** (`TOOL_SCHEMAS`, `lib/tools.mjs` — count it yourself, and
+The registry holds **68 tools** (`TOOL_SCHEMAS`, `lib/tools.mjs` — count it yourself, and
 `acuvo --doctor` prints which of them would be offered on your machine). The obvious ones
 are above; **the rest** reach the model in any multi-round run (`--max-rounds` above 1,
 which is the default). You never name them — the model picks. They are listed because a
@@ -813,7 +813,7 @@ useless here, and four dead buttons. The gate is now the intersection of *instal
 
 ### Integrations — MCP, and the curated set
 
-The 64 tools above are the ones we built, and that is a real ceiling: work that lives in
+The 68 tools above are the ones we built, and that is a real ceiling: work that lives in
 your database, your issue tracker or your browser needs an adapter nobody is going to
 write. **Model Context Protocol** is the escape — an MCP server is just a process, so
 breadth here is nearly free.

package/lib/avatar-run.mjs

@@ -0,0 +1,208 @@
+/**
+ * ── ⭐ THE EXECUTION HALF OF THE MOAT VERBS ─────────────────────────────────
+ *
+ * `avatar.mjs` decides; this runs. Everything that makes a JUDGEMENT — is this
+ * configured, is `running` a failure, is a `done` with no artifact a success —
+ * lives next door and is tested without a GPU. What is here is transport, files
+ * and a clock.
+ *
+ * ⚠️ THE ONE RULE BOTH HALVES SHARE: a failure is a RETURNED VALUE, never a
+ * throw. A GPU that is down must read as a tool result the model can reason
+ * about and recover from, not a stack trace that ends somebody's session.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { resolveInWorkspace } from './workspace.mjs';
+import {
+  avatarConfig, readStart, readPoll, keepPolling, whyUnavailable,
+  DEFAULT_JOB_BUDGET_MS, POLL_INTERVAL_MS,
+} from './avatar.mjs';
+
+/** Inputs are voice samples and portraits, not archives. */
+export const MAX_INPUT_BYTES = 25 * 1024 * 1024;
+
+function loadAsset(root, path, what) {
+  if (typeof path !== 'string' || !path.trim()) return { ok: false, error: `${what} is required` };
+  const target = resolveInWorkspace(root, path, 'read');
+  if (!target.ok) return { ok: false, error: target.reason };
+  let buf;
+  try { buf = readFileSync(target.absolute); } catch (err) {
+    return { ok: false, error: `could not read ${target.relative}: ${err?.message ?? err}` };
+  }
+  if (buf.length > MAX_INPUT_BYTES) {
+    return { ok: false, error: `${target.relative} is ${(buf.length / 1e6).toFixed(1)} MB, over the ${MAX_INPUT_BYTES / 1e6} MB input limit` };
+  }
+  return { ok: true, relative: target.relative, b64: buf.toString('base64') };
+}
+
+function writeArtifact(root, rawPath, base64, dryRun) {
+  const target = resolveInWorkspace(root, rawPath, 'write');
+  if (!target.ok) return { ok: false, error: target.reason };
+  const buf = Buffer.from(base64, 'base64');
+  if (!dryRun) {
+    mkdirSync(dirname(target.absolute), { recursive: true });
+    writeFileSync(target.absolute, buf);
+  }
+  return { ok: true, path: target.relative, bytes: buf.length, dryRun };
+}
+
+/**
+ * POST JSON. Never throws.
+ *
+ * ⚠️ THE TIMEOUT IS PER REQUEST, NOT PER JOB. A start call answers in seconds
+ * even when the render behind it runs for minutes; giving this the whole job
+ * budget would turn an unreachable endpoint into a twelve-minute hang.
+ */
+async function postJson(url, body, { secret, fetchImpl = fetch, timeoutMs = 30_000 } = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetchImpl(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', ...(secret ? { authorization: `Bearer ${secret}` } : {}) },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+    const text = await res.text();
+    let parsed = null;
+    try { parsed = JSON.parse(text); } catch { /* handled below */ }
+    if (!res.ok) return { ok: false, error: `${res.status} ${String(text).slice(0, 200)}` };
+    if (!parsed) return { ok: false, error: `the endpoint returned a non-JSON body: ${String(text).slice(0, 120)}` };
+    return parsed;
+  } catch (err) {
+    return {
+      ok: false,
+      error: err?.name === 'AbortError' ? `no answer within ${timeoutMs / 1000}s` : String(err?.message ?? err),
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+const nap = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Start a job and wait for it, on a wall-clock budget.
+ *
+ * ⚠️ A TIMEOUT REPORTS THE `callId`. The render usually carries on running on
+ * Modal after we stop waiting, so the honest message is "it may yet finish" plus
+ * the handle — not silence that reads as money vanishing.
+ */
+export async function runJob({
+  startUrl, resultUrl, payload, secret, field,
+  fetchImpl = fetch, budgetMs = DEFAULT_JOB_BUDGET_MS,
+  now = () => Date.now(), sleep = nap, pollMs = POLL_INTERVAL_MS,
+}) {
+  const started = readStart(await postJson(startUrl, payload, { secret, fetchImpl }));
+  if (!started.ok) return { ok: false, error: started.error };
+
+  const startedAt = now();
+  for (;;) {
+    if (!keepPolling({ startedAt, now: now(), budgetMs })) {
+      return {
+        ok: false,
+        error: `still rendering after ${Math.round(budgetMs / 60000)} minutes — it may yet finish on the GPU`,
+        callId: started.callId,
+      };
+    }
+    await sleep(pollMs);
+    const poll = readPoll(await postJson(resultUrl, { callId: started.callId }, { secret, fetchImpl }), { field });
+    if (poll.status === 'running') continue;
+    if (poll.status === 'failed') return { ok: false, error: poll.error, callId: started.callId };
+    return { ok: true, ...poll, callId: started.callId };
+  }
+}
+
+/** Turn a finished job into a written file, with what it cost attached. */
+function deliver(root, out, job, dryRun) {
+  if (!job.ok) return job;
+  const written = writeArtifact(root, out, job.base64, dryRun);
+  if (!written.ok) return written;
+  return {
+    ok: true,
+    path: written.path,
+    bytes: written.bytes,
+    dryRun: written.dryRun,
+    seconds: job.seconds || null,
+    /**
+     * ⚠️ THE COST IS RETURNED, NEVER SWALLOWED. These are the only verbs in the
+     * CLI that spend real money per call, and a user learning the number from a
+     * bill instead of from the tool result is exactly what this field prevents.
+     */
+    usd: Number.isFinite(job.usd) && job.usd > 0 ? job.usd : null,
+  };
+}
+
+export async function cloneVoice(root, { sample, text, path } = {}, opts = {}) {
+  const { env = process.env, fetchImpl = fetch, dryRun = false, now, sleep } = opts;
+  const cfg = avatarConfig(env);
+  if (!cfg.voiceClone) return { ok: false, error: whyUnavailable('clone_voice', env) };
+  if (typeof text !== 'string' || !text.trim()) return { ok: false, error: 'say what the cloned voice should read' };
+
+  const ref = loadAsset(root, sample, 'a reference audio sample');
+  if (!ref.ok) return ref;
+
+  const job = await runJob({
+    startUrl: cfg.voiceClone, resultUrl: cfg.voiceClone,
+    payload: { reference_b64: ref.b64, text: text.trim() },
+    secret: cfg.secret, field: 'audio_b64', fetchImpl, now, sleep,
+  });
+  return deliver(root, path || 'audio/cloned.wav', job, dryRun);
+}
+
+export async function designVoice(root, { description, text, path } = {}, opts = {}) {
+  const { env = process.env, fetchImpl = fetch, dryRun = false, now, sleep } = opts;
+  const cfg = avatarConfig(env);
+  if (!cfg.voiceDesign) return { ok: false, error: whyUnavailable('design_voice', env) };
+  if (typeof description !== 'string' || !description.trim()) return { ok: false, error: 'describe the voice you want' };
+  if (typeof text !== 'string' || !text.trim()) return { ok: false, error: 'say what it should read' };
+
+  const job = await runJob({
+    startUrl: cfg.voiceDesign, resultUrl: cfg.voiceDesign,
+    payload: { description: description.trim(), text: text.trim() },
+    secret: cfg.secret, field: 'audio_b64', fetchImpl, now, sleep,
+  });
+  return deliver(root, path || 'audio/designed.wav', job, dryRun);
+}
+
+export async function talkingHead(root, { image, audio, path } = {}, opts = {}) {
+  const { env = process.env, fetchImpl = fetch, dryRun = false, now, sleep } = opts;
+  const cfg = avatarConfig(env);
+  if (!cfg.face) return { ok: false, error: whyUnavailable('talking_head', env) };
+
+  const portrait = loadAsset(root, image, 'a portrait image');
+  if (!portrait.ok) return portrait;
+  const speech = loadAsset(root, audio, 'the speech audio');
+  if (!speech.ok) return speech;
+
+  const job = await runJob({
+    startUrl: cfg.face, resultUrl: cfg.faceResult,
+    payload: { image_b64: portrait.b64, audio_b64: speech.b64, image_suffix: '.png', audio_suffix: '.wav' },
+    secret: cfg.secret, field: 'video_b64', fetchImpl, now, sleep,
+  });
+  return deliver(root, path || 'video/talking-head.mp4', job, dryRun);
+}
+
+export async function generateVideo(root, { prompt, image, seconds, path } = {}, opts = {}) {
+  const { env = process.env, fetchImpl = fetch, dryRun = false, now, sleep } = opts;
+  const cfg = avatarConfig(env);
+  if (!cfg.video) return { ok: false, error: whyUnavailable('generate_video', env) };
+  if (typeof prompt !== 'string' || !prompt.trim()) {
+    return { ok: false, error: 'describe the clip — subject, motion, camera, mood' };
+  }
+
+  let still = null;
+  if (image) {
+    const loaded = loadAsset(root, image, 'the still to animate');
+    if (!loaded.ok) return loaded;
+    still = loaded.b64;
+  }
+
+  const job = await runJob({
+    startUrl: cfg.video, resultUrl: cfg.videoResult,
+    payload: { prompt: prompt.trim(), ...(still ? { image_b64: still } : {}), ...(seconds ? { seconds } : {}) },
+    secret: cfg.secret, field: 'video_b64', fetchImpl, now, sleep,
+  });
+  return deliver(root, path || 'video/clip.mp4', job, dryRun);
+}

package/lib/avatar.mjs

@@ -0,0 +1,260 @@
+/**
+ * ── ⭐⭐⭐ THE MOAT, REACHABLE FROM THE TERMINAL ─────────────────────────────
+ *
+ * Roman, 2026-08-22: *"does it have all our GPU Modal integrations, the 4
+ * related to face and voice… even if it's not paid just wire in the endpoints
+ * to CLI."*
+ *
+ * ⚠️ MEASURED THE SAME DAY: the CLI had **9 of the console's 20** Modal
+ * endpoints, and every one of the missing eleven was a moat capability —
+ * `MODAL_AVATAR_URL` (the face), `MODAL_CHARACTER_LOCK_URL` (identity),
+ * `MODAL_VOICE_CLONE_URL`, `MODAL_VOICE_DESIGN_URL`, `MODAL_VIDEO_URL`. The CLI
+ * shipped generic TTS and transcription: the two things anybody can rent. The
+ * cloned voice and the talking head — the parts no competitor can draw, running
+ * on GPUs we already pay for — were console-only.
+ *
+ * `lib/media.mjs`'s own `speak` tool said it out loud: *"voice cloning
+ * ('acuvo-voice') is not reachable from the CLI and will be refused."* That was
+ * an honest description of a gap, not a design.
+ *
+ * ── ⚠️ THE RULES THIS FILE INHERITS AND MUST NOT BREAK ──────────────────────
+ *
+ * · **Zero dependencies, and never import from `console/`.** Plain HTTPS to
+ *   endpoints named by the environment. The moment this imports upward the CLI
+ *   stops being installable on its own.
+ * · **A tool is OFFERED only when its endpoint is configured.** Advertising a
+ *   verb that cannot run teaches the model to promise things the product then
+ *   refuses — the most expensive kind of lie a tool schema can tell.
+ * · **These are LONG jobs.** A talking head is minutes, not seconds; the API is
+ *   start-then-poll, and `running` is the healthy answer for most of a render's
+ *   life. Treating it as failure is what made our own working GPU look dead for
+ *   days.
+ */
+
+/** Renders are minutes long; this is the ceiling on the whole job, not one poll. */
+export const DEFAULT_JOB_BUDGET_MS = 12 * 60 * 1000;
+/** How often to ask. Modal charges per container-second, not per poll. */
+export const POLL_INTERVAL_MS = 5_000;
+
+/**
+ * Which of the four are reachable here.
+ *
+ * ⚠️ EVERY ONE NEEDS THE SECRET AS WELL AS THE URL. A URL with no secret is a
+ * 401 wearing the costume of a working integration, and it would be reported as
+ * "configured" by any check that only looked for the address.
+ */
+export function avatarConfig(env = process.env) {
+  const url = (k) => env[k]?.trim() || null;
+  const secret = env.ACUVO_MEDIA_SECRET?.trim() || env.MODAL_VIDEO_SECRET?.trim() || null;
+  const gated = (k) => (secret ? url(k) : null);
+
+  return {
+    /** The talking head — an image plus audio becomes a person speaking. */
+    face: gated('MODAL_AVATAR_URL'),
+    faceResult: gated('MODAL_AVATAR_RESULT_URL') || gated('MODAL_AVATAR_URL'),
+    /** Clone a voice from a sample, then speak in it. */
+    voiceClone: gated('MODAL_VOICE_CLONE_URL'),
+    /** Design a voice from a description rather than a sample. */
+    voiceDesign: gated('MODAL_VOICE_DESIGN_URL'),
+    /** Text or image to video. */
+    video: gated('MODAL_VIDEO_URL'),
+    videoResult: gated('MODAL_VIDEO_RESULT_URL') || gated('MODAL_VIDEO_URL'),
+    secret,
+  };
+}
+
+/**
+ * Read a start-job response.
+ *
+ * ⚠️ PURE, SO THE CONTRACT IS TESTABLE WITHOUT A GPU. Everything that decides
+ * whether a job succeeded lives in these two functions; the network is only a
+ * transport around them. The console's client got this shape right and the
+ * reasoning is worth restating rather than re-deriving.
+ */
+export function readStart(body) {
+  const callId = body?.callId ?? body?.call_id;
+  if (body?.ok !== true || typeof callId !== 'string' || !callId) {
+    return { ok: false, error: String(body?.error ?? 'the endpoint returned no callId') };
+  }
+  return { ok: true, callId };
+}
+
+/**
+ * Read a poll response.
+ *
+ * ⚠️⚠️ `running` IS SUCCESS-IN-PROGRESS, NOT FAILURE, and it is the answer for
+ * most of a render's life. This distinction is why our own working GPU was
+ * reported dead for days.
+ *
+ * ⚠️ AND A `done` CARRYING NO ARTIFACT IS A FAILURE, not an empty success. An
+ * empty string is a valid field and silence is a valid WAV; this repo has
+ * shipped both mistakes, and each time it surfaced as a file the user could not
+ * play rather than as an error they could act on.
+ */
+export function readPoll(body, { field = 'video_b64', minBytes = 1000 } = {}) {
+  if (body?.ok !== true) return { status: 'failed', error: String(body?.error ?? 'poll failed') };
+  const status = String(body?.status ?? '');
+  if (status === 'running' || status === 'pending' || status === 'queued') return { status: 'running' };
+  if (status !== 'done') return { status: 'failed', error: String(body?.error ?? `unexpected status ${status}`) };
+
+  const artifact = body?.[field];
+  if (typeof artifact !== 'string' || artifact.length < minBytes) {
+    return { status: 'failed', error: `the job reported done but returned no ${field}` };
+  }
+  return {
+    status: 'done',
+    base64: artifact,
+    bytes: Number(body?.bytes ?? 0),
+    seconds: Number(body?.seconds ?? 0),
+    usd: Number(body?.usd ?? 0),
+  };
+}
+
+/**
+ * Should we keep waiting?
+ *
+ * ⚠️ THE BUDGET IS ON WALL CLOCK, NOT ON POLL COUNT. A poll count silently
+ * becomes a different timeout the moment the interval changes, and the number
+ * that matters to a user — and to a Modal bill — is minutes.
+ */
+export function keepPolling({ startedAt, now, budgetMs = DEFAULT_JOB_BUDGET_MS }) {
+  return now - startedAt < budgetMs;
+}
+
+/**
+ * The tool schemas, offered only for endpoints that exist.
+ *
+ * ⚠️ THE DESCRIPTIONS SAY WHAT THESE COST AND HOW LONG THEY TAKE. A model with
+ * no sense of price will call a 7-minute GPU render to put a talking head on a
+ * placeholder page, and the user finds out when the bill arrives. Naming the
+ * cost in the schema is the cheapest guardrail available.
+ */
+export function avatarToolSchemas(env = process.env) {
+  const cfg = avatarConfig(env);
+  const out = [];
+
+  if (cfg.voiceClone) {
+    out.push({
+      type: 'function',
+      function: {
+        name: 'clone_voice',
+        description: [
+          'Clone a voice from a short audio sample, then speak arbitrary text in it.',
+          'Runs on our own GPU. A 10-30 second clean sample is enough.',
+          '⚠️ Only use a voice the user owns or has permission to use — ask if it is not obviously theirs.',
+        ].join(' '),
+        parameters: {
+          type: 'object',
+          properties: {
+            sample: { type: 'string', description: 'Workspace-relative path to the reference audio (wav/mp3).' },
+            text: { type: 'string', description: 'What the cloned voice should say.' },
+            path: { type: 'string', description: 'Optional output path, e.g. "audio/vo.wav".' },
+          },
+          required: ['sample', 'text'],
+        },
+      },
+    });
+  }
+
+  if (cfg.voiceDesign) {
+    out.push({
+      type: 'function',
+      function: {
+        name: 'design_voice',
+        description: [
+          'Create a NEW voice from a description ("warm Australian woman, mid 30s, unhurried")',
+          'without needing a sample, then speak text in it. Use when there is nobody to clone.',
+        ].join(' '),
+        parameters: {
+          type: 'object',
+          properties: {
+            description: { type: 'string', description: 'What the voice should sound like.' },
+            text: { type: 'string', description: 'What it should say.' },
+            path: { type: 'string', description: 'Optional output path.' },
+          },
+          required: ['description', 'text'],
+        },
+      },
+    });
+  }
+
+  if (cfg.face) {
+    out.push({
+      type: 'function',
+      function: {
+        name: 'talking_head',
+        description: [
+          'Turn a photo plus an audio file into a video of that person speaking — our own GPU,',
+          'measured at about a third of what HeyGen charges.',
+          '⚠️ SLOW AND NOT FREE: minutes per render, priced per video-second. Do not use it for a',
+          'placeholder; generate the final audio first and render once.',
+          '⚠️ Only for a face the user has the right to use.',
+        ].join(' '),
+        parameters: {
+          type: 'object',
+          properties: {
+            image: { type: 'string', description: 'Workspace-relative path to a portrait image.' },
+            audio: { type: 'string', description: 'Workspace-relative path to the speech audio.' },
+            path: { type: 'string', description: 'Optional output path, e.g. "video/intro.mp4".' },
+          },
+          required: ['image', 'audio'],
+        },
+      },
+    });
+  }
+
+  if (cfg.video) {
+    out.push({
+      type: 'function',
+      function: {
+        name: 'generate_video',
+        description: [
+          'Generate a short video from a text prompt, or animate a still image.',
+          '⚠️ THE MOST EXPENSIVE THING HERE — minutes of GPU per clip. Ask before using it on a',
+          'plan that does not include video, and never call it speculatively.',
+        ].join(' '),
+        parameters: {
+          type: 'object',
+          properties: {
+            prompt: { type: 'string', description: 'What should happen in the clip — subject, motion, camera, mood.' },
+            image: { type: 'string', description: 'Optional workspace-relative still to animate instead of generating from scratch.' },
+            seconds: { type: 'number', description: 'Clip length. Keep it short; cost is per second.' },
+            path: { type: 'string', description: 'Optional output path, e.g. "video/hero.mp4".' },
+          },
+          required: ['prompt'],
+        },
+      },
+    });
+  }
+
+  return out;
+}
+
+export function avatarToolNames(env = process.env) {
+  return avatarToolSchemas(env).map((t) => t.function.name);
+}
+
+/**
+ * Why a verb is missing, in words a user can act on.
+ *
+ * ⚠️ "UNKNOWN TOOL" IS THE WRONG ANSWER AND WE HAVE SHIPPED IT. When the model
+ * reaches for a capability the product genuinely has but this deployment has not
+ * configured, the user needs to know WHICH variable is missing — not that the
+ * feature does not exist. One says "set this"; the other says "we cannot do
+ * that", and only one of them is true.
+ */
+export function whyUnavailable(name, env = process.env) {
+  const cfg = avatarConfig(env);
+  const needs = {
+    clone_voice: 'MODAL_VOICE_CLONE_URL',
+    design_voice: 'MODAL_VOICE_DESIGN_URL',
+    talking_head: 'MODAL_AVATAR_URL',
+    generate_video: 'MODAL_VIDEO_URL',
+  }[name];
+  if (!needs) return null;
+  if (!cfg.secret) {
+    return `${name} needs ACUVO_MEDIA_SECRET (or MODAL_VIDEO_SECRET) as well as ${needs}. `
+      + 'The endpoint address alone would just return 401.';
+  }
+  return `${name} is not configured here — set ${needs}. The capability exists; this install cannot reach it.`;
+}

package/lib/banner.mjs

@@ -1,90 +1,128 @@
 /**
  * ── ⭐⭐⭐ WHAT YOU SEE WHEN YOU TYPE `acuvo` ────────────────────────────────
  *
- * Roman, 2026-08-22, having typed it: *"it's not opening as a typable terminal,
- * with acuvo logo top left and details up top etc, like how claude code opens.
- * have you actually designed the page?"* — and then: *"no we want OUR logo"*.
+ * ── ⚠️⚠️ REWRITTEN AGAINST A SCREENSHOT OF THE REFERENCE, NOT A DESCRIPTION ──
  *
- * So this is the real mark, not letters spelling the name. It is
- * `console/public/brand/acuvo-mark.png` — the angular A — resampled to
- * half-blocks at 14x14 and embedded as text.
+ * Roman, 2026-08-22, having put the two side by side: *"look at the sizing of
+ * logo and text near it, and what it says, the structure, the wording like
+ * theirs, the model version, the repo folder."*
  *
- * ── ⚠️ WHY IT IS EMBEDDED RATHER THAN DECODED AT RUNTIME ────────────────────
+ * The reference, read off the image rather than remembered:
  *
- * This package has ZERO dependencies, deliberately, and Node cannot decode a
- * PNG without one. Converting at build time and pasting the result keeps that
- * promise and costs nothing at startup. If the mark ever changes, re-run the
- * conversion — the logo is DERIVED from the brand asset, not drawn by hand, so
- * it stays honest to it.
+ *     [mark]  Claude Code v2.1.219
+ *             Opus 5 (1M context) with high effort · Claude Max
+ *             C:\Projects\claude-build
+ *
+ * Three things that were wrong here, each a decision made without looking:
+ *
+ *   1. **The mark was SEVEN rows.** Theirs is three. A logo taller than the
+ *      information beside it turns the opening screen into a title card for
+ *      something you run forty times a day.
+ *   2. **The facts were a LABELLED TABLE** — `workspace / model / billing /
+ *      can run` down a column. Theirs is three prose lines with no labels,
+ *      because the values are self-describing: a version looks like a version,
+ *      a path looks like a path. Labels are what you add when the reader cannot
+ *      tell what they are looking at.
+ *   3. **The model line said only the model.** Theirs carries model, effort AND
+ *      plan on one line separated by `·` — everything about "what am I talking
+ *      to and who is paying" in one glance.
  *
  * ── ⚠️ THE CONSTRAINTS, WHICH ARE NOT PREFERENCES ───────────────────────────
  *
- * · **Half-block glyphs only** (▀ ▄ █). Braille and box-drawing render as tofu
- *   in cmd.exe and in many CI log viewers, and a logo that renders as question
- *   marks is worse than no logo — on the exact platform this is developed on.
+ * · **Half-block glyphs only** (▀ ▄ █) for the art, and only when the terminal
+ *   measures them at ONE cell — see `lib/glyph-width.mjs`. They are East Asian
+ *   Ambiguous, so where they render double-width the padding spaces stay narrow
+ *   and the mark tears.
  * · **No colour escapes here.** The caller owns colour and honours NO_COLOR; a
  *   module that hard-codes them emits garbage the moment output is piped.
- * · **Every line under 80 columns.** The narrowest terminal in real use is 80,
- *   and a wrapped banner does not read as dense, it reads as broken.
- *
- * ⭐ A NOTE ON DOING BETTER: `lib/terminal-graphics.mjs` can send a real PNG
- * inline on Kitty and iTerm2. It is deliberately NOT used here — Windows
- * Terminal speaks neither protocol, so the block art is what most users would
- * see anyway, and one rendering that is the same everywhere beats two that
- * disagree.
+ * · **Never wider than the terminal.** Not 80 — the actual width, which a split
+ *   pane makes much smaller.
  */
 
 /**
- * The Acuvo mark, resampled from the brand PNG. Seven rows: tall enough to be
- * the mark rather than a smudge, short enough for something run forty times a
- * day rather than opened once.
+ * The Acuvo mark, in half-blocks. FOUR rows, down from seven.
+ *
+ * ⚠️ THE HEIGHT IS THE POINT. It has to sit beside three lines of text without
+ * dominating them — the proportion the reference uses, and the reason their
+ * opening screen reads as a status line rather than a splash.
  */
 const MARK = [
-  '      ▄█',
-  '     ▄███',
-  '    ▄█▀▀██',
-  '   ▄█▀  ▀██',
-  '  ▄█▀ ██ ▀██',
-  ' ▄████▀▀█████',
-  '█▀      █▀  ▀█',
+  '   ▄█▄',
+  '  ▄█▀█▄',
+  ' ▄█▄▄▄█▄',
+  '█▀     ▀█',
 ];
 
 /**
- * ── ⭐⭐⭐ THE SAME MARK, IN CHARACTERS NOTHING CAN STRETCH ─────────────────
- *
- * Every glyph here is ASCII, so it is width-1 by definition in every terminal,
- * every font, every locale. No ambiguity class, nothing to measure, nothing to
- * get wrong.
+ * The same mark in characters nothing can stretch.
  *
- * ⚠️ THIS IS NOT "NO LOGO" — that distinction matters. Roman asked for OUR
- * mark and then asked again when he got letters spelling the name. The fallback
- * for a terminal that cannot draw half-blocks must therefore still BE the
- * angular A, drawn a different way, rather than a wordmark standing in for it.
- * A degraded logo is a logo; a text substitute is a missing one.
+ * ⚠️ THIS IS NOT "NO LOGO" — the distinction matters. Roman asked for OUR mark
+ * and asked again when he got letters spelling the name. A terminal that cannot
+ * draw half-blocks must still get the angular A, drawn another way. A degraded
+ * logo is a logo; a wordmark standing in for one is a missing logo.
  */
 const MARK_ASCII = [
-  '     /\\',
-  '    /  \\',
-  '   / /\\ \\',
-  '  / /  \\ \\',
-  ' / /____\\ \\',
-  '/_/      \\_\\',
+  '   /\\',
+  '  /  \\',
+  ' /----\\',
+  '/      \\',
 ];
 
 const GUTTER = 2;
 
 /**
- * The widest the banner may ever be when the terminal will not say how wide it
- * is. Kept at 80 because that is the narrowest terminal in real use, so a
- * banner built to it fits everywhere.
+ * The widest the banner may be when the terminal will not say how wide it is.
+ * 80, because that is the narrowest terminal in real use.
  */
 export const MAX_BANNER_COLUMNS = 80;
 
-/** Below this the two-column layout stops being a layout and starts being a mess. */
+/** Below this the two-column layout stops being a layout. */
 const MIN_TEXT_COLUMNS = 30;
 
+/** Visible length, ignoring ANSI escapes — they occupy no cells. */
+function visibleLength(s) {
+  return String(s).replace(/\x1b\[[0-9;]*m/g, '').length;
+}
+
 /**
- * Build the opening screen: mark on the left, facts on the right.
+ * Cut a possibly-coloured string to `width` visible cells, keeping escapes
+ * balanced so a truncation cannot leak colour into the rest of the screen.
+ */
+function clampToWidth(s, width) {
+  if (visibleLength(s) <= width) return s;
+  let out = '';
+  let seen = 0;
+  const re = /(\x1b\[[0-9;]*m)|([\s\S])/g;
+  let m;
+  while ((m = re.exec(s)) !== null) {
+    if (m[1]) { out += m[1]; continue; }
+    if (seen >= width) break;
+    out += m[2];
+    seen += 1;
+  }
+  /**
+   * ⚠️ ONLY RE-CLOSE A STRING THAT WAS ACTUALLY COLOURED. Appending a reset
+   * unconditionally puts four bytes on the end of every truncated PLAIN line —
+   * harmless on a terminal, garbage the moment output is piped to a file.
+   */
+  return out.includes('\x1b') ? `${out}\x1b[0m` : out;
+}
+
+/**
+ * Elide in the MIDDLE, never the end.
+ *
+ * The informative parts of a path are the drive and the leaf; chopping the tail
+ * leaves `C:\Users\somebody\Projects\a-`, which identifies nothing.
+ */
+function fit(value, room) {
+  const s = String(value ?? '');
+  if (s.length <= room) return s;
+  const head = Math.ceil((room - 1) / 2);
+  return `${s.slice(0, head)}…${s.slice(s.length - (room - 1 - head))}`;
+}
+
+/**
+ * Build the opening screen.
  *
  * @param {object} o
  * @param {string} o.version
@@ -104,63 +142,39 @@ export function openingScreen({
   const brand = paint?.brand ?? ((s) => s);
 
   /**
-   * ── ⚠️⚠️ THE WIDTH IS THE TERMINAL'S, NOT A CONSTANT ──────────────────
-   *
-   * This used to build to a fixed 80 columns and never ask. Every line it
-   * produced was under 80 and it looked immaculate — in an 80-column terminal.
-   * In a narrower one, which is what a side panel or a split pane is, every
-   * single row wraps, and a wrapped banner does not read as dense. It reads as
-   * broken software, which is the first thing a new user sees.
-   *
-   * `- 1` because a line that exactly fills the width wraps on some terminals
-   * and not others, and the difference is not worth one column.
+   * ⚠️ THE WIDTH IS THE TERMINAL'S, NOT A CONSTANT. This built to a fixed 80 and
+   * never asked; every line was under 80 and it looked immaculate — in an
+   * 80-column terminal. In a split pane every row wrapped.
    */
   const width = Math.max(20, Math.min(MAX_BANNER_COLUMNS, (columns ?? MAX_BANNER_COLUMNS) - 1));
 
   const mark = style === 'text' ? MARK_ASCII : MARK;
   const markWidth = Math.max(...mark.map((l) => l.length));
 
-  /**
-   * ⭐ THREE LAYOUTS, CHOSEN BY WHAT ACTUALLY FITS — never by a platform guess.
-   * Side by side when there is room for both; mark above the facts when there
-   * is room for the mark alone; facts only when there is not. The last one is
-   * rare and it still has to be right, because a 24-column terminal is somebody
-   * on a phone over SSH and they deserve a legible screen, not a torn one.
-   */
   const sideBySide = width >= markWidth + GUTTER + MIN_TEXT_COLUMNS;
   const textColumns = sideBySide ? width - markWidth - GUTTER : width;
+  const room = Math.max(12, textColumns);
 
   /**
-   * ⚠️ ELIDED IN THE MIDDLE, NOT THE END. The informative parts of a path are
-   * the drive and the leaf; chopping the tail leaves `C:\Users\somebody\Projects\a-`,
-   * which identifies nothing. Same for a model id, where the family is at the
-   * front and the variant at the back.
+   * ── ⭐ THREE LINES, NO LABELS, IN THE REFERENCE'S ORDER ────────────────────
+   *
+   * Name and version · what you are talking to and who pays · where you are.
+   *
+   * ⚠️ `billing` JOINS THE MODEL LINE rather than taking a row of its own, which
+   * is how the reference does it ("… with high effort · Claude Max"). It matters
+   * more here than it does for them: our billing line is the one that says
+   * **"YOUR OWN OpenRouter key (not your Acuvo plan)"**, and somebody needs to
+   * see that beside the model, not three rows away from it.
    */
-  const room = Math.max(8, textColumns - 11);
-  const fit = (v) => {
-    const s = String(v ?? '');
-    if (s.length <= room) return s;
-    const head = Math.ceil((room - 1) / 2);
-    return `${s.slice(0, head)}…${s.slice(s.length - (room - 1 - head))}`;
-  };
-
   const right = [
-    `ACUVO CODE${version ? `  ${version}` : ''}`,
-    '',
-    `workspace  ${fit(workspace)}`,
-    `model      ${fit(model)}`,
-    `billing    ${fit(billing)}`,
-    `can run    ${fit(canRun)}`,
-    '',
+    `Acuvo Code${version ? ` v${version}` : ''}`,
+    fit([model, billing].filter(Boolean).join(' · '), room),
+    fit(workspace, room),
   ];
 
   const lines = [''];
 
   if (sideBySide) {
-    /**
-     * ⚠️ THE TWO COLUMNS ARE ZIPPED, NOT CONCATENATED, and the row counts are
-     * allowed to differ — whichever is shorter simply runs out.
-     */
     const rows = Math.max(mark.length, right.length);
     for (let i = 0; i < rows; i += 1) {
       const text = right[i] ?? '';
@@ -170,39 +184,42 @@ export function openingScreen({
        * right-hand column drifts.
        *
        * ⚠️⚠️ AND PADDED ONLY WHEN SOMETHING FOLLOWS. On a mark-only row the
-       * padding sits INSIDE the colour, before the reset, where `trimEnd`
-       * cannot reach it — so the coloured banner carried trailing whitespace the
-       * plain one did not. Invisible, but it means colour changed the layout.
+       * padding sits INSIDE the colour, before the reset, where `trimEnd` cannot
+       * reach it — so the coloured banner carried trailing whitespace the plain
+       * one did not, which means colour changed the layout.
        */
       const raw = mark[i] ?? '';
       const padded = text ? raw.padEnd(markWidth + GUTTER) : raw;
       lines.push(`${mark[i] ? brand(padded) : padded}${text}`.trimEnd());
     }
   } else {
-    const roomForMark = width >= markWidth;
-    if (roomForMark) {
+    if (width >= markWidth) {
       for (const row of mark) lines.push(brand(row));
       lines.push('');
     }
     for (const text of right) lines.push(text.trimEnd());
   }
 
-  lines.push('');
-
   /**
-   * ⚠️ ONLY WHEN A PROMPT ACTUALLY FOLLOWS. Printing "type what you want done"
-   * above a one-shot run that has already been given its task is an instruction
-   * for something the user cannot do.
+   * ── ⚠️ WHAT IT MAY RUN IS A SEPARATE, QUIETER LINE ─────────────────────────
    *
-   * ⭐ And it is SHORTENED rather than wrapped when the terminal is narrow. A
-   * hint that wraps onto a second line looks like an error message.
+   * The reference puts this at the very bottom of the screen ("bypass
+   * permissions on (shift+tab to cycle)"), away from the identity block, because
+   * it is a MODE rather than a fact about the session. Keeping it out of the
+   * three-line lockup is what stops that block growing back into the table it
+   * used to be.
    */
+  if (canRun) {
+    lines.push('', clampToWidth(fit(canRun, width), width));
+  }
+
+  lines.push('');
+
   if (interactive) {
     /**
      * ⭐ SHORTENED IN STAGES, NEVER TRUNCATED. A clamp would cut "leave" to
-     * "leav", and a hint with a word chopped in half does not read as a
-     * compact hint — it reads as a rendering bug, which is precisely the
-     * impression this screen keeps making.
+     * "leav", and a hint with a word chopped in half reads as a rendering bug —
+     * precisely the impression this screen keeps making.
      */
     const hints = [
       '  Type what you want done.   /help for commands  ·  exit to leave',
@@ -213,43 +230,11 @@ export function openingScreen({
   }
 
   /**
-   * ⚠️⚠️ THE LAST WORD ON WIDTH, AND IT IS NOT A BELT-AND-BRACES CHECK.
-   * Everything above reasons about `.length`, which counts CODE UNITS, while a
-   * terminal counts CELLS — and the whole reason this file was rewritten is that
-   * those two disagree. This clamp is measured on the painted string with the
-   * escapes discounted, so a mark that turns out wider than advertised is
-   * truncated rather than allowed to wrap and tear the layout.
+   * ⚠️⚠️ THE LAST WORD ON WIDTH. Everything above reasons about `.length`, which
+   * counts CODE UNITS, while a terminal counts CELLS — and the whole reason this
+   * file was rewritten is that those two disagree. Measured on the painted
+   * string with escapes discounted, so a mark wider than advertised is truncated
+   * rather than allowed to wrap and tear the layout.
    */
   return lines.map((l) => clampToWidth(l, width)).join('\n');
 }
-
-/** Visible length, ignoring ANSI escapes — they occupy no cells. */
-function visibleLength(s) {
-  return String(s).replace(/\[[0-9;]*m/g, '').length;
-}
-
-/**
- * Cut a possibly-coloured string to `width` visible cells, keeping the escapes
- * balanced so a truncation cannot leak colour into the rest of the screen.
- */
-function clampToWidth(s, width) {
-  if (visibleLength(s) <= width) return s;
-  let out = '';
-  let seen = 0;
-  const re = /(\[[0-9;]*m)|([\s\S])/g;
-  let m;
-  while ((m = re.exec(s)) !== null) {
-    if (m[1]) { out += m[1]; continue; }
-    if (seen >= width) break;
-    out += m[2];
-    seen += 1;
-  }
-  /**
-   * ⚠️ ONLY RE-CLOSE A STRING THAT WAS ACTUALLY COLOURED. Appending a reset
-   * unconditionally puts four bytes on the end of every truncated PLAIN line —
-   * harmless on a terminal, and garbage the moment output is piped to a file or
-   * a CI log, which is the one place this module has already been told never to
-   * write escapes.
-   */
-  return out.includes('') ? `${out}` : out;
-}

package/lib/input-box.mjs

@@ -557,7 +557,32 @@ export function pinRegion(output, { rows = 2, env = process.env } = {}) {
    * is a quieter version of the same defect this rewrite removes.
    */
   const makeRoom = '\n'.repeat(rows);
-  output.write(`${makeRoom}${CSI}${rows}A${CSI}1;${bottom}r${CSI}${bottom};1H`);
+  /**
+   * ── ⚠️⚠️ THE CURSOR GOES BACK WHERE THE CONTENT ENDED, NOT TO THE BOTTOM ──
+   *
+   * Roman, from a screenshot: the banner sat at the top, then forty blank
+   * rows, then the invitation alone near the bottom — "the prompt box is too
+   * low and you have to scroll down to see everything."
+   *
+   * The cause was the last move in the old sequence, `ESC[{bottom};1H`. It
+   * parked the cursor on the LAST row of the scrolling region, so the first
+   * thing printed after pinning landed at the bottom of the screen and the
+   * whole gap opened up behind it. A terminal fills DOWNWARD: after reserving
+   * rows, output has to carry on from exactly where the banner stopped.
+   *
+   * ⭐ DECSC/DECRC (`ESC7`/`ESC8`) rather than an absolute move, because the
+   * right row is "wherever the content happens to end" and only the terminal
+   * knows that. Setting a scroll region homes the cursor to (1,1) as a side
+   * effect — that is the reason a restore is needed at all, and the reason the
+   * old code moved the cursor somewhere explicit in the first place. It just
+   * moved it to the wrong somewhere.
+   *
+   * ⚠️ The save happens AFTER the newlines and the step back up, so the
+   * position being restored is already inside the region — a restore to a row
+   * below the region would put the cursor outside it, which is undefined
+   * across terminals.
+   */
+  output.write(`${makeRoom}${CSI}${rows}A\x1b7${CSI}1;${bottom}r\x1b8`);
 
   const release = () => {
     if (released) return;

package/lib/mcp-server.mjs

@@ -420,6 +420,19 @@ export const MEDIA_READ_TOOLS = Object.freeze(['read_document', 'read_table']);
  * fact rather than a preference.
  */
 export const REFUSED_TOOL_REASONS = Object.freeze({
+  /**
+   * ── ⭐ THE FOUR MOAT VERBS ARE REFUSED OVER MCP, DELIBERATELY ────────────
+   *
+   * Each is minutes of GPU billed per video-second, started by a caller we
+   * cannot see and cannot ask. Every other expensive verb in this product is
+   * bounded by a human in the loop; an MCP client is not one. Serving these
+   * would let a third-party agent spend real money in a loop with nobody
+   * watching, and the first anyone would know is the invoice.
+   */
+  clone_voice: 'minutes of GPU billed per second, and it impersonates a real person — an MCP caller cannot be asked whether they have the right to that voice',
+  design_voice: 'minutes of GPU billed per second, started by a caller with no spending limit we can see',
+  talking_head: 'the most expensive verb here: minutes of GPU priced per video-second, and it puts words in a real face',
+  generate_video: 'minutes of GPU per clip, and nothing on the MCP side bounds how many times it is called',
   // ── Rule 1a: nothing starts a process, and there is no flag for it. ──
   run_command: 'starts a process; combined with write_file that is arbitrary code execution, and an MCP config is not a per-run human decision',
   run_program: 'starts a process — same reason as run_command, with an argv instead of a string',

package/lib/tools.mjs

@@ -46,6 +46,8 @@ import {
 } from './git.mjs';
 import { speak, transcribe, makeDocument, readDocument, readTable, mediaToolSchemas, mediaToolNames } from './media.mjs';
 import { editImage, expandImage, imageEditToolSchemas, imageEditToolNames } from './image-edit.mjs';
+import { avatarToolSchemas, avatarToolNames } from './avatar.mjs';
+import { cloneVoice, designVoice, talkingHead, generateVideo } from './avatar-run.mjs';
 /**
  * ⭐ `designPass` IS A STRICT SUPERSET OF `seePage`, deliberately, so wiring it
  * is a SWAP rather than a migration: `ok`, `path`, `screenshot`,
@@ -294,6 +296,26 @@ TOOL_SCHEMAS.push(...imageEditToolSchemas({
   MODAL_SELECT_URL: 'declared', MODAL_FLUX_URL: 'declared',
 }));
 
+/**
+ * ── ⭐⭐⭐ THE MOAT HALF — cloned voice · designed voice · the face · video ──
+ *
+ * ⚠️ MEASURED 2026-08-22: the CLI carried 9 of the console's 20 Modal
+ * endpoints, and every missing one was a moat capability. It shipped generic
+ * TTS and transcription — the two things anybody can rent — while the cloned
+ * voice and the talking head, running on GPUs we already pay for, were
+ * reachable only from the web builder. `media.mjs` said so in its own schema:
+ * "voice cloning is not reachable from the CLI and will be refused."
+ *
+ * Declared unconditionally like the rest, for the same reason: the drift guard
+ * must not see a different tool list on a machine with different env. The
+ * per-turn OFFER below is what gates on real configuration.
+ */
+TOOL_SCHEMAS.push(...avatarToolSchemas({
+  MODAL_VIDEO_SECRET: 'declared',
+  MODAL_AVATAR_URL: 'declared', MODAL_VOICE_CLONE_URL: 'declared',
+  MODAL_VOICE_DESIGN_URL: 'declared', MODAL_VIDEO_URL: 'declared',
+}));
+
 /**
  * ── ⭐ THE MODULES THAT WERE BUILT FOR THIS SEAM AND NEVER PLUGGED INTO IT ──
  *
@@ -818,6 +840,14 @@ export function toolNamesForRounds(maxRounds, { allowRun = true, env = process.e
   // the model then LOOKS at the result. Offering it on a single-shot turn buys
   // the render and throws away the check.
   names.push(...imageEditToolNames(env));
+  /**
+   * ⚠️ MULTI-ROUND ONLY, AND THE STRONGEST CASE OF THE THREE. A talking head
+   * is MINUTES of GPU and is priced per video-second. On a single-shot turn
+   * the model would buy the render and then have no round left to look at it,
+   * which is paying for the expensive half of a loop and skipping the half
+   * that makes it correct.
+   */
+  names.push(...avatarToolNames(env));
   names.push('git_status', 'git_diff', 'git_log');
   if (allowRun) names.push('git_commit');
   /**
@@ -1516,6 +1546,34 @@ export async function executeToolCall(call, executor, {
       });
       return { id, name, args, result, mutated: result.ok === true, mutatedPath: result.path ?? null };
     }
+    /**
+     * ── ⭐⭐⭐ THE FOUR MOAT VERBS ────────────────────────────────────────
+     *
+     * ⚠️ ALL FOUR ARE `mutated: true`. Each writes a real file into the
+     * workspace, so the run summary must count it — otherwise a user ends up
+     * with a video on disk that the session never mentioned, which is how a
+     * generated asset becomes a mystery file nobody trusts.
+     *
+     * ⚠️ AND THE EXECUTOR RETURNS `usd`. These are the only verbs here that
+     * spend money per call; the cost travels back with the result rather than
+     * arriving later on a bill.
+     */
+    case 'clone_voice': {
+      const result = await cloneVoice(executor.root, args, { dryRun: executor.dryRun });
+      return { id, name, args, result, mutated: result.ok === true, mutatedPath: result.path ?? null };
+    }
+    case 'design_voice': {
+      const result = await designVoice(executor.root, args, { dryRun: executor.dryRun });
+      return { id, name, args, result, mutated: result.ok === true, mutatedPath: result.path ?? null };
+    }
+    case 'talking_head': {
+      const result = await talkingHead(executor.root, args, { dryRun: executor.dryRun });
+      return { id, name, args, result, mutated: result.ok === true, mutatedPath: result.path ?? null };
+    }
+    case 'generate_video': {
+      const result = await generateVideo(executor.root, args, { dryRun: executor.dryRun });
+      return { id, name, args, result, mutated: result.ok === true, mutatedPath: result.path ?? null };
+    }
     case 'generate_image': {
       /**
        * ⚠️ `mutated: true` — this DOES write a file into the workspace, unlike

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acuvo-code",
-  "version": "0.6.8",
+  "version": "0.6.10",
   "description": "Acuvo Code — the terminal client for the Acuvo capability registry. Zero dependencies, by design.",
   "type": "module",
   "bin": {