@aicopycoders/exodus 2026.9.1900-beta.0 → 2026.9.1900-beta.2

package/dist/commands/workflow.js

@@ -20,7 +20,7 @@ Usage:
   exodus workflow templates [list] [--json]
   exodus workflow templates export <key> [--out <file>] [--json]
   exodus workflow schema [--kind <kind>] [--face <face>] [--json]
-  exodus workflow run <workflowId|name> [--fill <name>] [--input key=value ...] [--input <fileField>=<path> ...] [--rig-overrides <json|@file>] [--voices <json|@voices.json>] [--auto-approve] [--wait] [--out <dir>] [--json]
+  exodus workflow run <workflowId|name> [--fill <name>] [--input key=value ...] [--input <fileField>=<path> ...] [--rig-overrides <json|@file>] [--voices <json|@voices.json>] [--voice-treatment <name|json|@file>] [--auto-approve] [--wait] [--out <dir>] [--json]
   exodus workflow status [--json]
   exodus workflow status --id <runId> [--out <dir>] [--json]
   exodus workflow cancel <runId> [--reason "..."] [--json]
@@ -102,6 +102,29 @@ Flags:
                          <run>" at the storyboard review instead. Voice ids
                          belong to the brand's own folder — never put them in a
                          shared workflow or template.
+  --voice-treatment <v>  (run) Say HOW this run makes its voices. Two kinds of
+                         answer. A name on its own picks a way of working that
+                         uses voices you already have:
+                           --voice-treatment sts-revoice
+                           --voice-treatment lipsync-retarget --voices @voices.json
+                         The other kind has the video model speak the lines
+                         itself, in a voice you WRITE instead of one you pick.
+                         Those need a description for every speaker in your
+                         script, so they take a JSON object, or @path to a .json
+                         file holding one:
+                           --voice-treatment @voice-treatment.json
+                           --voice-treatment '{"path":"native-prompt","describe":{"HOST 1":"Dry, tired baritone."}}'
+                         Written voices and --voices are never used together:
+                         the video model owns the voice on those runs, so
+                         ElevenLabs voices would be paid for and never heard,
+                         and asking for both stops the launch. Anything the run
+                         could not actually do — a treatment this stack has not
+                         switched on, a Video step on a model that cannot do it,
+                         a missing key, a rig that shows every line as on-screen
+                         text — stops the launch before the run is created, and
+                         the message says which. Descriptions are chosen HERE,
+                         at the start: "exodus video voices <run>" shows them at
+                         the review but cannot change them.
   --auto-approve         (run) Deliberately unattended launch: every Checkpoint
                          box this run stops at is approved automatically, with
                          whatever it was holding left exactly as it is, and the
@@ -194,6 +217,7 @@ Examples:
   exodus workflow run "Product Shots" --rig-overrides '{"rig_1":{"lines":{"line_1":{"count":3}}}}'
   exodus workflow run "Product Shots" --rig-overrides @rig.json --wait
   exodus workflow run "Podcast Ad" --input script=@script.txt --voices @voices.json --wait
+  exodus workflow run "Podcast Ad" --input script=@script.txt --voice-treatment @voice-treatment.json --wait
   exodus workflow run "Launch Flow" --wait --out ./deliverables
   exodus workflow status                      # recent runs + their ids
   exodus workflow status --id wr_123
@@ -268,6 +292,20 @@ Notes:
   no speaker names to key on at the start, so it is refused with a pointer at
   the review-time command. Keep voice ids in the brand's own folder, never in a
   shared workflow or template. (#1846)
+  "workflow run --voice-treatment" says HOW a run makes its voices. Some ways of
+  working play a voice you picked (that is today's behaviour, and it still takes
+  --voices); others have the video model speak the CAST's lines itself, in voices
+  you describe in words. A described voice needs one description per speaker,
+  because a speaker nobody described gets a voice the model invents afresh on
+  every clip, and the drift only shows up once the clips are paid for. Written
+  voices and --voices are refused together, since the ElevenLabs voices would
+  never be heard. Everything the run could not do — a way of working this stack
+  has not switched on, a Video step whose model cannot do it, a missing key, a
+  rig that shows every line as on-screen text — stops the launch before the run
+  is created. The ways of working beyond the two shipped ones are switched on
+  only on the test stack while they are being tried out, so a live run refuses
+  them by name. Both the launch receipt and "workflow status" say which way a
+  run took, and "exodus video voices <run>" shows each written voice. (#1869)
   workflow triggers are addressed by 1-based position — a trigger carries no id,
   so the CLI reads the live list from the export contract and sends a fingerprint
   of the trigger's fields as the guard; a concurrent edit fails loud rather than
@@ -310,6 +348,24 @@ Notes:
   ids it wants). The "gate" verbs retired in 2.0 along with the Gate node — the
   command now prints a pointer at "checkpoint" and exits 1.
 `.trim();
+export function formatRulesLine(provenance) {
+    const format = provenance?.format;
+    if (!format || typeof format !== "object")
+        return undefined;
+    const { rigName, specVersion, nodeId, rulesFrom } = format;
+    if (typeof rigName !== "string" || rigName === "")
+        return undefined;
+    const version = typeof specVersion === "string" && specVersion !== ""
+        ? `, version ${specVersion}`
+        : "";
+    const where = typeof nodeId === "string" && nodeId !== ""
+        ? ` (from the "${nodeId}" Rig box)`
+        : " (from the Show's rig)";
+    const borrowed = rulesFrom && typeof rulesFrom.rigName === "string"
+        ? ` The rules come from "${rulesFrom.rigName}".`
+        : "";
+    return `Format rules: ${rigName}${version}${where}.${borrowed}`;
+}
 const LIST_PATH = "/api/v2/workflows";
 const RUN_PATH = "/api/v2/workflows/run";
 const STATUS_PATH = "/api/v2/workflow";
@@ -354,6 +410,7 @@ const VALUE_FLAGS = new Set([
     "reject",
     "rig-overrides",
     "voices",
+    "voice-treatment",
     "note",
 ]);
 function defaultMkdirp(dir) {
@@ -552,35 +609,25 @@ function normalizeMultiValue(value) {
         .filter((p) => p.length > 0)
         .join(", ");
 }
-export function parseRawInputFlags(args) {
+export function parseRawInputFlags(occurrences) {
     const inputs = {};
-    for (let i = 0; i < args.length; i++) {
-        const arg = args[i];
-        let raw;
-        if (arg === "--input") {
-            raw = args[i + 1];
-            i++;
-        }
-        else if (arg.startsWith("--input=")) {
-            raw = arg.slice("--input=".length);
-        }
-        else {
+    for (const { flag, value } of occurrences) {
+        if (flag !== "input")
             continue;
-        }
-        if (!raw)
+        if (!value)
             throw new Error("--input requires key=value");
-        const eq = raw.indexOf("=");
+        const eq = value.indexOf("=");
         if (eq <= 0)
-            throw new Error(`--input must be key=value (got "${raw}")`);
-        const key = raw.slice(0, eq).trim();
+            throw new Error(`--input must be key=value (got "${value}")`);
+        const key = value.slice(0, eq).trim();
         if (!key)
-            throw new Error(`--input must include a key (got "${raw}")`);
-        inputs[key] = raw.slice(eq + 1);
+            throw new Error(`--input must include a key (got "${value}")`);
+        inputs[key] = value.slice(eq + 1);
     }
     return inputs;
 }
-export function parseInputFlags(args, readFile) {
-    const inputs = parseRawInputFlags(args);
+export function parseInputFlags(occurrences, readFile) {
+    const inputs = parseRawInputFlags(occurrences);
     for (const [key, value] of Object.entries(inputs)) {
         inputs[key] = expandInputValue(key, value, readFile);
     }
@@ -876,12 +923,10 @@ async function prepareRunInputs(workflowId, raw, deps, note) {
     }
     return { inputs: prepared, warnings };
 }
-export function rejectTerminalFlag(args) {
-    for (const arg of args) {
-        if (arg === "--terminal" || arg.startsWith("--terminal=")) {
-            throw new Error("--terminal is no longer supported: a run now executes the whole " +
-                "workflow or it doesn't start. Re-run without --terminal.");
-        }
+export function rejectTerminalFlag(occurrences) {
+    if (occurrences.some((o) => o.flag === "terminal")) {
+        throw new Error("--terminal is no longer supported: a run now executes the whole " +
+            "workflow or it doesn't start. Re-run without --terminal.");
     }
 }
 export function parseAutoApproveFlag(args) {
@@ -894,21 +939,11 @@ export function parseAutoApproveFlag(args) {
     }
     return false;
 }
-export function parseRigOverridesFlag(args, readFile) {
+export function parseRigOverridesFlag(occurrences, readFile) {
     let raw;
-    for (let i = 0; i < args.length; i++) {
-        const arg = args[i];
-        let value;
-        if (arg === "--rig-overrides") {
-            value = args[i + 1];
-            i++;
-        }
-        else if (arg.startsWith("--rig-overrides=")) {
-            value = arg.slice("--rig-overrides=".length);
-        }
-        else {
+    for (const { flag, value } of occurrences) {
+        if (flag !== "rig-overrides")
             continue;
-        }
         if (value === undefined || value.startsWith("--")) {
             throw new Error("--rig-overrides requires JSON or @path/to/file.json");
         }
@@ -951,21 +986,11 @@ export function parseRigOverridesFlag(args, readFile) {
     }
     return parsed;
 }
-export function parseVoicesFlag(args, readFile) {
+export function parseVoicesFlag(occurrences, readFile) {
     let raw;
-    for (let i = 0; i < args.length; i++) {
-        const arg = args[i];
-        let value;
-        if (arg === "--voices") {
-            value = args[i + 1];
-            i++;
-        }
-        else if (arg.startsWith("--voices=")) {
-            value = arg.slice("--voices=".length);
-        }
-        else {
+    for (const { flag, value } of occurrences) {
+        if (flag !== "voices")
             continue;
-        }
         if (value === undefined || value.startsWith("--")) {
             throw new Error("--voices requires JSON or @path/to/voices.json");
         }
@@ -1008,25 +1033,66 @@ export function parseVoicesFlag(args, readFile) {
     }
     return parsed;
 }
-export function parseFillFlag(args) {
-    let name;
-    for (let i = 0; i < args.length; i++) {
-        const arg = args[i];
-        let raw;
-        if (arg === "--fill") {
-            raw = args[i + 1];
-            i++;
+export function parseVoiceTreatmentFlag(occurrences, readFile) {
+    const usage = "--voice-treatment requires a treatment name, JSON, or @path/to/voice-treatment.json";
+    let raw;
+    for (const { flag, value } of occurrences) {
+        if (flag !== "voice-treatment")
+            continue;
+        if (value === undefined || value.startsWith("--"))
+            throw new Error(usage);
+        raw = value;
+    }
+    if (raw === undefined)
+        return undefined;
+    let text = raw.trim();
+    if (!text)
+        throw new Error(usage);
+    let fromFile = false;
+    if (text.startsWith("@@")) {
+        text = text.slice(1);
+    }
+    else if (text.startsWith("@")) {
+        const filePath = text.slice(1);
+        if (!filePath) {
+            throw new Error("--voice-treatment @<file> needs a file path after \"@\"");
         }
-        else if (arg.startsWith("--fill=")) {
-            raw = arg.slice("--fill=".length);
+        if (!readFile) {
+            throw new Error(`--voice-treatment: cannot load @${filePath} here (no file access)`);
         }
-        else {
-            continue;
+        try {
+            text = readFile(filePath);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            throw new Error(`--voice-treatment: could not read file "${filePath}": ${msg}`);
         }
-        if (raw === undefined || raw.startsWith("--")) {
+        fromFile = true;
+    }
+    if (!fromFile && !text.startsWith("{"))
+        return { path: text };
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        throw new Error(`--voice-treatment is not valid JSON: ${msg}`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error('--voice-treatment must be a treatment name, or a JSON object like {"path":"native-prompt","describe":{"HOST 1":"..."}}');
+    }
+    return parsed;
+}
+export function parseFillFlag(occurrences) {
+    let name;
+    for (const { flag, value } of occurrences) {
+        if (flag !== "fill")
+            continue;
+        if (value === undefined || value.startsWith("--")) {
             throw new Error("--fill requires a saved fill's name");
         }
-        const trimmed = raw.trim();
+        const trimmed = value.trim();
         if (!trimmed)
             throw new Error("--fill requires a saved fill's name");
         name = trimmed;
@@ -1137,6 +1203,12 @@ export function formatWorkflowRun(run) {
     lines.push(`status:       ${runVerdict(run)}${counts ? ` (${counts})` : ""}`);
     if (run.isTerminal)
         lines.push("terminal:     yes");
+    const rulesLine = formatRulesLine(run.provenance);
+    if (rulesLine)
+        lines.push(rulesLine);
+    const treatmentLine = voiceTreatmentLine(run.provenance);
+    if (treatmentLine)
+        lines.push(treatmentLine);
     if (run.error)
         lines.push(`error:        ${run.error}`);
     if (Object.keys(run.inputs ?? {}).length > 0) {
@@ -1828,6 +1900,23 @@ function launchVoicesLine(attached) {
     }
     return said.length > 0 ? `Voices: ${said.join(", ")}` : undefined;
 }
+export function voiceTreatmentLine(provenance) {
+    const voice = provenance?.voice;
+    if (!voice || typeof voice !== "object")
+        return undefined;
+    if (voice.source === "unreadable") {
+        return ("Voice treatment: the setting saved when this run started cannot be read, so no " +
+            "clip will be made. Start the run again.");
+    }
+    const path = voice.path;
+    if (typeof path !== "string" || path === "")
+        return undefined;
+    const where = voice.source === "show" ? "from its Show" : "chosen at launch";
+    const described = voice.source === "launch" && Array.isArray(voice.descriptions) && voice.descriptions.length > 0
+        ? `. Written voices: ${voice.descriptions.map((d) => d.speaker).join(", ")}`
+        : "";
+    return `Voice treatment: ${path} (${where})${described}`;
+}
 export async function runFlow(workflowRef, opts, deps) {
     let workflowId;
     try {
@@ -1871,6 +1960,7 @@ export async function runFlow(workflowRef, opts, deps) {
         ...(opts.autoApprove === true ? { autoApprove: true } : {}),
         ...(opts.imageRigOverrides ? { imageRigOverrides: opts.imageRigOverrides } : {}),
         ...(opts.voices ? { voices: opts.voices } : {}),
+        ...(opts.voiceTreatment ? { voiceTreatment: opts.voiceTreatment } : {}),
         launchedVia: "cli",
     };
     const start = await deps.post(RUN_PATH, body);
@@ -1885,6 +1975,12 @@ export async function runFlow(workflowRef, opts, deps) {
     if (opts.json && !opts.wait)
         return { code: 0, lines: [JSON.stringify(base)] };
     const voicesLine = launchVoicesLine(data?.launchVoices);
+    const provenance = { format: data?.format ?? null, voice: data?.voice ?? null };
+    const rulesLine = formatRulesLine(provenance);
+    const treatmentLine = voiceTreatmentLine(provenance);
+    const advisories = Array.isArray(data?.advisories)
+        ? data.advisories.filter((line) => typeof line === "string")
+        : [];
     const lines = opts.json
         ? []
         : [
@@ -1892,7 +1988,10 @@ export async function runFlow(workflowRef, opts, deps) {
             "Workflow run started.",
             `runId:        ${data.runId}`,
             `triggerRunId: ${data.triggerRunId}`,
+            ...(rulesLine ? [rulesLine] : []),
+            ...advisories,
             ...(voicesLine ? [voicesLine] : []),
+            ...(treatmentLine ? [treatmentLine] : []),
             `Poll: exodus workflow status --id ${data.runId}`,
         ];
     if (!opts.wait) {
@@ -2858,30 +2957,20 @@ async function resumeAndMaybeWait(runId, triggerRunId, headline, opts, deps, lan
     const prefix = opts.onProgressLine ? [] : startLines;
     return { code: waited.code, lines: [...prefix, ...waited.lines] };
 }
-export function parseSlotFlags(args) {
+export function parseSlotFlags(occurrences) {
     const values = {};
-    for (let i = 0; i < args.length; i++) {
-        const arg = args[i];
-        let raw;
-        if (arg === "--slot") {
-            raw = args[i + 1];
-            i++;
-        }
-        else if (arg.startsWith("--slot=")) {
-            raw = arg.slice("--slot=".length);
-        }
-        else {
+    for (const { flag, value } of occurrences) {
+        if (flag !== "slot")
             continue;
-        }
-        if (!raw)
+        if (!value)
             throw new Error("--slot requires key=value");
-        const eq = raw.indexOf("=");
+        const eq = value.indexOf("=");
         if (eq <= 0)
-            throw new Error(`--slot must be key=value (got "${raw}")`);
-        const key = raw.slice(0, eq).trim();
+            throw new Error(`--slot must be key=value (got "${value}")`);
+        const key = value.slice(0, eq).trim();
         if (!key)
-            throw new Error(`--slot must include a key (got "${raw}")`);
-        values[key] = raw.slice(eq + 1);
+            throw new Error(`--slot must include a key (got "${value}")`);
+        values[key] = value.slice(eq + 1);
     }
     return values;
 }
@@ -2953,7 +3042,7 @@ async function maybeReadStdin(flags) {
         return undefined;
     return raw.endsWith("\n") ? raw.slice(0, -1) : raw;
 }
-export async function run(flags) {
+export async function run(flags, occurrences) {
     const positional = parsePositional();
     const [sub, ...rest] = positional;
     const json = !!flags["json"];
@@ -3009,7 +3098,7 @@ export async function run(flags) {
         const workflowRef = rest[0];
         if (!workflowRef) {
             console.error("Error: workflow run requires <workflowId|name>.");
-            console.log("Usage: exodus workflow run <workflowId|name> [--fill <name>] [--input key=value ...] [--input <fileField>=./path/to/file ...] [--rig-overrides <json|@file>] [--voices <json|@voices.json>] [--auto-approve] [--wait] [--json]");
+            console.log("Usage: exodus workflow run <workflowId|name> [--fill <name>] [--input key=value ...] [--input <fileField>=./path/to/file ...] [--rig-overrides <json|@file>] [--voices <json|@voices.json>] [--voice-treatment <name|json|@file>] [--auto-approve] [--wait] [--json]");
             process.exit(1);
         }
         let inputs;
@@ -3017,13 +3106,15 @@ export async function run(flags) {
         let autoApprove;
         let imageRigOverrides;
         let voices;
+        let voiceTreatment;
         try {
-            inputs = parseRawInputFlags(process.argv.slice(3));
-            rejectTerminalFlag(process.argv.slice(3));
-            fill = parseFillFlag(process.argv.slice(3));
+            inputs = parseRawInputFlags(occurrences);
+            rejectTerminalFlag(occurrences);
+            fill = parseFillFlag(occurrences);
             autoApprove = parseAutoApproveFlag(process.argv.slice(3));
-            imageRigOverrides = parseRigOverridesFlag(process.argv.slice(3), defaultDeps.readFile);
-            voices = parseVoicesFlag(process.argv.slice(3), defaultDeps.readFile);
+            imageRigOverrides = parseRigOverridesFlag(occurrences, defaultDeps.readFile);
+            voices = parseVoicesFlag(occurrences, defaultDeps.readFile);
+            voiceTreatment = parseVoiceTreatmentFlag(occurrences, defaultDeps.readFile);
         }
         catch (e) {
             console.error(`Error: ${e instanceof Error ? e.message : String(e)}`);
@@ -3035,6 +3126,7 @@ export async function run(flags) {
             autoApprove,
             imageRigOverrides,
             voices,
+            voiceTreatment,
             wait: flags["wait"] === true,
             json,
             out: flagString(flags, "out"),
@@ -3167,7 +3259,7 @@ export async function run(flags) {
         }
         let values;
         try {
-            values = parseSlotFlags(process.argv.slice(3));
+            values = parseSlotFlags(occurrences);
         }
         catch (e) {
             console.error(`Error: ${e instanceof Error ? e.message : String(e)}`);
@@ -3205,7 +3297,7 @@ export async function run(flags) {
             }
             let fireOverrides;
             try {
-                fireOverrides = parseRigOverridesFlag(process.argv.slice(3), defaultDeps.readFile);
+                fireOverrides = parseRigOverridesFlag(occurrences, defaultDeps.readFile);
             }
             catch (e) {
                 console.error(`Error: ${e instanceof Error ? e.message : String(e)}`);

package/dist/lib/args.d.ts

@@ -0,0 +1,10 @@
+export interface FlagOccurrence {
+    flag: string;
+    value: string | undefined;
+}
+export interface ParsedArgs {
+    command: string;
+    flags: Record<string, string | boolean>;
+    occurrences: FlagOccurrence[];
+}
+export declare function parseArgs(argv: string[]): ParsedArgs;

package/dist/lib/args.js

@@ -0,0 +1,39 @@
+export function parseArgs(argv) {
+    const [, , rawCommand = "help", ...rest] = argv;
+    const command = ["--help", "-h", "-help"].includes(rawCommand) ? "help" : rawCommand;
+    const flags = {};
+    const occurrences = [];
+    let i = 0;
+    while (i < rest.length) {
+        const arg = rest[i];
+        if (arg === "--help" || arg === "-h") {
+            flags["help"] = true;
+            i++;
+            continue;
+        }
+        if (arg.startsWith("--")) {
+            const key = arg.slice(2);
+            const next = rest[i + 1];
+            const eq = key.indexOf("=");
+            occurrences.push(eq === -1
+                ? { flag: key, value: next }
+                : { flag: key.slice(0, eq), value: key.slice(eq + 1) });
+            if (key.startsWith("no-")) {
+                flags[key.slice(3)] = false;
+                i++;
+            }
+            else if (next !== undefined && !next.startsWith("--")) {
+                flags[key] = next;
+                i += 2;
+            }
+            else {
+                flags[key] = true;
+                i++;
+            }
+        }
+        else {
+            i++;
+        }
+    }
+    return { command, flags, occurrences };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aicopycoders/exodus",
-  "version": "2026.9.1900-beta.0",
+  "version": "2026.9.1900-beta.2",
   "description": "CLI + Claude Code skills for the Copycoders Exodus ad pipeline",
   "repository": {
     "type": "git",