@officexapp/vidfarm-devcli 0.21.59 → 0.21.60

package/dist/src/devcli/clipper-run.js

@@ -35,13 +35,26 @@
 //
 // Backend-free (Node built-ins only) so it ships in the public cloud-only CLI.
 import { parseArgs } from "node:util";
-import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import path from "node:path";
 const BOLD = "\x1b[1m";
 const DIM = "\x1b[2m";
 const GREEN = "\x1b[32m";
 const YELLOW = "\x1b[33m";
 const RESET = "\x1b[0m";
+/**
+ * An expected, user-facing condition — "that task does not exist", "that id is
+ * already taken", "answer the gate first". Every throw in this file is one of
+ * these: they are the CLI talking to a human, not a bug. The entry point prints
+ * `.message` and exits 1 instead of dumping a Node stack and filing a crash
+ * report, which is what a wrong task id used to produce.
+ */
+export class ClipperUserError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ClipperUserError";
+    }
+}
 export const RUN_MODES = ["full-interactive", "quick-interactive", "auto-batch", "auto-submit"];
 /** Nobody has chosen yet. Safe, and one of the two common modes. */
 export const DEFAULT_RUN_MODE = "quick-interactive";
@@ -77,7 +90,29 @@ const DEFAULT_ASK = {
     shortlist: "Which of these templates should I adapt? Reply with one template_id (or say 'you pick').",
     plan: "Does this plan match what the buyer asked for? Approve it, or tell me what to change.",
     raws: "Want to help collect footage? Drop clips into the folder above, then approve. Say 'go' to let me source it all myself.",
-    cut: "Watch the cut: does it satisfy the brief, is the hook alive in the first 3 seconds, are the captions readable and inside the safe zone, is the audio clean, is the buyer's brand right?"
+    cut: "Watch the cut, then tick what passes."
+};
+/**
+ * The checklist behind a default gate, as a LIST — never as prose to be split
+ * apart later. The control panel used to derive checkboxes by splitting the ask
+ * on commas, which mangled any custom `--ask` ("…the music licence, and, most of
+ * all, the timing" became a criterion called "most of all") and could write an
+ * invented criterion into a task's approval history. A gate that carries its own
+ * criteria cannot be misread, and a custom ask simply carries none.
+ */
+export const DEFAULT_CRITERIA = {
+    cut: [
+        "Does it satisfy the brief",
+        "Is the hook alive in the first 3 seconds",
+        "Are the captions readable and inside the safe zone",
+        "Is the audio clean",
+        "Is the buyer's brand right"
+    ],
+    plan: [
+        "Does it deliver what the buyer asked for",
+        "Is every beat something the agent can actually source",
+        "Is the hook in the first 3 seconds"
+    ]
 };
 export function normalizeRunMode(raw) {
     const v = (raw ?? "").trim().toLowerCase().replace(/[\s_]+/g, "-");
@@ -98,27 +133,45 @@ export function normalizeRunMode(raw) {
     return null;
 }
 // ── the mission folder ───────────────────────────────────────────────────────
-function missionRoot(values) {
-    const explicit = values.dir?.trim();
+/**
+ * Where the mission folder lives: an explicit path, else VIDFARM_CLIPPER_DIR,
+ * else ./CLIPPER. Exported because the control panel resolves the same folder
+ * from its own flag rather than re-implementing the precedence.
+ */
+export function resolveMissionRoot(dir) {
+    const explicit = dir?.trim();
     if (explicit)
         return path.resolve(explicit);
     if (process.env.VIDFARM_CLIPPER_DIR)
         return path.resolve(process.env.VIDFARM_CLIPPER_DIR);
     return path.resolve("CLIPPER");
 }
+function missionRoot(values) {
+    return resolveMissionRoot(values.dir);
+}
 function readRunMode(root) {
     // A per-run flag beats the file: `--mode auto-batch` on one command must not
     // silently rewrite the mission's own choice.
+    const file = path.join(root, "run.json");
+    if (!existsSync(file))
+        return { mode: DEFAULT_RUN_MODE, isSet: false };
     try {
-        const parsed = JSON.parse(readFileSync(path.join(root, "run.json"), "utf8"));
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
         const mode = normalizeRunMode(parsed?.mode);
         if (mode)
             return { mode, isSet: true, note: parsed.note ?? null };
+        // The file exists and parses but names no mode we know. Falling back
+        // silently is how a mission drops from four gates to two without anybody
+        // being told.
+        return { mode: DEFAULT_RUN_MODE, isSet: false, unreadable: `run.json has no usable "mode" (found ${JSON.stringify(parsed?.mode)})` };
     }
-    catch {
-        /* not set yet */
+    catch (error) {
+        return {
+            mode: DEFAULT_RUN_MODE,
+            isSet: false,
+            unreadable: `run.json could not be read (${error instanceof Error ? error.message : String(error)})`
+        };
     }
-    return { mode: DEFAULT_RUN_MODE, isSet: false };
 }
 function resolveMode(root, values) {
     const flag = normalizeRunMode(values.mode);
@@ -129,15 +182,52 @@ function resolveMode(root, values) {
         return { mode: env, isSet: true };
     return readRunMode(root);
 }
+/** Build a gate, attaching the standard criteria only when the ask is standard. */
+function makeGate(stage, ask) {
+    const custom = (ask ?? "").trim();
+    const text = custom || DEFAULT_ASK[stage] || "Review this and approve it.";
+    const criteria = custom ? undefined : DEFAULT_CRITERIA[stage];
+    return {
+        stage,
+        ask: text,
+        since: new Date().toISOString(),
+        ...(criteria ? { criteria: [...criteria] } : {})
+    };
+}
 function tasksDir(root) {
     return path.join(root, "tasks");
 }
-function taskDir(root, taskId) {
-    // Task ids come off the wire; keep them from escaping the mission folder.
-    const safe = taskId.replace(/[^A-Za-z0-9._-]/g, "_");
-    if (!safe || safe === "." || safe === "..")
+/**
+ * Task ids come off the wire, so they are validated, never "cleaned". Rewriting
+ * unsafe characters mapped distinct ids onto one folder ("T 1" and "T_1"), and
+ * `start` on the second silently overwrote the first — a live task, its history
+ * and its "a human watched this" record, gone with no warning. A raw id also
+ * reaches the page, so anything exotic here is a problem there too.
+ */
+function assertUsableTaskId(taskId) {
+    const id = (taskId ?? "").trim();
+    if (!id || id === "." || id === "..")
         throw new Error(`"${taskId}" is not a usable task id.`);
-    return path.join(tasksDir(root), safe);
+    if (!/^[A-Za-z0-9._-]+$/.test(id)) {
+        throw new Error(`"${taskId}" is not a usable task id — letters, digits, dot, dash and underscore only. ` +
+            `Ids with spaces or quotes cannot be told apart once they are folder names.`);
+    }
+    if (id.length > 128)
+        throw new Error(`"${taskId.slice(0, 32)}…" is too long for a task id (max 128).`);
+    return id;
+}
+/** Non-throwing form of the check above, for readers that must not crash. */
+export function isUsableTaskId(taskId) {
+    try {
+        assertUsableTaskId(taskId);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function taskDir(root, taskId) {
+    return path.join(tasksDir(root), assertUsableTaskId(taskId));
 }
 function statePath(root, taskId) {
     return path.join(taskDir(root, taskId), "state.json");
@@ -149,10 +239,49 @@ function readState(root, taskId) {
     }
     return JSON.parse(readFileSync(file, "utf8"));
 }
+/**
+ * Task folders whose state.json could not be parsed on the last scan, by folder
+ * name. Exported so both front ends can SAY so instead of quietly showing a
+ * shorter list.
+ */
+export const unreadableTasks = new Map();
+/**
+ * Why this parsed object cannot be treated as a task, or null when it can.
+ * Only the fields something downstream will dereference are checked — this is a
+ * guard against bricking the mission, not a schema validator.
+ */
+function describeUnusableState(state) {
+    if (!state || typeof state !== "object")
+        return "state.json is not an object";
+    if (typeof state.task_id !== "string" || !state.task_id)
+        return "state.json has no task_id";
+    if (!isUsableTaskId(state.task_id))
+        return `its recorded task_id ${JSON.stringify(state.task_id)} is not a usable id`;
+    if (typeof state.stage !== "string")
+        return "state.json has no stage";
+    if (typeof state.created_at !== "string")
+        return "state.json has no created_at";
+    if (state.price !== null && state.price !== undefined && typeof state.price !== "number") {
+        return "state.json has a non-numeric price";
+    }
+    if (!Array.isArray(state.history))
+        return "state.json has no history array";
+    if (!Array.isArray(state.shortlist))
+        return "state.json has no shortlist array";
+    return null;
+}
+/** Forget folders that no longer exist, so a deleted broken task stops warning. */
+function forgetMissingUnreadable(root) {
+    for (const folder of Array.from(unreadableTasks.keys())) {
+        if (!existsSync(path.join(tasksDir(root), folder, "state.json")))
+            unreadableTasks.delete(folder);
+    }
+}
 function listStates(root) {
     const dir = tasksDir(root);
     if (!existsSync(dir))
         return [];
+    forgetMissingUnreadable(root);
     const rows = [];
     for (const entry of readdirSync(dir, { withFileTypes: true })) {
         if (!entry.isDirectory())
@@ -161,20 +290,97 @@ function listStates(root) {
         if (!existsSync(file))
             continue;
         try {
-            rows.push(JSON.parse(readFileSync(file, "utf8")));
+            const parsed = JSON.parse(readFileSync(file, "utf8"));
+            // Parsing is not enough. Anything downstream — the sort below, the review
+            // queue's price formatting, the panel's view model — assumes a shape this
+            // module wrote. A hand edit, an older schema or a half-recovered file has
+            // no such guarantee, and ONE of them used to brick the whole mission.
+            const missing = describeUnusableState(parsed);
+            if (missing) {
+                unreadableTasks.set(entry.name, missing);
+                continue;
+            }
+            rows.push(parsed);
+        }
+        catch (error) {
+            // Do not crash the whole loop over one bad file — but do NOT let it
+            // disappear either. A task silently missing from the review queue is
+            // indistinguishable from a task nobody has to look at.
+            unreadableTasks.set(entry.name, error instanceof Error ? error.message : String(error));
+            continue;
+        }
+        unreadableTasks.delete(entry.name);
+    }
+    // Defensive even after validation: a comparator must never be the thing that
+    // throws, because it runs inside every write.
+    return rows.sort((a, b) => String(a.created_at ?? "").localeCompare(String(b.created_at ?? "")));
+}
+/**
+ * One task's own folder (state.json, brief.md, raws/). Exported so the control
+ * panel reads the brief from the same sanitized path the CLI writes it to.
+ */
+export function taskFolder(root, taskId) {
+    return taskDir(root, taskId);
+}
+/** One task's state. Throws when the task was never started. */
+export function readTaskState(root, taskId) {
+    return readState(root, taskId);
+}
+/** Every task in the mission folder, oldest first. */
+export function listTaskStates(root) {
+    return listStates(root);
+}
+/** The mission's saved run mode (ignores the per-call --mode flag). */
+export function readMissionMode(root) {
+    return readRunMode(root);
+}
+/** LEDGER.jsonl, newest last. Unparseable lines are skipped, never fatal. */
+export function readLedger(root) {
+    const file = path.join(root, "LEDGER.jsonl");
+    if (!existsSync(file))
+        return [];
+    const rows = [];
+    for (const line of readFileSync(file, "utf8").split("\n")) {
+        const text = line.trim();
+        if (!text)
+            continue;
+        try {
+            rows.push(JSON.parse(text));
         }
         catch {
-            /* a half-written state file is not worth crashing the whole loop over */
+            /* a torn append is not worth failing the whole view over */
         }
     }
-    return rows.sort((a, b) => a.created_at.localeCompare(b.created_at));
+    return rows;
 }
 function writeState(root, state) {
     state.updated_at = new Date().toISOString();
     const dir = taskDir(root, state.task_id);
     mkdirSync(dir, { recursive: true });
     const file = statePath(root, state.task_id);
-    writeFileSync(file, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+    // Write a sibling temp file and rename over the target. rename(2) is atomic
+    // within a directory, so a reader sees either the whole old file or the whole
+    // new one — never the half-written state that made a gated task vanish from
+    // the queue (listStates skips what it cannot parse).
+    const temp = `${file}.${process.pid}.tmp`;
+    writeFileSync(temp, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+    try {
+        renameSync(temp, file);
+    }
+    catch (error) {
+        // Windows returns EPERM/EBUSY when an indexer or antivirus has the target
+        // open. Retry once, then clean up rather than leaving a stray .tmp behind.
+        try {
+            renameSync(temp, file);
+        }
+        catch {
+            try {
+                rmSync(temp, { force: true });
+            }
+            catch { /* nothing more to do */ }
+            throw error;
+        }
+    }
     // The human's list is a VIEW of the states, so regenerate it every time. A
     // hand-maintained review queue goes stale the first time an agent forgets.
     writeReviewQueue(root);
@@ -202,7 +408,7 @@ export function nextStage(stage) {
 function completeStage(state, stage, ask) {
     state.stage = stage;
     if (isGated(state.mode, stage)) {
-        state.gate = { stage, ask: (ask ?? "").trim() || DEFAULT_ASK[stage] || "Review this and approve it.", since: new Date().toISOString() };
+        state.gate = makeGate(stage, ask);
         note(state, `gate_opened:${stage}`);
         return { gated: true };
     }
@@ -214,13 +420,23 @@ function completeStage(state, stage, ask) {
 // ── the human's list ─────────────────────────────────────────────────────────
 function writeReviewQueue(root) {
     const rows = listStates(root).filter((s) => s.gate);
+    const broken = Array.from(unreadableTasks.entries());
     const lines = [
         "# Review queue",
         "",
         "Regenerated by `vidfarm clipper-run`. One row per task that is WAITING FOR YOU.",
-        "Approve: `vidfarm clipper-run approve <task-id>` · changes: `… changes <task-id> --note \"…\"` · drop: `… drop <task-id> --reason \"…\"`",
+        "**Easiest way to clear this list: `vidfarm dashboard`** — the clipper dashboard plays each cut,",
+        "shows the buyer's brief beside it, and answers the gate in one click.",
+        "",
+        "By hand: `vidfarm clipper-run approve <task-id>` · `… changes <task-id> --note \"…\"` · `… drop <task-id> --reason \"…\"`",
         ""
     ];
+    if (broken.length) {
+        lines.push(`> **${broken.length} task folder(s) could not be read and are NOT in this list.**`);
+        for (const [folder, why] of broken)
+            lines.push(`> - \`${folder}\` — ${why}`);
+        lines.push("");
+    }
     if (!rows.length) {
         lines.push("_Nothing waiting for you right now._");
     }
@@ -228,7 +444,7 @@ function writeReviewQueue(root) {
         lines.push(`## ${state.task_id} — waiting at \`${state.gate.stage}\``);
         lines.push("");
         lines.push(`- buyer machine: ${state.gig_id ?? "?"}${state.machine ? ` (${state.machine})` : ""}`);
-        lines.push(`- price: ${state.price === null ? "TBD" : `$${state.price.toFixed(2)}`} · mode: ${state.mode} · waiting since ${state.gate.since}`);
+        lines.push(`- price: ${typeof state.price === "number" ? `$${state.price.toFixed(2)}` : "TBD"} · mode: ${state.mode} · waiting since ${state.gate.since}`);
         if (state.title)
             lines.push(`- brief: ${state.title}`);
         if (state.harness)
@@ -305,7 +521,295 @@ export function nextAction(state) {
             return { who: "agent", what: "Nothing left on this task." };
     }
 }
+// ── the transitions ──────────────────────────────────────────────────────────
+// Every state change lives here, and BOTH front ends call these: the CLI verbs
+// below, and the local control panel (`vidfarm panel`). Nothing else may write
+// state.json. Two writers would let the terminal and the panel disagree about
+// which gate is open, and the gate is the rail that stops an unreviewed cut.
+/** Size in bytes, or null when the path is missing / not a file. */
+function fileSizeOrNull(candidate) {
+    if (!candidate)
+        return null;
+    try {
+        const stat = statSync(candidate);
+        return stat.isFile() ? stat.size : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Answer an open gate with "yes". Throws when nothing is waiting. */
+export function approveGate(root, taskId, noteText) {
+    const state = readState(root, taskId);
+    if (state.gate?.stage === "cut") {
+        // `reviewed_by_gigworker` is the record a buyer's trust score rests on. It
+        // may only be granted for something that can actually be watched.
+        const size = fileSizeOrNull(state.cut_path);
+        if (size === null) {
+            throw new ClipperUserError(`${state.task_id} has no cut on disk at ${state.cut_path ?? "(no path recorded)"} — there is nothing ` +
+                `to watch, so it cannot be approved. Request changes, or drop it.`);
+        }
+        if (size === 0) {
+            throw new ClipperUserError(`${state.task_id}'s cut is 0 bytes (${state.cut_path}) — the render produced nothing. ` +
+                `Request changes, or drop it.`);
+        }
+    }
+    if (!state.gate) {
+        throw new Error(`${state.task_id} is not waiting for anybody — it is at stage "${state.stage}". Run: vidfarm clipper-run status ${state.task_id}`);
+    }
+    const stage = state.gate.stage;
+    const at = new Date().toISOString();
+    note(state, `approved:${stage}`, noteText ?? null);
+    // Only the CUT gate is the "a human watched the video" record — that is the
+    // one the ledger and the buyer's trust score care about.
+    if (stage === "cut")
+        state.reviewed_by_gigworker = at;
+    state.gate = null;
+    state.stage = nextStage(stage);
+    writeState(root, state);
+    return { state, approved: stage };
+}
+/**
+ * Undo the last decision: reopen the gate this task most recently stopped at.
+ *
+ * A reviewer working at speed WILL mis-click, and the first thing they reach
+ * for is undo. Without it the only escape is `changes` with a note the agent
+ * then tries to act on — which is how "undo" ends up in a task's history as an
+ * instruction to the model. A sent proof is the one thing this cannot take
+ * back; that is a withdrawal on the gig, not a local edit.
+ */
+export function reopenGate(root, taskId) {
+    const state = readState(root, taskId);
+    // The stage is the real signal: `done` means a proof went out, whether or not
+    // a proof id was recorded. Guarding on proof_id alone let a proofless
+    // `submitted` be reopened, re-approved and re-submitted — two ledger rows and
+    // a doubled "awaiting the buyer" figure for one task.
+    if (state.stage === "done" || state.proof_id) {
+        throw new Error(`${state.task_id} already went out${state.proof_id ? ` as proof ${state.proof_id}` : ""}. Undo is local — ` +
+            `it cannot unsend a proof. Withdraw it on the gig instead: vidfarm gigs withdraw ` +
+            `${state.gig_id ?? "<gig-id>"} ${state.proof_id ?? "<proof-id>"}`);
+    }
+    if (state.gate) {
+        throw new Error(`${state.task_id} is already waiting on you at "${state.gate.stage}" — there is nothing to undo.`);
+    }
+    let stage = null;
+    for (let i = state.history.length - 1; i >= 0; i -= 1) {
+        const match = /^gate_opened:(.+)$/.exec(state.history[i].event);
+        if (match) {
+            stage = match[1];
+            break;
+        }
+    }
+    if (!stage) {
+        throw new Error(`${state.task_id} has never stopped for you, so there is no decision of yours to undo.`);
+    }
+    const wasDiscarded = state.stage === "discarded";
+    note(state, `undo:${stage}`);
+    // Unwind what answering that gate had recorded.
+    if (stage === "cut")
+        state.reviewed_by_gigworker = null;
+    if (stage === "shortlist") {
+        state.template_id = null;
+        state.template_picked_by = null;
+    }
+    state.stage = stage;
+    // The original wording is not kept in history, so the gate comes back with
+    // its standard question. The task's own history still shows what happened.
+    state.gate = makeGate(stage, null);
+    writeState(root, state);
+    // A drop wrote a ledger row, so the reversal writes one too — the ledger is
+    // append-only, and a rewritten past is worse than a longer one.
+    if (wasDiscarded) {
+        appendLedger(root, {
+            ts: new Date().toISOString(),
+            gig_id: state.gig_id,
+            task_id: state.task_id,
+            template_id: state.template_id,
+            run_mode: state.mode,
+            status: "reopened",
+            reason: `undo — back to the ${stage} gate`
+        });
+    }
+    return { state, stage };
+}
+/**
+ * A task that has already gone to the buyer is closed to local edits. The rail
+ * lives in these transitions — NOT in the page — so every one of them has to
+ * say so, or the guard is only as good as the client that happens to call it.
+ */
+function assertNotAlreadySent(state, verb) {
+    if (state.stage !== "done" && !state.proof_id)
+        return;
+    throw new ClipperUserError(`${verb} ${state.task_id} is not possible — it already went out` +
+        `${state.proof_id ? ` as proof ${state.proof_id}` : ""}. Withdraw it on the gig instead: ` +
+        `vidfarm gigs withdraw ${state.gig_id ?? "<gig-id>"} ${state.proof_id ?? "<proof-id>"}`);
+}
+/** Send the work back with a note. The note is the whole point. */
+export function requestChanges(root, taskId, noteText) {
+    const state = readState(root, taskId);
+    assertNotAlreadySent(state, "Requesting changes on");
+    const text = noteText.trim();
+    if (!text)
+        throw new Error('changes needs a note — say what to fix, or the agent redoes the same thing.');
+    const stage = state.gate?.stage ?? state.stage;
+    note(state, `changes_requested:${stage}`, text);
+    state.gate = null;
+    // Changing your mind after approving, but before the proof is sent, must
+    // WITHDRAW the approval. It used to leave the "a human watched and accepted
+    // this" stamp in place and the rail cleared, so the agent submitted anyway.
+    if (stage === "submit" || state.stage === "submit") {
+        state.reviewed_by_gigworker = null;
+        note(state, "approval_withdrawn");
+    }
+    // "None of these" means exactly that: clear the candidates so the next round
+    // cannot re-offer the ones just refused.
+    if (stage === "shortlist")
+        state.shortlist = [];
+    // Send it back to the stage that produced the thing being rejected, so the
+    // agent redoes THAT step rather than starting the task over. "not these
+    // templates" means shortlist again, which is the stage BEFORE the list.
+    state.stage = (stage === "cut" || stage === "submit")
+        ? "build"
+        : stage === "shortlist" ? "claimed" : stage;
+    writeState(root, state);
+    return { state, from: stage };
+}
+/** Discard the task and log it. Never submit a cut the gigworker rejected. */
+export function dropTask(root, taskId, reasonText) {
+    const state = readState(root, taskId);
+    // Dropping a task whose proof is with the buyer writes a "discarded" ledger
+    // row that overrides the "submitted" one, silently removing its price from
+    // the money the gigworker is owed.
+    assertNotAlreadySent(state, "Dropping");
+    const reason = reasonText?.trim() || "no reason given";
+    note(state, "discarded", reason);
+    state.gate = null;
+    state.stage = "discarded";
+    writeState(root, state);
+    appendLedger(root, {
+        ts: new Date().toISOString(),
+        gig_id: state.gig_id,
+        task_id: state.task_id,
+        template_id: state.template_id,
+        run_mode: state.mode,
+        status: "discarded",
+        reason
+    });
+    return { state, reason };
+}
+/**
+ * Choose the template to adapt. A pick IS the answer to the shortlist gate, so
+ * it closes it — the gigworker never has to both pick and approve.
+ */
+export function pickTemplate(root, taskId, templateId, by) {
+    const state = readState(root, taskId);
+    // With no id at all, take the top of the shortlist. That is the auto-mode
+    // shape — the agent shortlisted best-first, so "pick" means "take your own
+    // first choice" — and it saves a weak model from re-typing an id it just wrote.
+    const chosen = templateId?.trim() || state.shortlist[0]?.template_id;
+    if (!chosen) {
+        throw new Error("pick needs a template id (or a shortlist to take the top of): vidfarm clipper-run pick <task-id> template_019…");
+    }
+    assertNotAlreadySent(state, "Picking a template for");
+    const wasGated = state.gate?.stage === "shortlist";
+    if (state.gate && !wasGated) {
+        throw new Error(`${state.task_id} is waiting on the gigworker at "${state.gate.stage}", not at the shortlist. ` +
+            `Picking a template here would delete that review request and rewind the task.`);
+    }
+    state.template_id = String(chosen);
+    state.template_picked_by = normalizeWho(by) ?? (wasGated ? "human" : "agent");
+    note(state, "template_picked", `${state.template_id} by ${state.template_picked_by}`);
+    state.gate = null;
+    state.stage = "plan";
+    writeState(root, state);
+    return { state };
+}
+/** Close the row once the proof is on the wire, and append the ledger. */
+export function markSubmitted(root, taskId, proofId) {
+    const state = readState(root, taskId);
+    // Closing the row is a RECORD that the proof went out — it is not a decision,
+    // and it must never be able to answer a question the human was asked. This
+    // used to clear `gate` unconditionally, which turned a HOLD into "cleared to
+    // submit" and wrote a ledger row with reviewed_by_gigworker: null.
+    if (state.gate) {
+        throw new Error(`${state.task_id} is still waiting on the gigworker at "${state.gate.stage}" — answer that first ` +
+            `(vidfarm clipper-run approve ${state.task_id}). "submitted" records a proof; it cannot close a gate.`);
+    }
+    if (state.stage !== "submit" && state.stage !== "done") {
+        throw new Error(`${state.task_id} is at stage "${state.stage}", not "submit" — nothing has been cleared to send yet.`);
+    }
+    state.proof_id = proofId ?? null;
+    note(state, "submitted", state.proof_id);
+    state.gate = null;
+    state.stage = "done";
+    writeState(root, state);
+    appendLedger(root, {
+        ts: new Date().toISOString(),
+        gig_id: state.gig_id,
+        task_id: state.task_id,
+        proof_id: state.proof_id,
+        template_id: state.template_id,
+        harness: state.harness,
+        run_mode: state.mode,
+        locked_price: state.price,
+        status: "submitted",
+        reviewed_by_gigworker: state.reviewed_by_gigworker ?? (state.mode === "auto-submit" ? "auto_submit" : null),
+        paid_out_at: null
+    });
+    return { state };
+}
+/** Add a free-text note to a task's history. */
+export function addTaskNote(root, taskId, text) {
+    const state = readState(root, taskId);
+    const trimmed = text.trim();
+    if (!trimmed)
+        throw new Error('note needs some text: vidfarm clipper-run note <task-id> "buyer wants the logo bigger"');
+    note(state, "note", trimmed);
+    writeState(root, state);
+    return { state };
+}
+/** Save the mission's run mode (run.json + the two MISSION.md lines). */
+export function setRunMode(root, mode, noteText) {
+    const savedAt = new Date().toISOString();
+    mkdirSync(root, { recursive: true });
+    const payload = { mode, note: noteText ?? null, savedAt };
+    const file = path.join(root, "run.json");
+    writeFileSync(file, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+    // MISSION.md is the file a human reads, so keep its two mode lines honest —
+    // but only rewrite lines that already exist. This never invents a mission.
+    const missionFile = path.join(root, "MISSION.md");
+    if (existsSync(missionFile)) {
+        const before = readFileSync(missionFile, "utf8");
+        const after = before
+            .replace(/^run_mode:.*$/m, `run_mode: ${mode}`)
+            .replace(/^auto_submit:.*$/m, `auto_submit: ${mode === "auto-submit"}`);
+        if (after !== before)
+            writeFileSync(missionFile, after, "utf8");
+    }
+    return { mode, file, savedAt };
+}
 // ── output helpers ───────────────────────────────────────────────────────────
+/**
+ * Print anything the mission could not read. The panel already surfaced this;
+ * the CLI did not — and the CLI is what the agent loop reads, so a gated task
+ * could disappear from `next`, `status`, `review` and REVIEW_QUEUE.md at once.
+ */
+function warnUnreadable(root) {
+    if (unreadableTasks.size) {
+        console.log("");
+        console.log(`${YELLOW}${unreadableTasks.size} task folder(s) could not be read — they are NOT in the list above${RESET}`);
+        for (const [folder, why] of unreadableTasks) {
+            console.log(`  ${BOLD}${folder}${RESET} ${DIM}${why}${RESET}`);
+        }
+        console.log(`  ${DIM}Fix or delete ${path.join(root, "tasks", "<folder>", "state.json")} — a task nobody can read is a task nobody reviews.${RESET}`);
+    }
+    const mode = readRunMode(root);
+    if (mode.unreadable) {
+        console.log("");
+        console.log(`${YELLOW}${mode.unreadable}${RESET}`);
+        console.log(`  ${DIM}Falling back to ${mode.mode}. Set it deliberately: vidfarm clipper-run mode <${RUN_MODES.join("|")}>${RESET}`);
+    }
+}
 function out(json, value, human) {
     if (json) {
         console.log(JSON.stringify(value, null, 2));
@@ -315,7 +819,7 @@ function out(json, value, human) {
 }
 function stageLine(state) {
     const gate = state.gate ? `${YELLOW}WAITING ON THE GIGWORKER${RESET} at ${BOLD}${state.gate.stage}${RESET}` : `stage ${BOLD}${state.stage}${RESET}`;
-    const price = state.price === null ? "price TBD" : `$${state.price.toFixed(2)}`;
+    const price = typeof state.price === "number" ? `$${state.price.toFixed(2)}` : "price TBD";
     return `  ${BOLD}${state.task_id}${RESET}  ${gate}  ${DIM}${state.mode} · ${price}${state.gig_id ? " · " + state.gig_id : ""}${RESET}`;
 }
 // ── commands ─────────────────────────────────────────────────────────────────
@@ -324,6 +828,7 @@ const MISSION_TEMPLATE = (mode) => `# Clipper mission
 payout_wallet: 0xYOUR_BASE_L2_ADDRESS      # Base L2, receives USDC
 cash_out: GCash via https://officex.short.gy/solana-usdc-gcash
 cost_mode: minimize                        # profit = price - spend
+dashboard: ask                             # ask | yes | no — open the clipper dashboard for reviews?
 run_mode: ${mode}                          # full-interactive | quick-interactive | auto-batch | auto-submit
 auto_submit: ${mode === "auto-submit"}     # only the gigworker may set this true, in words, on purpose
 specialities:                              # sticker explainers, meme recaptions, greenscreen reaction
@@ -334,7 +839,8 @@ cycle_every: 30 minutes
 stop_if: 2 rejections in a row · any gig warning about funds · 3 failed renders · human says stop
 `;
 function cmdInit(root, values) {
-    const mode = resolveMode(root, values).mode;
+    const resolved = resolveMode(root, values);
+    const mode = resolved.mode;
     mkdirSync(tasksDir(root), { recursive: true });
     const created = [];
     const seed = (name, contents) => {
@@ -354,6 +860,13 @@ function cmdInit(root, values) {
     // which clip, which hook, which pain went to which buyer. Read it before you
     // shortlist, or you sell one buyer the same video twice.
     seed("DELIVERED.tsv", "# gig_id\tproof_id\tharness\ttemplate_id\tsource_clip\thook\tpain\tverdict\n");
+    // `init --mode auto-batch` used to write the mode into MISSION.md and nowhere
+    // else, so run.json stayed unset and `clipper-run mode` reported the default
+    // — the human's file and the machine's file disagreed. Persist a mode that
+    // was actually ASKED for; never persist the assumed default (that stays an
+    // open question until the gigworker answers it).
+    if (resolved.isSet)
+        setRunMode(root, mode, values.note);
     writeReviewQueue(root);
     out(Boolean(values.json), { ok: true, root, mode, created }, () => {
         console.log(`${GREEN}✓${RESET} Mission folder ready at ${BOLD}${root}${RESET}`);
@@ -361,6 +874,9 @@ function cmdInit(root, values) {
             console.log(`  ${DIM}${file}${RESET}`);
         console.log("");
         console.log(`${DIM}Run mode: ${BOLD}${mode}${RESET}${DIM} — change it with: vidfarm clipper-run mode <${RUN_MODES.join("|")}>${RESET}`);
+        console.log("");
+        console.log(`${BOLD}Ask the gigworker whether to open the clipper dashboard${RESET}${DIM} — recommended, and the answer goes in MISSION.md \`dashboard:\`.${RESET}`);
+        console.log(`  ${BOLD}vidfarm dashboard${RESET}${DIM}   the queue as a page: the cut plays, the brief sits beside it, one click answers the gate.${RESET}`);
     });
 }
 function cmdMode(root, values, positionals) {
@@ -370,22 +886,7 @@ function cmdMode(root, values, positionals) {
         const mode = normalizeRunMode(requested);
         if (!mode)
             throw new Error(`Unknown run mode "${requested}". Choose one of: ${RUN_MODES.join(", ")}.`);
-        const savedAt = new Date().toISOString();
-        mkdirSync(root, { recursive: true });
-        const payload = { mode, note: values.note ?? null, savedAt };
-        const file = path.join(root, "run.json");
-        writeFileSync(file, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
-        // MISSION.md is the file a human reads, so keep its two mode lines honest —
-        // but only rewrite lines that already exist. This never invents a mission.
-        const missionFile = path.join(root, "MISSION.md");
-        if (existsSync(missionFile)) {
-            const before = readFileSync(missionFile, "utf8");
-            const after = before
-                .replace(/^run_mode:.*$/m, `run_mode: ${mode}`)
-                .replace(/^auto_submit:.*$/m, `auto_submit: ${mode === "auto-submit"}`);
-            if (after !== before)
-                writeFileSync(missionFile, after, "utf8");
-        }
+        const { file, savedAt } = setRunMode(root, mode, values.note);
         out(json, { ok: true, run_mode: mode, saved_at: savedAt, file, gates: MODE_GATES[mode] }, () => {
             console.log(`${GREEN}${BOLD}Run mode: ${mode}${RESET}`);
             console.log(`${DIM}${MODE_BLURB[mode]}${RESET}`);
@@ -408,11 +909,26 @@ function cmdMode(root, values, positionals) {
         }
         console.log("");
         console.log(`${DIM}Set it: ${BOLD}vidfarm clipper-run mode <${RUN_MODES.join("|")}>${RESET}`);
-        if (!resolved.isSet) {
+        const stored = readRunMode(root);
+        if (stored.unreadable) {
+            console.log(`${YELLOW}${stored.unreadable}${RESET}`);
+            console.log(`${DIM}A mode WAS saved but cannot be read — this is a fallback, not a fresh mission.${RESET}`);
+        }
+        else if (!resolved.isSet) {
             console.log(`${DIM}Nothing saved yet — ASK the gigworker which one they want before the first task.${RESET}`);
         }
     });
 }
+/** A price the caller typed wrong is a silent $0 in the ledger otherwise. */
+function parsePrice(value) {
+    if (value === undefined || value === null || value === "")
+        return null;
+    const parsed = numberOrNull(value);
+    if (parsed === null) {
+        throw new ClipperUserError(`--price "${String(value)}" is not a number. Give it as e.g. --price 4.50, or leave it out.`);
+    }
+    return parsed;
+}
 function numberOrNull(value) {
     const parsed = typeof value === "string" ? Number(value) : typeof value === "number" ? value : NaN;
     return Number.isFinite(parsed) ? parsed : null;
@@ -424,12 +940,23 @@ function cmdStart(root, values, positionals) {
     const mode = resolveMode(root, values).mode;
     const now = new Date().toISOString();
     const dir = taskDir(root, taskId);
+    // Starting an id that already exists used to overwrite a live task back to
+    // `claimed`, taking its history and its review record with it.
+    if (existsSync(path.join(dir, "state.json")) && values.force) {
+        const doomed = readState(root, taskId);
+        console.log(`${YELLOW}--force: overwriting ${taskId}${RESET}${DIM} (was at "${doomed.stage}"${doomed.gate ? `, waiting on you at "${doomed.gate.stage}"` : ""}, ${doomed.history.length} history entr(ies)) — that record is gone.${RESET}`);
+    }
+    if (existsSync(path.join(dir, "state.json")) && !values.force) {
+        const existing = readState(root, taskId);
+        throw new Error(`${taskId} already exists (stage "${existing.stage}"${existing.gate ? `, waiting at "${existing.gate.stage}"` : ""}). ` +
+            `Starting it again would erase its history. Use a different id, or --force to overwrite on purpose.`);
+    }
     mkdirSync(path.join(dir, "raws"), { recursive: true });
     const state = {
-        task_id: taskId,
+        task_id: assertUsableTaskId(taskId),
         gig_id: values.gig ?? null,
         machine: values.machine ?? null,
-        price: numberOrNull(values.price),
+        price: parsePrice(values.price),
         title: values.title ?? null,
         harness: values.harness ?? null,
         mode,
@@ -477,9 +1004,7 @@ function cmdShortlist(root, values, positionals) {
     // task waits at `shortlist` for a `pick` either way — only the gate differs.
     state.stage = "shortlist";
     const gated = isGated(state.mode, "shortlist");
-    state.gate = gated
-        ? { stage: "shortlist", ask: (values.ask ?? "").trim() || DEFAULT_ASK.shortlist, since: new Date().toISOString() }
-        : null;
+    state.gate = gated ? makeGate("shortlist", values.ask) : null;
     if (gated)
         note(state, "gate_opened:shortlist");
     writeState(root, state);
@@ -499,24 +1024,8 @@ function cmdShortlist(root, values, positionals) {
     });
 }
 function cmdPick(root, values, positionals) {
-    const state = readState(root, requireTask(positionals[0], "pick"));
     const flagged = [].concat(values.template ?? [])[0];
-    // With no id at all, take the top of the shortlist. That is the auto-mode
-    // shape — the agent shortlisted best-first, so "pick" means "take your own
-    // first choice" — and it saves a weak model from re-typing an id it just wrote.
-    const templateId = positionals[1] ?? flagged ?? state.shortlist[0]?.template_id;
-    if (!templateId) {
-        throw new Error("clipper-run pick needs a template id (or a shortlist to take the top of): vidfarm clipper-run pick <task-id> template_019…");
-    }
-    // A pick IS the answer to the shortlist gate, so it closes it. That saves the
-    // gigworker from having to both pick and approve.
-    const wasGated = state.gate?.stage === "shortlist";
-    state.template_id = String(templateId);
-    state.template_picked_by = (normalizeWho(values.by) ?? (wasGated ? "human" : "agent"));
-    note(state, "template_picked", `${state.template_id} by ${state.template_picked_by}`);
-    state.gate = null;
-    state.stage = "plan";
-    writeState(root, state);
+    const { state } = pickTemplate(root, requireTask(positionals[0], "pick"), positionals[1] ?? flagged, values.by);
     out(Boolean(values.json), { ok: true, state, next: nextAction(state) }, () => {
         console.log(`${GREEN}✓${RESET} ${BOLD}${state.task_id}${RESET} will adapt ${BOLD}${state.template_id}${RESET} ${DIM}(chosen by the ${state.template_picked_by})${RESET}`);
         const next = nextAction(state);
@@ -585,6 +1094,14 @@ function cmdCut(root, values, positionals) {
         state.clean_master = path.resolve(String(values["clean-master"]));
     if (!state.cut_path)
         throw new Error("clipper-run cut needs --file <path to the WATERMARKED cut>.");
+    const recordedSize = fileSizeOrNull(state.cut_path);
+    if (recordedSize === null) {
+        throw new ClipperUserError(`No file at ${state.cut_path}. Record the cut only once the render has finished — a gate opened on a ` +
+            `path that does not exist wastes the gigworker's trip to the queue.`);
+    }
+    if (recordedSize === 0) {
+        throw new ClipperUserError(`${state.cut_path} is 0 bytes — the render produced nothing. Re-render before recording it.`);
+    }
     note(state, "cut_ready", state.cut_path);
     const { gated } = completeStage(state, "cut", values.ask);
     writeState(root, state);
@@ -597,7 +1114,7 @@ function cmdCut(root, values, positionals) {
             console.log("");
             console.log(`${YELLOW}STOP — the gigworker watches this before it is submitted.${RESET}`);
             console.log(`${DIM}${state.gate.ask}${RESET}`);
-            console.log(`${DIM}Play it: vidfarm serve   ·   fast look: vidfarm stills ${state.cut_path}${RESET}`);
+            console.log(`${DIM}Play it in the clipper dashboard: ${BOLD}vidfarm dashboard${RESET}${DIM}   ·   fast look: vidfarm stills ${state.cut_path}${RESET}`);
             console.log(`${DIM}They answer: vidfarm clipper-run approve ${state.task_id} · changes … --note "…" · drop … --reason "…"${RESET}`);
         }
         else {
@@ -608,19 +1125,7 @@ function cmdCut(root, values, positionals) {
     });
 }
 function cmdApprove(root, values, positionals) {
-    const state = readState(root, requireTask(positionals[0], "approve"));
-    if (!state.gate)
-        throw new Error(`${state.task_id} is not waiting for anybody — it is at stage "${state.stage}". Run: vidfarm clipper-run status ${state.task_id}`);
-    const stage = state.gate.stage;
-    const at = new Date().toISOString();
-    note(state, `approved:${stage}`, values.note ?? null);
-    // Only the CUT gate is the "a human watched the video" record — that is the
-    // one the ledger and the buyer's trust score care about.
-    if (stage === "cut")
-        state.reviewed_by_gigworker = at;
-    state.gate = null;
-    state.stage = nextStage(stage);
-    writeState(root, state);
+    const { state, approved: stage } = approveGate(root, requireTask(positionals[0], "approve"), values.note);
     out(Boolean(values.json), { ok: true, approved: stage, state, next: nextAction(state) }, () => {
         console.log(`${GREEN}✓${RESET} ${BOLD}${state.task_id}${RESET} approved at ${BOLD}${stage}${RESET} → stage ${BOLD}${state.stage}${RESET}`);
         const next = nextAction(state);
@@ -628,18 +1133,10 @@ function cmdApprove(root, values, positionals) {
     });
 }
 function cmdChanges(root, values, positionals) {
-    const state = readState(root, requireTask(positionals[0], "changes"));
     const text = values.note?.trim();
     if (!text)
         throw new Error('clipper-run changes needs --note "<what to fix>" — that note is the whole point.');
-    const stage = state.gate?.stage ?? state.stage;
-    note(state, `changes_requested:${stage}`, text);
-    state.gate = null;
-    // Send it back to the stage that produced the thing being rejected, so the
-    // agent redoes THAT step rather than starting the task over. "not these
-    // templates" means shortlist again, which is the stage BEFORE the list.
-    state.stage = stage === "cut" ? "build" : stage === "shortlist" ? "claimed" : stage;
-    writeState(root, state);
+    const { state, from: stage } = requestChanges(root, requireTask(positionals[0], "changes"), text);
     out(Boolean(values.json), { ok: true, state, next: nextAction(state) }, () => {
         console.log(`${GREEN}✓${RESET} Changes recorded on ${BOLD}${state.task_id}${RESET} at ${BOLD}${stage}${RESET} → back to ${BOLD}${state.stage}${RESET}`);
         console.log(`  ${DIM}${text}${RESET}`);
@@ -647,46 +1144,14 @@ function cmdChanges(root, values, positionals) {
     });
 }
 function cmdDrop(root, values, positionals) {
-    const state = readState(root, requireTask(positionals[0], "drop"));
-    const reason = values.reason?.trim() || "no reason given";
-    note(state, "discarded", reason);
-    state.gate = null;
-    state.stage = "discarded";
-    writeState(root, state);
-    appendLedger(root, {
-        ts: new Date().toISOString(),
-        gig_id: state.gig_id,
-        task_id: state.task_id,
-        template_id: state.template_id,
-        run_mode: state.mode,
-        status: "discarded",
-        reason
-    });
+    const { state, reason } = dropTask(root, requireTask(positionals[0], "drop"), values.reason);
     out(Boolean(values.json), { ok: true, state }, () => {
         console.log(`${GREEN}✓${RESET} Dropped ${BOLD}${state.task_id}${RESET} — ${reason}`);
         console.log(`  ${DIM}Logged to LEDGER.jsonl. On Custom Requests, release it or let it expire — never submit a cut the gigworker rejected.${RESET}`);
     });
 }
 function cmdSubmitted(root, values, positionals) {
-    const state = readState(root, requireTask(positionals[0], "submitted"));
-    state.proof_id = values.proof ?? null;
-    note(state, "submitted", state.proof_id);
-    state.gate = null;
-    state.stage = "done";
-    writeState(root, state);
-    appendLedger(root, {
-        ts: new Date().toISOString(),
-        gig_id: state.gig_id,
-        task_id: state.task_id,
-        proof_id: state.proof_id,
-        template_id: state.template_id,
-        harness: state.harness,
-        run_mode: state.mode,
-        locked_price: state.price,
-        status: "submitted",
-        reviewed_by_gigworker: state.reviewed_by_gigworker ?? (state.mode === "auto-submit" ? "auto_submit" : null),
-        paid_out_at: null
-    });
+    const { state } = markSubmitted(root, requireTask(positionals[0], "submitted"), values.proof);
     out(Boolean(values.json), { ok: true, state }, () => {
         console.log(`${GREEN}✓${RESET} ${BOLD}${state.task_id}${RESET} closed as submitted${state.proof_id ? ` ${DIM}(${state.proof_id})${RESET}` : ""}`);
         console.log(`  ${DIM}Ledger row appended. approved is not paid — reconcile with: vidfarm gigs proof ${state.gig_id ?? "<gig>"} ${state.proof_id ?? "<proof-id>"}${RESET}`);
@@ -726,8 +1191,9 @@ function cmdStatus(root, values, positionals) {
         const waiting = open.filter((s) => s.gate).length;
         console.log("");
         console.log(waiting
-            ? `${YELLOW}${waiting} task(s) waiting on the gigworker${RESET}${DIM} — the list is in ${path.join(root, "REVIEW_QUEUE.md")}${RESET}`
+            ? `${YELLOW}${waiting} task(s) waiting on the gigworker${RESET}${DIM} — answer them in the clipper dashboard: ${BOLD}vidfarm dashboard${RESET}${DIM} (or ${path.join(root, "REVIEW_QUEUE.md")})${RESET}`
             : `${DIM}Nothing waiting on the gigworker.${RESET}`);
+        warnUnreadable(root);
     });
 }
 function cmdNext(root, values) {
@@ -757,12 +1223,13 @@ function cmdNext(root, values) {
         }
         if (waiting.length) {
             console.log("");
-            console.log(`${YELLOW}Waiting on the gigworker — do NOT work around these${RESET}`);
+            console.log(`${YELLOW}Waiting on the gigworker — do NOT work around these${RESET}${DIM} (they answer fastest in the clipper dashboard: ${BOLD}vidfarm dashboard${RESET}${DIM})${RESET}`);
             for (const state of waiting) {
                 console.log(`  ${BOLD}${state.task_id}${RESET} ${DIM}at ${state.gate.stage} since ${state.gate.since}${RESET}`);
                 console.log(`     ${DIM}${state.gate.ask}${RESET}`);
             }
         }
+        warnUnreadable(root);
     });
 }
 function cmdReview(root, values) {
@@ -771,12 +1238,13 @@ function cmdReview(root, values) {
     out(Boolean(values.json), { ok: true, waiting: rows }, () => {
         if (!rows.length) {
             console.log(`${DIM}Nothing waiting for the gigworker.${RESET}`);
+            warnUnreadable(root);
             return;
         }
-        console.log(`${BOLD}${rows.length} task(s) waiting for you${RESET} ${DIM}(also written to ${path.join(root, "REVIEW_QUEUE.md")})${RESET}`);
+        console.log(`${BOLD}${rows.length} task(s) waiting for you${RESET} ${DIM}— the clipper dashboard plays each cut and answers the gate in one click: ${BOLD}vidfarm dashboard${RESET}`);
         for (const state of rows) {
             console.log("");
-            console.log(`  ${BOLD}${state.task_id}${RESET} ${DIM}${state.gate.stage} · ${state.mode}${state.price === null ? "" : ` · $${state.price.toFixed(2)}`}${RESET}`);
+            console.log(`  ${BOLD}${state.task_id}${RESET} ${DIM}${state.gate.stage} · ${state.mode}${typeof state.price === "number" ? ` · $${state.price.toFixed(2)}` : ""}${RESET}`);
             if (state.gate.stage === "shortlist") {
                 for (const row of state.shortlist)
                     console.log(`     ${BOLD}${row.template_id}${RESET}${row.why ? ` ${DIM}— ${row.why}${RESET}` : ""}`);
@@ -790,6 +1258,7 @@ function cmdReview(root, values) {
             console.log(`     ${DIM}${state.gate.ask}${RESET}`);
             console.log(`     ${DIM}vidfarm clipper-run approve ${state.task_id}${state.gate.stage === "shortlist" ? ` (or: pick ${state.task_id} <template_id>)` : ""}${RESET}`);
         }
+        warnUnreadable(root);
     });
 }
 /**
@@ -809,7 +1278,12 @@ function cmdGate(root, values, positionals) {
         reviewed_by_gigworker: state.reviewed_by_gigworker
     }, () => {
         if (!blocked) {
-            console.log(`${GREEN}✓ CLEARED TO SUBMIT${RESET} ${BOLD}${state.task_id}${RESET}${state.reviewed_by_gigworker ? ` ${DIM}(gigworker approved the cut at ${state.reviewed_by_gigworker})${RESET}` : ` ${DIM}(auto-submit — no human watched this)${RESET}`}`);
+            const provenance = state.reviewed_by_gigworker
+                ? `${DIM}(gigworker approved the cut at ${state.reviewed_by_gigworker})${RESET}`
+                : state.mode === "auto-submit"
+                    ? `${DIM}(auto-submit — no human watched this)${RESET}`
+                    : `${YELLOW}(NO review record, and this task is ${state.mode} — it should have stopped at the cut gate)${RESET}`;
+            console.log(`${GREEN}✓ CLEARED TO SUBMIT${RESET} ${BOLD}${state.task_id}${RESET} ${provenance}`);
             // This gate answers "did a human watch it", never "can the buyer open it".
             // The second question is the other pre-submit check, and it is the one that
             // catches a 403 bucket or an expiring link.
@@ -823,13 +1297,18 @@ function cmdGate(root, values, positionals) {
     if (blocked)
         process.exitCode = 2;
 }
+function cmdUndo(root, values, positionals) {
+    const { state, stage } = reopenGate(root, requireTask(positionals[0], "undo"));
+    out(Boolean(values.json), { ok: true, reopened: stage, state }, () => {
+        console.log(`${GREEN}✓${RESET} Undone — ${BOLD}${state.task_id}${RESET} is waiting on you again at ${BOLD}${stage}${RESET}`);
+        console.log(`  ${DIM}${state.gate.ask}${RESET}`);
+    });
+}
 function cmdNote(root, values, positionals) {
-    const state = readState(root, requireTask(positionals[0], "note"));
     const text = positionals.slice(1).join(" ").trim() || String(values.note ?? "").trim();
     if (!text)
         throw new Error('clipper-run note needs some text: vidfarm clipper-run note <task-id> "buyer wants the logo bigger"');
-    note(state, "note", text);
-    writeState(root, state);
+    const { state } = addTaskNote(root, requireTask(positionals[0], "note"), text);
     out(Boolean(values.json), { ok: true, state }, () => {
         console.log(`${GREEN}✓${RESET} Noted on ${BOLD}${state.task_id}${RESET}.`);
     });
@@ -866,6 +1345,14 @@ THE GIGWORKER ANSWERS
   clipper-run approve <task-id> [--note "<text>"]
   clipper-run changes <task-id> --note "<what to fix>"
   clipper-run drop    <task-id> --reason "<why>"
+  clipper-run undo    <task-id>          Mis-clicked? Reopen the gate you just answered.
+                                         Refuses once a proof is sent — that is a gig withdrawal.
+
+THE CLIPPER DASHBOARD — the visual half of this loop
+  vidfarm dashboard                One localhost page: the queue with the cut PLAYING, the buyer's
+                                   brief beside it, and Approve / Request changes / Drop. Offer it
+                                   to the gigworker before the first task — most want it, and a
+                                   gate that means "watch this" cannot be answered in a terminal.
 
 WHERE AM I
   clipper-run next                 THE ONE COMMAND — what to do right now, per open task
@@ -887,6 +1374,7 @@ function options() {
         title: { type: "string" },
         harness: { type: "string" },
         brief: { type: "string" },
+        force: { type: "boolean" },
         template: { type: "string", multiple: true },
         why: { type: "string", multiple: true },
         file: { type: "string" },
@@ -899,6 +1387,25 @@ function options() {
     };
 }
 export async function runClipperRunCommand(argv) {
+    try {
+        await dispatchClipperRun(argv);
+    }
+    catch (error) {
+        if (error instanceof ClipperUserError)
+            throw error;
+        // Only DELIBERATE conditions become friendly one-liners. A TypeError or a
+        // ReferenceError is a bug in this file, and dressing it up as advice hides
+        // it from the user AND from crash reporting — which is how a null-deref
+        // shipped looking like an ordinary error message.
+        const deliberate = error instanceof Error
+            && error.constructor === Error
+            && !/undefined|is not a function|Cannot read propert/i.test(error.message);
+        if (deliberate)
+            throw new ClipperUserError(error.message);
+        throw error;
+    }
+}
+async function dispatchClipperRun(argv) {
     const sub = (argv[0] ?? "help").toLowerCase();
     if (["help", "--help", "-h", ""].includes(sub)) {
         console.log(CLIPPER_RUN_HELP);
@@ -929,6 +1436,8 @@ export async function runClipperRunCommand(argv) {
         case "revise": return cmdChanges(root, values, rest);
         case "drop":
         case "discard": return cmdDrop(root, values, rest);
+        case "undo":
+        case "reopen": return cmdUndo(root, values, rest);
         case "submitted":
         case "sent": return cmdSubmitted(root, values, rest);
         case "status":