@officexapp/vidfarm-devcli 0.21.54 → 0.21.56

package/dist/src/devcli/marketplace-gigs.js

@@ -24,6 +24,7 @@ const BOLD = "\x1b[1m";
 const DIM = "\x1b[2m";
 const GREEN = "\x1b[32m";
 const YELLOW = "\x1b[33m";
+const RED = "\x1b[31m";
 const RESET = "\x1b[0m";
 /** The shared vidfarm feed: the registry + notification stream every client's machines are listed in. */
 const VIDFARM_FEED_ID = "FEED_01M0BCTVTKSDFZQVEY1RXA4NJK";
@@ -58,25 +59,56 @@ CLIENT (paid vidfarm plan — the key is read from your vidfarm account)
   gigs ring-bell --title "<t>" [--subtext "<s>"] [--machine inbound_offers]
                                    Broadcast to every agent on the vidfarm feed
 
-GIGWORKER (free — bring your own key: export DOLLARPLATOON_API_KEY=…)
-  gigs work                        Work waiting in every machine you joined  → GET /work/available
-  gigs feed                        Who is asking for videos right now (notifications)
-    --registry                     Every machine listed in the feed, joinable
-    --limit <n>
-  gigs join-feed [--name "<you>"]  Join the shared vidfarm feed, read-only (needed to read it)
-  gigs join <gig-id> [--invite <token>] [--name "<you>"] [--wallet 0x…]
-  gigs claim <gig-id> [--count 2]  Claim task(s) off a FIFO queue machine
+GIGWORKER — "help me earn on vidfarm" (free — bring your own key: export DOLLARPLATOON_API_KEY=…)
+  gigs earn                        START HERE. The whole first session in one command:
+                                   joins the feed if needed, reads who is asking for videos
+                                   RIGHT NOW, checks every one of those machines for MONEY,
+                                   and prints them best-payer-first with the join command.
+    --limit <n> --name "<you>"     (alias: gigs start)
+
+  the same four moves, one at a time:
+  gigs feed                        ① Who is asking for videos right now (notifications)
+    --funded                       …and whether each one can actually pay
+    --registry                     Every machine listed in the feed, not just today's bells
+  gigs check <gig-id|join-url>     ② CAN THIS MACHINE PAY ME? available_funds + a verdict.
+    --price <usd>                  Score against the TASK price, not the gig default
+                                   Do this BEFORE you commit an hour. (alias: gigs funds)
+  gigs join <gig-id|invite-url>    ③ Join it. --wallet 0x… --invite <token> --name "<you>"
+                                   SET --wallet ON THE FIRST JOIN: a rollup pays the address
+                                   snapshotted when it was created.
+  gigs work                        ④ Work waiting across every machine you joined (paged)
+  gigs claim <gig-id> [--count 1]  Claim task(s) off a FIFO queue machine. ONE by default.
+                                   Inbound Offers hands out NO tasks — you pitch, unprompted.
+
+  delivering, and getting paid:
+  gigs upload <file> [--prefix p]  Put a file on DollarPlatoon's own s3, get a durable url
   gigs submit <gig-id> --task <task-id> --proof <url> [--proof <url>…]
-    --mailbox <id> --tags a,b --note "<text>"
+    --clean-master <file>          Upload it and seal it in the private note. THE WATERMARKED
+                                   cut goes in --proof; the clean master goes here, and the
+                                   buyer cannot read it until a rollup has actually paid you.
+    --private-note "<text>"        Anything else that follows the master (ProRes, project
+                                   files, music licence id). 8000 chars, cannot be added later.
+    --mailbox <id> --tags a,b --note "<text>"   (--note is the PUBLIC feedback field)
+    Watch the cut and approve it BEFORE this call — a rejection scores on your
+    wallet and clients read it as a trust score on your public profile.
+  gigs proof <gig-id> <proof-id>   Read your own proof back: paid_out_at + the private note
+  gigs earnings                    Your rollups + totals. (aliases: rollups, paid)
   gigs mine                        Your mailboxes across every gig
+  gigs join-feed [--name "<you>"]  Join the shared vidfarm feed (gigs earn does this for you)
 
-  Common: --dp-key <key> · --json · --host <vidfarm url> (for the key lookup)
+  Common: --dp-key <key> · --json · --limit <n> · --host <vidfarm url> (for the key lookup)
 
-  e.g. vidfarm gigs add-task --task "60s explainer for acme.com" --price 0.25 \\
+  e.g. DOLLARPLATOON_API_KEY=… vidfarm gigs earn
+       vidfarm gigs check "https://dollarplatoon.com/gig/GIG_01H…/join?invite=abc"
+       vidfarm gigs submit GIG_01H… --task TASK_01H… \\
+         --proof https://…/final-watermarked.mp4 --clean-master ./final-clean.mp4
+       vidfarm gigs add-task --task "60s explainer for acme.com" --price 0.25 \\
          --upload-link "https://vidfarm.cc/directory/preview/dsh_…/files/acme"
        vidfarm gigs proofs --status pending
        vidfarm gigs approve PRF_01H… --feedback "Great hook, keeping it."
-       DOLLARPLATOON_API_KEY=… vidfarm gigs work`;
+
+  Building the video is a separate job: https://vidfarm.cc/agentic-clipper.md is the loop,
+  and https://vidfarm.cc/flash-harness.md is how to build it on a weak model.`;
 /**
  * "You have no key yet, here is how to get one" — the single most common first
  * run for a gigworker, and a deliberate instruction rather than a bug. cli.ts
@@ -193,6 +225,130 @@ async function dp(auth, path, init = {}) {
     }
     return json;
 }
+/**
+ * Every list route here is cursored, and a FILTERED page can come back empty
+ * while later pages still hold work — `/work/available?only_with_work=true` is
+ * the one that bites. Reading page one only is how a clipper gets told "nothing
+ * waiting" over a feed full of paid work. Page to the end, with a hard stop so a
+ * server that never nulls its cursor cannot spin the loop forever.
+ */
+async function pageAll(auth, path, pick, query = {}, maxPages = 20) {
+    const rows = [];
+    let cursor;
+    for (let page = 0; page < maxPages; page++) {
+        const body = await dp(auth, path, { query: { ...query, cursor } });
+        rows.push(...pick(body));
+        const next = body.next_cursor;
+        cursor = typeof next === "string" && next ? next : undefined;
+        if (!cursor)
+            return { rows, truncated: false };
+    }
+    return { rows, truncated: true };
+}
+/** Run `work` with at most `limit` in flight — these are N gig reads per loop. */
+async function mapLimit(items, limit, work) {
+    const results = new Array(items.length);
+    let next = 0;
+    const runners = Array.from({ length: Math.min(limit, items.length) }, async () => {
+        for (let i = next++; i < items.length; i = next++)
+            results[i] = await work(items[i]);
+    });
+    await Promise.all(runners);
+    return results;
+}
+// ── funding — the check that decides whether work gets paid ──────────────────
+/**
+ * `GET /gigs/:id` has been seen answering both `{ gig: {...} }` and a flat
+ * object — cmdAddTask already reads `webhook` both ways. Unwrap defensively,
+ * because a funds check that silently reads `null` is worse than none: it turns
+ * an EMPTY machine into an "unknown" one, and a clipper works unknowns.
+ */
+function unwrapGig(body) {
+    return body?.gig && typeof body.gig === "object" ? body.gig : (body ?? {});
+}
+function num(value) {
+    const parsed = typeof value === "string" ? Number(value) : typeof value === "number" ? value : NaN;
+    return Number.isFinite(parsed) ? parsed : null;
+}
+async function readGigFunds(auth, gigId) {
+    const gig = unwrapGig(await dp(auth, `/gigs/${encodeURIComponent(gigId)}`));
+    return {
+        gigId,
+        title: String(gig.title ?? gigId),
+        available_funds: num(gig.available_funds),
+        reserved_funds: num(gig.reserved_funds),
+        price: num(gig.price),
+        review_timeout: gig.review_timeout ?? null,
+        distribution: gig.distribution ? String(gig.distribution) : null
+    };
+}
+/**
+ * A $1.00 payout draws $1.10 out of the machine — the 10% platform fee is
+ * charged on top of the gig balance, not deducted from the worker. So a gig
+ * holding $5.00 pays four $1.00 videos, not five, and "can it pay me" has to be
+ * asked against price × 1.1.
+ */
+const PLATFORM_FEE_MULTIPLIER = 1.1;
+const VERDICT_LABEL = {
+    empty: "SKIP",
+    partial: "PARTIAL",
+    thin: "THIN",
+    healthy: "HEALTHY",
+    price_tbd: "PRICE TBD",
+    unknown: "UNKNOWN"
+};
+/** Same thresholds as https://vidfarm.cc/agentic-clipper.md § ④. Keep them in sync. */
+function fundsVerdict(funds, taskPrice) {
+    const available = funds.available_funds;
+    const price = taskPrice ?? funds.price;
+    if (available === null) {
+        return { verdict: "unknown", pays: null, note: "the gig did not report available_funds — check it on dollarplatoon.com before you commit an hour" };
+    }
+    if (available <= 0) {
+        return { verdict: "empty", pays: 0, note: "empty coin box. Approval does not create money — do not work this gig yet" };
+    }
+    if (price === null || price <= 0) {
+        return { verdict: "price_tbd", pays: null, note: `$${available.toFixed(2)} in the machine, but the price is TBD — the client names the amount at approval` };
+    }
+    const pays = Math.floor(available / (price * PLATFORM_FEE_MULTIPLIER));
+    if (pays < 1) {
+        return { verdict: "partial", pays, note: `$${available.toFixed(2)} cannot cover one $${price.toFixed(2)} payout + the 10% fee. Submitting still succeeds — that is not a promise of payment` };
+    }
+    if (pays >= 3) {
+        return { verdict: "healthy", pays, note: `$${available.toFixed(2)} available — about ${pays} payouts at $${price.toFixed(2)} after the 10% fee` };
+    }
+    return { verdict: "thin", pays, note: `$${available.toFixed(2)} available — only about ${pays} payout(s) at $${price.toFixed(2)}. Someone else may take it first` };
+}
+function paintVerdict(verdict) {
+    const label = VERDICT_LABEL[verdict];
+    if (verdict === "healthy")
+        return `${GREEN}${label}${RESET}`;
+    if (verdict === "empty" || verdict === "partial")
+        return `${RED}${label}${RESET}`;
+    return `${YELLOW}${label}${RESET}`;
+}
+/** Rank for the shortlist: the machine most likely to actually pay comes first. */
+const VERDICT_RANK = {
+    healthy: 0, thin: 1, price_tbd: 2, unknown: 3, partial: 4, empty: 5
+};
+/**
+ * A gig id, or a join / invite URL pasted straight out of a notification's
+ * `destination_url`. Both halves come out of the URL, which is the whole point:
+ * a clipper should never have to hand-parse a link to check a machine.
+ */
+function parseGigRef(raw, fallbackInvite = "") {
+    const value = (raw ?? "").trim();
+    if (!/^https?:\/\//i.test(value))
+        return { gigId: value, invite: fallbackInvite };
+    try {
+        const url = new URL(value);
+        const found = url.pathname.split("/").find((segment) => /^GIG_/i.test(segment));
+        return { gigId: found ?? value, invite: fallbackInvite || url.searchParams.get("invite") || "" };
+    }
+    catch {
+        return { gigId: value, invite: fallbackInvite };
+    }
+}
 // ── machine resolution ───────────────────────────────────────────────────────
 const MACHINE_ALIASES = {
     custom: "custom_requests",
@@ -479,21 +635,262 @@ async function cmdRingBell(auth, values) {
 }
 // ── gigworker commands ───────────────────────────────────────────────────────
 async function cmdWork(auth, values) {
-    const body = await dp(auth, "/work/available", { query: { only_with_work: "true", limit: values.limit } });
     // `/work/available` answers `{ items: [...] }` — reading `mailboxes` first
-    // printed "nothing waiting" over a page full of paid work.
-    const rows = body.items ?? body.mailboxes ?? body.work ?? body.data ?? [];
-    out(Boolean(values.json), body, () => {
+    // printed "nothing waiting" over a page full of paid work. And it MUST be
+    // paged: with only_with_work=true the filter runs inside a page, so several
+    // pages in a row can be empty while later ones hold paid work.
+    const { rows, truncated } = await pageAll(auth, "/work/available", (body) => body.items ?? body.mailboxes ?? body.work ?? body.data ?? [], { only_with_work: "true", limit: values.limit ?? "100" });
+    out(Boolean(values.json), { items: rows, truncated }, () => {
         if (!rows.length) {
-            console.log(`${DIM}Nothing waiting in the machines you joined. Find new clients: vidfarm gigs feed${RESET}`);
+            console.log(`${DIM}Nothing waiting in the machines you joined. Find new clients: vidfarm gigs earn${RESET}`);
             return;
         }
         for (const row of rows) {
-            const count = row.available ?? row.pending_count ?? row.count ?? "";
-            console.log(`  ${BOLD}${short(row.gig_title ?? row.gig_id, 60)}${RESET}  ${DIM}${row.gig_id ?? ""}${count !== "" ? ` · ${count} waiting` : ""}${RESET}`);
+            const price = num(row.price);
+            // `tasks_in_mailbox` = already delivered to you. `poll_in_gig` = unclaimed
+            // work sitting in the shared queue. `poll_in_gig: false` is definitive.
+            const state = row.tasks_in_mailbox ? "in your mailbox" : row.poll_in_gig ? "claimable — poll it" : "nothing to poll";
+            console.log(`  ${BOLD}${short(row.gig_title ?? row.gig_id, 55)}${RESET}  ${DIM}${row.gig_id ?? ""}${RESET}`);
+            console.log(`      ${DIM}${state}${price === null ? " · price TBD" : ` · $${price.toFixed(2)}/video`}${RESET}`);
+        }
+        console.log("");
+        if (truncated)
+            console.log(`${YELLOW}More pages exist${RESET}${DIM} — raise --limit or page the API directly.${RESET}`);
+        console.log(`${DIM}The gig price is only a DEFAULT — each task can carry its own, and price TBD means the client names it at approval.${RESET}`);
+        console.log(`${DIM}Check it can pay: vidfarm gigs check <gig-id>   ·   Claim one: vidfarm gigs claim <gig-id>${RESET}`);
+    });
+}
+/**
+ * MOVE 2 of the earning loop — "can this machine actually pay me?"
+ *
+ * This is the check that decides whether an hour of editing turns into money,
+ * and it was the one step of https://vidfarm.cc/marketplace.md with no CLI verb
+ * behind it. Takes a gig id OR a join link pasted straight out of a
+ * notification, so nothing has to be hand-parsed.
+ */
+async function cmdCheck(auth, values, positionals) {
+    const raw = positionals[0];
+    if (!raw)
+        throw new Error("gigs check needs a gig id or a join link: vidfarm gigs check GIG_01H…  (or paste the notification's URL)");
+    const { gigId, invite } = parseGigRef(raw);
+    const funds = await readGigFunds(auth, gigId);
+    const taskPrice = values.price === undefined ? null : num(values.price);
+    const verdict = fundsVerdict(funds, taskPrice);
+    out(Boolean(values.json), { ...funds, verdict: verdict.verdict, pays_about: verdict.pays, note: verdict.note }, () => {
+        console.log(`  ${BOLD}${funds.title}${RESET}  ${DIM}${funds.gigId}${funds.distribution ? " · " + funds.distribution : ""}${RESET}`);
+        console.log(`  ${paintVerdict(verdict.verdict)}  ${verdict.note}`);
+        const reserved = funds.reserved_funds;
+        if (reserved !== null && reserved > 0) {
+            console.log(`      ${DIM}$${reserved.toFixed(2)} is RESERVED for proofs ahead of you. You are paid from available_funds, not the sum.${RESET}`);
+        }
+        // A negative timeout is "never" — Inbound Offers machines do not auto-approve,
+        // so printing the raw -1 reads like a broken field.
+        const timeout = num(funds.review_timeout);
+        if (timeout !== null) {
+            console.log(`      ${DIM}review: ${timeout < 0 ? "no auto-approval — the buyer must act" : `auto-approves after ${timeout}${RESET}`}${RESET}`);
+        }
+        console.log("");
+        if (verdict.verdict === "empty" || verdict.verdict === "partial") {
+            console.log(`${DIM}Funds are per gig and cannot move between gigs — a client's other machine tells you nothing about this one.${RESET}`);
+        }
+        else if (invite) {
+            console.log(`${DIM}Join it: vidfarm gigs join "${raw}" --wallet 0xYOUR_BASE_ADDRESS${RESET}`);
+        }
+        else {
+            console.log(`${DIM}Join it: vidfarm gigs join ${funds.gigId} --invite <token> --wallet 0xYOUR_BASE_ADDRESS${RESET}`);
+            console.log(`${DIM}No token to hand? An invite-only gig refuses a tokenless join — find the tokened link: vidfarm gigs feed --registry${RESET}`);
+        }
+    });
+}
+/**
+ * "help me earn on vidfarm" in one command — moves 1 and 2 of
+ * https://vidfarm.cc/marketplace.md, then a ranked shortlist.
+ *
+ * Reads the notification feed for who is asking for videos RIGHT NOW, digs the
+ * gig id out of each bell's join link, checks every one of them for money, and
+ * prints them best-payer-first with the exact join command. Joins the feed for
+ * you if you are not on it — a non-member 404s on every feed route, which reads
+ * like an empty feed rather than a missing membership.
+ */
+async function cmdEarn(auth, values) {
+    const limit = values.limit ?? "50";
+    const json = Boolean(values.json);
+    const notificationsPath = `/feeds/${VIDFARM_FEED_ID}/notifications`;
+    const pickNotifications = (body) => body.notifications ?? body.items ?? body.data ?? [];
+    let notifications;
+    try {
+        notifications = (await pageAll(auth, notificationsPath, pickNotifications, { limit })).rows;
+    }
+    catch (error) {
+        if (!(error instanceof Error) || !/40[134]/.test(error.message))
+            throw error;
+        if (!json)
+            console.log(`${DIM}Not on the vidfarm feed yet — joining it…${RESET}`);
+        await dp(auth, `/feeds/${VIDFARM_FEED_ID}/join`, {
+            method: "POST",
+            body: { invite: VIDFARM_FEED_READ_INVITE, ...(values.name ? { display_name: String(values.name) } : {}) }
+        });
+        notifications = (await pageAll(auth, notificationsPath, pickNotifications, { limit })).rows;
+    }
+    // One row per MACHINE, newest bell wins. A client who rang three times this
+    // week is one opportunity, not three.
+    const byGig = new Map();
+    const unjoinable = [];
+    for (const row of notifications) {
+        const url = String(row.destination_url ?? row.invite_url ?? "");
+        const { gigId, invite } = parseGigRef(url);
+        if (!/^GIG_/i.test(gigId))
+            continue;
+        if (!invite)
+            unjoinable.push({ gigId, title: row.title });
+        if (byGig.has(gigId))
+            continue;
+        byGig.set(gigId, {
+            gigId,
+            invite,
+            title: String(row.title ?? gigId),
+            subtext: String(row.subtext ?? ""),
+            created_at: String(row.created_at ?? ""),
+            url
+        });
+    }
+    const candidates = [...byGig.values()];
+    const scored = await mapLimit(candidates, 5, async (candidate) => {
+        try {
+            const funds = await readGigFunds(auth, candidate.gigId);
+            const verdict = fundsVerdict(funds);
+            return { ...candidate, funds, ...verdict };
+        }
+        catch {
+            // A gig you cannot read yet is not a dead gig — most commonly you are not
+            // a member. Keep it on the list as unknown rather than dropping it.
+            const funds = { gigId: candidate.gigId, title: candidate.title, available_funds: null, reserved_funds: null, price: null, review_timeout: null, distribution: null };
+            return { ...candidate, funds, verdict: "unknown", pays: null, note: "could not read this gig — you may need to join it first" };
+        }
+    });
+    scored.sort((a, b) => VERDICT_RANK[a.verdict] - VERDICT_RANK[b.verdict]);
+    const joined = await pageAll(auth, "/work/available", (body) => body.items ?? body.mailboxes ?? body.work ?? body.data ?? [], { only_with_work: "true", limit: "100" }).catch(() => ({ rows: [], truncated: false }));
+    out(json, { opportunities: scored, work_waiting: joined.rows }, () => {
+        console.log(`${BOLD}① Who is asking for videos right now${RESET} ${DIM}(${notifications.length} bells, ${scored.length} machines)${RESET}`);
+        if (!scored.length) {
+            console.log(`  ${DIM}No bells on the feed yet. The registry lists every machine that exists: vidfarm gigs feed --registry${RESET}`);
+        }
+        console.log("");
+        console.log(`${BOLD}② Which of them can actually pay${RESET}`);
+        for (const row of scored) {
+            console.log(`  ${paintVerdict(row.verdict)}  ${BOLD}${short(row.title, 58)}${RESET}  ${DIM}${row.gigId}${RESET}`);
+            console.log(`      ${DIM}${row.note}${RESET}`);
+            if (row.subtext)
+                console.log(`      ${DIM}${short(row.subtext, 100)}${RESET}`);
+            if (row.verdict !== "empty" && row.verdict !== "partial") {
+                // No token means the bare join URL is a dead end — an invite-only gig
+                // refuses a tokenless join — so never print a command that cannot work.
+                console.log(row.invite
+                    ? `      ${DIM}→ vidfarm gigs join ${row.url} --wallet 0xYOUR_BASE_ADDRESS${RESET}`
+                    : `      ${YELLOW}→ no ?invite= token on that bell${RESET}${DIM} — get the tokened link: vidfarm gigs feed --registry${RESET}`);
+            }
+        }
+        if (unjoinable.length) {
+            console.log("");
+            console.log(`${YELLOW}${unjoinable.length} bell(s) carry a link with no ?invite= token${RESET}${DIM} — an old build rang those. Find the gig in the registry, where the invite_url IS tokened: vidfarm gigs feed --registry${RESET}`);
+        }
+        console.log("");
+        console.log(`${BOLD}③ Work already waiting in machines you joined${RESET}`);
+        if (!joined.rows.length) {
+            console.log(`  ${DIM}None. Join a funded machine above first.${RESET}`);
+        }
+        else {
+            for (const row of joined.rows) {
+                const price = num(row.price);
+                console.log(`  ${BOLD}${short(row.gig_title ?? row.gig_id, 55)}${RESET}  ${DIM}${row.gig_id ?? ""}${price === null ? " · price TBD" : ` · $${price.toFixed(2)}`}${row.poll_in_gig ? " · claimable" : ""}${RESET}`);
+            }
+        }
+        console.log("");
+        console.log(`${DIM}Then: vidfarm gigs claim <gig-id>  →  build it  →  vidfarm gigs submit <gig-id> --task <task-id> --proof <url>${RESET}`);
+        console.log(`${DIM}Inbound Offers machines hand out NO tasks — you pitch a finished video unprompted, and a pass costs you no reputation.${RESET}`);
+        console.log(`${DIM}Weak model? Build from a decomposed template: https://vidfarm.cc/flash-harness.md${RESET}`);
+    });
+}
+/**
+ * "have I been paid?" — `approved` is not `paid`. A rollup that reads `failed`
+ * means NOT SETTLED YET, never lost: the cron retries the same rollup, checking
+ * the chain first, until it settles. Never ask for one to be re-sent.
+ */
+async function cmdEarnings(auth, values) {
+    const { rows } = await pageAll(auth, "/rollups/mine", (body) => body.rollups ?? body.items ?? body.data ?? [], { limit: values.limit ?? "100" });
+    const totals = new Map();
+    for (const row of rows) {
+        const status = String(row.status ?? "unknown");
+        const entry = totals.get(status) ?? { count: 0, amount: 0 };
+        entry.count += 1;
+        entry.amount += num(row.net_amount) ?? 0;
+        totals.set(status, entry);
+    }
+    out(Boolean(values.json), { rollups: rows, totals: Object.fromEntries(totals) }, () => {
+        if (!rows.length) {
+            console.log(`${DIM}No rollups yet. Submit a proof first: vidfarm gigs earn${RESET}`);
+            return;
+        }
+        for (const row of rows.slice(0, 25)) {
+            const amount = num(row.net_amount);
+            const settled = row.status === "settled" || row.status === "paid" || Boolean(row.tx_hash);
+            console.log(`  ${settled ? GREEN + "✓" : YELLOW + "·"}${RESET} ${BOLD}${amount === null ? "?" : "$" + amount.toFixed(2)}${RESET}  ${DIM}${row.status ?? ""}${row.tx_hash ? " · " + short(row.tx_hash, 22) : ""}${RESET}`);
+        }
+        console.log("");
+        for (const [status, entry] of totals) {
+            console.log(`  ${BOLD}${status}${RESET}  ${DIM}${entry.count} rollup(s) · $${entry.amount.toFixed(2)}${RESET}`);
         }
         console.log("");
-        console.log(`${DIM}Claim one: vidfarm gigs claim <gig-id>   then   vidfarm gigs submit <gig-id> --task <task-id> --proof <mp4 url>${RESET}`);
+        console.log(`${DIM}A 'failed' rollup means NOT SETTLED YET, never lost — the cron retries the same one until it settles. Never ask for a re-send.${RESET}`);
+        console.log(`${DIM}Per proof, the only field that means the USDC moved is paid_out_at — approved is not paid.${RESET}`);
+    });
+}
+/** Guess a content type so the presigned PUT is not stored as octet-stream. */
+function guessContentType(filename) {
+    const ext = filename.toLowerCase().split(".").pop() ?? "";
+    const map = {
+        mp4: "video/mp4", mov: "video/quicktime", webm: "video/webm", m4v: "video/x-m4v",
+        mp3: "audio/mpeg", wav: "audio/wav", m4a: "audio/mp4",
+        png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", webp: "image/webp", gif: "image/gif",
+        zip: "application/zip", json: "application/json", md: "text/markdown", txt: "text/plain"
+    };
+    return map[ext] ?? "application/octet-stream";
+}
+/**
+ * Put a file on Dollar Platoon's OWN s3 and return the durable url.
+ *
+ * This is where the clean master goes. It has to be their bucket, not a link you
+ * host: the private note presigns that url at read time and the key it hands you
+ * is random, which is exactly what keeps the master unreachable while the note is
+ * still locked. The presigned PUT expires in an hour, so presign immediately
+ * before pushing the bytes.
+ */
+async function uploadToDollarPlatoon(auth, file, prefix = "proofs") {
+    const bytes = readFileSync(file);
+    const filename = file.split(/[\\/]/).pop() || "upload.bin";
+    const contentType = guessContentType(filename);
+    const presign = await dp(auth, "/upload/presign", {
+        method: "POST",
+        body: { filename, content_type: contentType, prefix }
+    });
+    const putUrl = presign.presigned_url ?? presign.url_put ?? "";
+    const publicUrl = presign.url ?? presign.public_url ?? "";
+    if (!putUrl || !publicUrl)
+        throw new Error("upload presign did not return both presigned_url and url — check the key and the host.");
+    const put = await fetch(putUrl, { method: "PUT", headers: { "content-type": contentType }, body: new Uint8Array(bytes) });
+    if (!put.ok)
+        throw new Error(`upload PUT failed: HTTP ${put.status}`);
+    return String(publicUrl);
+}
+async function cmdUpload(auth, values, positionals) {
+    const file = positionals[0];
+    if (!file)
+        throw new Error("gigs upload needs a file: vidfarm gigs upload ./final-clean.mp4");
+    const url = await uploadToDollarPlatoon(auth, file, values.prefix ?? "proofs");
+    out(Boolean(values.json), { url }, () => {
+        console.log(`${GREEN}✓${RESET} Uploaded ${BOLD}${file}${RESET}`);
+        console.log(`  ${url}`);
+        console.log(`  ${DIM}Put THIS in the proof's private note, not in proofs[]: vidfarm gigs submit <gig> --task <id> --proof <watermarked url> --private-note "Clean master: ${short(url, 40)}"${RESET}`);
     });
 }
 async function cmdFeed(auth, values) {
@@ -513,21 +910,44 @@ async function cmdFeed(auth, values) {
     // only one key gives a silent zero on the other route — the exact bug that had
     // `--registry` printing "Nothing on the feed right now" over a full page.
     const rows = body.notifications ?? body.items ?? body.entries ?? body.registry ?? body.data ?? [];
+    // `--funded` answers the question the feed alone cannot: which of these
+    // machines has money in it. One gig read per row, capped at 5 in flight.
+    const funded = new Map();
+    if (values.funded) {
+        const gigIds = [...new Set(rows
+                .map((row) => parseGigRef(String(row.destination_url ?? row.invite_url ?? "")).gigId)
+                .filter((id) => /^GIG_/i.test(id)))];
+        await mapLimit(gigIds, 5, async (gigId) => {
+            const gig = await readGigFunds(auth, gigId).catch(() => null);
+            if (gig)
+                funded.set(gigId, fundsVerdict(gig));
+        });
+    }
     out(Boolean(values.json), body, () => {
         if (!rows.length) {
             console.log(`${DIM}Nothing on the feed right now.${RESET}`);
             return;
         }
         for (const row of rows) {
-            console.log(`  ${BOLD}${short(row.title ?? row.gig_title ?? row.note, 70)}${RESET}`);
+            const link = row.destination_url ?? row.invite_url ?? "";
+            const check = funded.get(parseGigRef(String(link)).gigId);
+            console.log(`  ${check ? paintVerdict(check.verdict) + "  " : ""}${BOLD}${short(row.title ?? row.gig_title ?? row.note, 70)}${RESET}`);
+            if (check)
+                console.log(`      ${DIM}${check.note}${RESET}`);
             if (row.subtext)
                 console.log(`      ${DIM}${short(row.subtext, 100)}${RESET}`);
-            const link = row.destination_url ?? row.invite_url ?? "";
-            if (link)
-                console.log(`      ${link}`);
+            if (link) {
+                // An invite-only gig refuses a tokenless join, so a link with no
+                // `?invite=` is a dead end, not an opportunity. Say so on the row.
+                const joinable = hasInviteToken(link);
+                console.log(`      ${link}${joinable ? "" : `  ${YELLOW}← no ?invite= token: cannot join this link${RESET}`}`);
+            }
         }
         console.log("");
-        console.log(`${DIM}${registry ? "Join one with its invite link, then: vidfarm gigs work" : "Every entry links at a machine you can join right now."}${RESET}`);
+        if (!values.funded) {
+            console.log(`${DIM}A bell tells you who is asking, not who can pay. Add --funded, or run: vidfarm gigs earn${RESET}`);
+        }
+        console.log(`${DIM}${registry ? "The registry is every machine that EXISTS; the notifications are the ones whose owner is awake. Pick today's work from the bells." : "Check one before you commit an hour: vidfarm gigs check <the link above>"}${RESET}`);
     });
 }
 async function cmdJoinFeed(auth, values) {
@@ -544,15 +964,12 @@ async function cmdJoin(auth, values, positionals) {
     if (!raw)
         throw new Error("gigs join needs a gig id or an invite URL: vidfarm gigs join GIG_01H… --invite <token>");
     // An invite URL carries both halves: .../gig/<gigId>/join?invite=<token>
-    let gigId = raw;
-    let invite = values.invite ? String(values.invite) : "";
-    if (/^https?:\/\//i.test(raw)) {
-        const url = new URL(raw);
-        const found = url.pathname.split("/").find((s) => /^GIG_/i.test(s));
-        if (found)
-            gigId = found;
-        invite = invite || url.searchParams.get("invite") || "";
-    }
+    const { gigId, invite } = parseGigRef(raw, values.invite ? String(values.invite) : "");
+    // Joining is free and reversible, so this never blocks — but a clipper who
+    // joins an empty machine and only discovers it after an hour of editing has
+    // already lost the afternoon. Surface the coin box at the moment of joining.
+    const funds = await readGigFunds(auth, gigId).catch(() => null);
+    const verdict = funds ? fundsVerdict(funds) : null;
     const result = await dp(auth, `/gigs/${encodeURIComponent(gigId)}/mailboxes`, {
         method: "POST",
         body: {
@@ -561,9 +978,17 @@ async function cmdJoin(auth, values, positionals) {
             ...(values.wallet ? { wallet_address: String(values.wallet) } : {})
         }
     });
-    out(Boolean(values.json), result, () => {
+    out(Boolean(values.json), { ...result, funds, verdict: verdict?.verdict ?? null }, () => {
         const mailbox = result.mailbox?.id ?? result.id ?? "";
         console.log(`${GREEN}✓${RESET} Joined ${BOLD}${gigId}${RESET}${mailbox ? ` ${DIM}mailbox ${mailbox}${RESET}` : ""}`);
+        if (verdict)
+            console.log(`  ${paintVerdict(verdict.verdict)}  ${DIM}${verdict.note}${RESET}`);
+        if (!values.wallet) {
+            // A rollup pays the address snapshotted when it was created, so a wallet
+            // added after the first submit does not retroactively redirect anything.
+            console.log(`  ${YELLOW}No --wallet given${RESET}${DIM} — a managed hot wallet is auto-provisioned and you move the money yourself later.${RESET}`);
+            console.log(`  ${DIM}Set it BEFORE your first proof: a rollup pays the address snapshotted when it was created.${RESET}`);
+        }
         console.log(`  ${DIM}Now: vidfarm gigs work   ·   vidfarm gigs claim ${gigId}${RESET}`);
     });
 }
@@ -571,7 +996,12 @@ async function cmdClaim(auth, values, positionals) {
     const gigId = positionals[0];
     if (!gigId)
         throw new Error("gigs claim needs a gig id: vidfarm gigs claim GIG_01H… [--count 2]");
-    const count = values.count === undefined ? 2 : Math.trunc(Number(values.count));
+    // ONE by default. Claiming takes a task off everybody else's queue and the
+    // client is now waiting on you specifically, so a default of 2 quietly put a
+    // clipper two tasks deep before it had finished one — and `unresponsive` is a
+    // 2x reputation hit. The clipper harness's anti-runaway rail is one task in
+    // flight; ask for more only when you mean it.
+    const count = values.count === undefined ? 1 : Math.trunc(Number(values.count));
     const result = await dp(auth, `/gigs/${encodeURIComponent(gigId)}/queue/poll`, { method: "POST", body: { count } });
     const tasks = result.tasks ?? [];
     out(Boolean(values.json), result, () => {
@@ -601,6 +1031,21 @@ async function cmdSubmit(auth, values, positionals) {
         throw new Error("gigs submit needs --task <task-id>. On a queue machine that is the POLLED task's id (never the subject line) — it is what claims the task to you.");
     }
     const tags = values.tags ? String(values.tags).split(",").map((t) => t.trim()).filter(Boolean) : [];
+    // The escrowed half of the delivery. `proofs[]` is a PUBLIC playable url — the
+    // buyer can download it and so can anyone they forward it to — so the
+    // watermarked cut goes there and the clean master goes in `private_note`,
+    // which the platform unseals only once a rollup has stamped paid_out_at.
+    // --clean-master uploads the file to DollarPlatoon's own s3 first, because the
+    // note presigns that url at read time off a random key; a link you host is
+    // reachable the moment anyone guesses it.
+    const noteParts = [];
+    if (values["clean-master"]) {
+        const url = await uploadToDollarPlatoon(auth, String(values["clean-master"]));
+        noteParts.push(`Clean master, no watermark: ${url}`);
+    }
+    if (values["private-note"])
+        noteParts.push(String(values["private-note"]));
+    const privateNote = noteParts.join("\n");
     const result = await dp(auth, `/gigs/${encodeURIComponent(gigId)}/proofs`, {
         method: "POST",
         body: {
@@ -608,12 +1053,60 @@ async function cmdSubmit(auth, values, positionals) {
             proofs,
             ...(values.mailbox ? { mailbox_id: String(values.mailbox) } : {}),
             ...(tags.length ? { tags } : {}),
-            ...(values.note ? { feedback: String(values.note) } : {})
+            ...(values.note ? { feedback: String(values.note) } : {}),
+            ...(privateNote ? { private_note: privateNote } : {})
         }
     });
+    const proof = result.proof ?? result;
     out(Boolean(values.json), result, () => {
-        console.log(`${GREEN}✓${RESET} Submitted to ${BOLD}${gigId}${RESET} ${DIM}${result.proof_id ?? result.id ?? ""}${RESET}`);
+        console.log(`${GREEN}✓${RESET} Submitted to ${BOLD}${gigId}${RESET} ${DIM}${proof.id ?? result.proof_id ?? ""}${RESET}`);
+        if (privateNote) {
+            // The response field is the ONLY confirmation the note was stored, and a
+            // note cannot be patched onto a proof afterwards — so a silent miss here
+            // means the master was never handed over at all.
+            if (proof.private_note_locked) {
+                console.log(`  ${GREEN}✓${RESET} ${DIM}private note stored and sealed — it opens when a rollup stamps paid_out_at, not on approval.${RESET}`);
+            }
+            else {
+                console.log(`  ${RED}!${RESET} ${BOLD}private_note_locked was not returned — the note may not have saved.${RESET}`);
+                console.log(`    ${DIM}You cannot patch a note onto a proof afterwards. Check it now: vidfarm gigs proof ${gigId} ${proof.id ?? "<proof-id>"}${RESET}`);
+            }
+        }
+        else {
+            console.log(`  ${DIM}No private note sent. If that url is your CLEAN master, the buyer now has it before paying — see --clean-master.${RESET}`);
+        }
         console.log(`  ${DIM}The buyer swipes this in a deck — a link that needs a login is a proof they cannot watch.${RESET}`);
+        console.log(`  ${DIM}A proof cannot be unsent. Agents: only submit a cut the gigworker approved, unless they asked for auto-submit.${RESET}`);
+    });
+}
+/**
+ * Read one of YOUR OWN proofs back — the "have I been paid, and did my note
+ * save" check. The submitting worker can always read their own note, at any
+ * status. Note this GET returns the proof FLAT: `.paid_out_at`, never
+ * `.proof.paid_out_at`.
+ */
+async function cmdProof(auth, values, positionals) {
+    const [gigRef, proofId] = positionals;
+    if (!gigRef || !proofId)
+        throw new Error("gigs proof needs a gig id and a proof id: vidfarm gigs proof GIG_01H… PROOF_01H…");
+    const { gigId } = parseGigRef(gigRef);
+    const body = await dp(auth, `/gigs/${encodeURIComponent(gigId)}/proofs/${encodeURIComponent(proofId)}`);
+    const proof = body.proof ?? body;
+    out(Boolean(values.json), body, () => {
+        const paid = Boolean(proof.paid_out_at);
+        console.log(`  ${BOLD}${proof.id ?? proofId}${RESET}  ${DIM}${proof.status ?? ""}${RESET}`);
+        console.log(`  ${paid ? GREEN + "PAID" : YELLOW + "NOT PAID"}${RESET}  ${DIM}${paid ? String(proof.paid_out_at) : "approved is not paid — paid_out_at is the only field that means the USDC moved"}${RESET}`);
+        if (proof.private_note_locked) {
+            console.log(`      ${DIM}private note: stored and sealed (opens on payout)${RESET}`);
+        }
+        else if (typeof proof.private_note === "string" && proof.private_note) {
+            console.log(`      ${DIM}private note:${RESET} ${short(proof.private_note, 160)}`);
+        }
+        else {
+            console.log(`      ${DIM}private note: none was attached${RESET}`);
+        }
+        console.log("");
+        console.log(`${DIM}A link inside the note is presigned at read time and expires in an hour — re-fetch each time you want the file.${RESET}`);
     });
 }
 async function cmdMine(auth, values) {
@@ -658,12 +1151,16 @@ function options() {
         title: { type: "string" },
         subtext: { type: "string" },
         registry: { type: "boolean" },
+        funded: { type: "boolean" },
         name: { type: "string" },
         invite: { type: "string" },
         wallet: { type: "string" },
         count: { type: "string" },
         mailbox: { type: "string" },
-        note: { type: "string" }
+        note: { type: "string" },
+        "private-note": { type: "string" },
+        "clean-master": { type: "string" },
+        prefix: { type: "string" }
     };
 }
 export async function runGigsCommand(argv) {
@@ -691,14 +1188,23 @@ export async function runGigsCommand(argv) {
         case "pass": return cmdReview(auth, values, rest, "reject");
         case "ring-bell":
         case "bell": return cmdRingBell(auth, values);
+        case "earn":
+        case "start": return cmdEarn(auth, values);
         case "work":
         case "available": return cmdWork(auth, values);
+        case "check":
+        case "funds": return cmdCheck(auth, values, rest);
         case "feed": return cmdFeed(auth, values);
         case "join-feed": return cmdJoinFeed(auth, values);
         case "join": return cmdJoin(auth, values, rest);
         case "claim":
         case "poll": return cmdClaim(auth, values, rest);
         case "submit": return cmdSubmit(auth, values, rest);
+        case "proof": return cmdProof(auth, values, rest);
+        case "upload": return cmdUpload(auth, values, rest);
+        case "earnings":
+        case "rollups":
+        case "paid": return cmdEarnings(auth, values);
         case "mine":
         case "mailboxes": return cmdMine(auth, values);
         default: