cursedbelt-server 4.42.0 → 4.43.1

package/dist/server/youtube/ytdlp.js

@@ -0,0 +1,334 @@
+/**
+ * `cursedbelt-server/youtube/ytdlp` — run yt-dlp on the Mac and hand back the file it made.
+ *
+ * ── Why it is here (forge task 2349) ────────────────────────────────────────────────────
+ * Music downloads the owner's YouTube playlists as AUDIO (task 2348) and Collections downloads
+ * them as VIDEO (task 2349). Both runners were the same machine with a different `-f`: spawn
+ * yt-dlp, read its progress off a marker line, sort a failure by what fixes it, install the
+ * binary when it is missing and update it when YouTube has moved on. So that machine is here,
+ * once, and each app hands it a {@link YtDlpProfile} — the format, the size ceiling, the noun
+ * its sentences use — plus the one command that installs or updates yt-dlp from that app.
+ *
+ * What is NOT here, on purpose: where the binary lives (each app passes `binary`, normally
+ * {@link ytDlpPath} of the generation's state root), what a downloaded file becomes (Music files
+ * a track; Collections ingests a video), and any re-encode (only Collections has one, and only
+ * when no H.264 stream exists).
+ *
+ * ── The file stays on disk ──────────────────────────────────────────────────────────────
+ * A download resolves to a PATH inside a fresh temporary directory, and the caller disposes of
+ * it. A 1080p video is gigabytes, and reading it into memory to hand it over would make the
+ * agent's footprint the size of the largest video in a playlist. Music, whose files are a few
+ * MB, reads the bytes and disposes at once.
+ *
+ * ── Self-healing in the two ways that need no owner ─────────────────────────────────────
+ * A missing binary is installed before the first run, and a failure that reads as "this
+ * yt-dlp is out of date" updates it (at most once an hour) and tries again. What is left after
+ * that is a sentence that NAMES the fix — "yt-dlp is out of date … Run: cd … && bun run yt-dlp".
+ *
+ * YouTube's JS challenges need a JavaScript runtime and yt-dlp enables only Deno by default,
+ * so it is handed the Bun running this process — which it supports — rather than a second
+ * runtime installed for one tool.
+ *
+ * 🔴 Mac-only. It spawns a process and writes files; nothing a Worker mounts may import it.
+ * It imports `node:*` and nothing else, which `leafSubpathsImportNothing.spec.ts` holds it to.
+ */
+import { spawn } from "node:child_process";
+import { chmod, mkdir, mkdtemp, rename, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+/** Where the standalone build is published. `latest` always names the newest release. */
+const YTDLP_RELEASE_URL = "https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp_macos";
+/** The markers this module asks yt-dlp to print, so its own chatter can never be mistaken for them. */
+const PROGRESS_MARK = "ytprogress ";
+const INFO_MARK = "ytinfo ";
+/**
+ * A download that failed and was tried again. yt-dlp answers an intermittent `403` on the
+ * media request (measured 2026-09-30: one in three identical runs), and a retry is the fix.
+ */
+const ATTEMPTS = 3;
+/** How often a fetcher may update yt-dlp by itself. A release that does not fix it will not
+ *  start fixing it on the tenth try. */
+const SELF_UPDATE_EVERY_MS = 60 * 60_000;
+/** `$STATE/bin/yt-dlp` — one binary for every app on the Mac. `state` is the generation's state root. */
+export function ytDlpPath(state) {
+    return join(state, "bin", "yt-dlp");
+}
+/** yt-dlp's cache (the player JS it has already solved), kept with the generation's state. */
+export function ytDlpCacheDir(state) {
+    return join(state, "cache", "yt-dlp");
+}
+export class YtDlpError extends Error {
+    kind;
+    constructor(message, kind) {
+        super(message);
+        this.kind = kind;
+        this.name = "YtDlpError";
+    }
+}
+/** A failure no retry and no update can change — the video's own fault, or the ceiling. */
+export const isFinalYtDlpFailure = (kind) => kind === "unavailable" || kind === "too-big";
+// ── Pure: reading what yt-dlp prints ───────────────────────────────────────────────────
+/**
+ * One progress line, as a fraction — or `null` for any other line.
+ *
+ * The template prints `downloaded total estimate`, and yt-dlp writes `NA` for a field it does
+ * not know. The exact total wins; the estimate is what a stream without a `content-length`
+ * has. With neither there is no honest fraction, so none is claimed.
+ */
+export function parseYtProgress(line) {
+    if (!line.startsWith(PROGRESS_MARK))
+        return null;
+    const [downloaded, total, estimate] = line.slice(PROGRESS_MARK.length).trim().split(/\s+/).map(Number);
+    const whole = Number.isFinite(total) && total > 0 ? total : estimate;
+    if (!Number.isFinite(downloaded) || !Number.isFinite(whole) || whole <= 0)
+        return null;
+    return Math.min(Math.max(downloaded / whole, 0), 1);
+}
+/** The info JSON printed after the file is in place, or `null` for any other line. */
+export function parseYtInfo(line) {
+    if (!line.startsWith(INFO_MARK))
+        return null;
+    try {
+        const value = JSON.parse(line.slice(INFO_MARK.length));
+        return value && typeof value === "object" && typeof value.id === "string" ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** yt-dlp's last `ERROR:` line — the one that says why — or the stderr's last line. */
+function lastYtDlpError(stderr) {
+    const lines = stderr
+        .split("\n")
+        .map((l) => l.trim())
+        .filter(Boolean);
+    const errors = lines.filter((l) => l.startsWith("ERROR:"));
+    return (errors.at(-1) ?? lines.at(-1) ?? "").replace(/^ERROR:\s*/, "");
+}
+const UNAVAILABLE = /video unavailable|this video is unavailable|private video|has been removed|no longer available|account associated with this video has been terminated|not available in your country|blocked it in your country|members[- ]only|join this channel|confirm your age|age-restricted|copyright/i;
+const BLOCKED = /confirm you.?re not a bot|sign in to confirm|too many requests|http error 429/i;
+const OUTDATED = /unable to extract|nsig|n challenge|signature (extraction|function)|precondition check failed|http error 403|requested format is not available|please report this issue|js challenge|player .*(response|js)|unsupported url|jsc/i;
+const TOO_BIG = /larger than max-filesize|max-filesize/i;
+/** Sort a failure by what can be done about it — see {@link YtDlpFailure}. */
+export function classifyYtDlpFailure(stderr) {
+    const line = lastYtDlpError(stderr);
+    if (TOO_BIG.test(line))
+        return "too-big";
+    if (UNAVAILABLE.test(line))
+        return "unavailable";
+    if (BLOCKED.test(line))
+        return "blocked";
+    if (OUTDATED.test(line))
+        return "outdated";
+    return "failed";
+}
+/** The sentence a downloads table shows. Every kind that has a remedy NAMES it. */
+function describeYtDlpFailure(kind, detail, context) {
+    const fix = context.fixCommand;
+    switch (kind) {
+        case "missing":
+            return `yt-dlp is not installed on the Mac and installing it failed (${detail}). Run: ${fix}`;
+        case "outdated":
+            return (`yt-dlp could not read YouTube — it is out of date for a change YouTube made (${detail}). ` +
+                (context.updated
+                    ? `The agent already updated it and it still fails, so the fix is not released yet; try again in a day, or run: ${fix}`
+                    : `Run: ${fix}`));
+        case "blocked":
+            return `YouTube is refusing this Mac's requests as a bot (${detail}). It usually lifts within hours — try again later. If it persists, update yt-dlp: ${fix}`;
+        case "unavailable":
+            return `YouTube will not play this video to anyone signed out (${detail}), so there is nothing to download.`;
+        case "too-big":
+            return `${context.profile.noun} is over this app's ${context.profile.maxFilesize}B ceiling for one download.`;
+        default:
+            return `yt-dlp failed: ${detail || "no reason given"}. If YouTube links keep failing, update it: ${fix}`;
+    }
+}
+/** The arguments for one download. Exported so a test pins the flags that matter. */
+export function ytDlpArgs(videoId, outDir, profile, options = {}) {
+    return [
+        ...(options.jsRuntime ? ["--js-runtimes", `bun:${options.jsRuntime}`] : []),
+        ...(options.cacheDir ? ["--cache-dir", options.cacheDir] : []),
+        "--no-playlist",
+        "-f",
+        profile.format,
+        ...(profile.extraArgs ?? []),
+        "--max-filesize",
+        profile.maxFilesize,
+        "--no-part",
+        "--no-mtime",
+        "--no-colors",
+        "--newline",
+        // `--print` implies `--quiet`, which would swallow the progress lines — hence `--progress`.
+        "--progress",
+        "--progress-template",
+        `download:${PROGRESS_MARK}%(progress.downloaded_bytes)s %(progress.total_bytes)s %(progress.total_bytes_estimate)s`,
+        "--print",
+        `after_move:${INFO_MARK}%()j`,
+        "-o",
+        join(outDir, "%(id)s.%(ext)s"),
+        "--",
+        `https://www.youtube.com/watch?v=${videoId}`,
+    ];
+}
+const runLines = (binary, args, onLine) => new Promise((resolve, reject) => {
+    const child = spawn(binary, args, { stdio: ["ignore", "pipe", "pipe"] });
+    let buffer = "";
+    let stderr = "";
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+        buffer += chunk;
+        let at = buffer.indexOf("\n");
+        while (at >= 0) {
+            onLine(buffer.slice(0, at).replace(/\r$/, ""));
+            buffer = buffer.slice(at + 1);
+            at = buffer.indexOf("\n");
+        }
+    });
+    child.stderr.setEncoding("utf8");
+    child.stderr.on("data", (chunk) => {
+        // The tail is the part that says why; a runaway stderr must not grow without bound.
+        stderr = (stderr + chunk).slice(-16_384);
+    });
+    child.on("error", reject);
+    child.on("close", (code) => {
+        if (buffer)
+            onLine(buffer);
+        resolve({ code: code ?? 1, stderr });
+    });
+});
+/**
+ * Put the newest standalone build at `binary`. Written beside it and renamed into place, so a
+ * download that dies halfway never leaves a truncated executable where a fetcher looks.
+ */
+export async function installYtDlp(binary, fetchImpl = fetch) {
+    const res = await fetchImpl(YTDLP_RELEASE_URL, { redirect: "follow", signal: AbortSignal.timeout(120_000) });
+    if (!res.ok)
+        throw new Error(`GitHub answered ${res.status} for ${YTDLP_RELEASE_URL}`);
+    const bytes = new Uint8Array(await res.arrayBuffer());
+    // The standalone build is a Mach-O executable; anything small is an error page.
+    if (bytes.length < 1_000_000)
+        throw new Error(`the download was ${bytes.length} bytes, not a yt-dlp build`);
+    await mkdir(dirname(binary), { recursive: true });
+    const partial = `${binary}.partial`;
+    await writeFile(partial, bytes);
+    await chmod(partial, 0o755);
+    await rename(partial, binary);
+}
+/** `yt-dlp -U` — the standalone build updates itself in place. Resolves to what it printed. */
+export async function updateYtDlp(binary, run = runLines) {
+    const lines = [];
+    const { code, stderr } = await run(binary, ["-U"], (line) => lines.push(line));
+    const said = [...lines, ...stderr.split("\n")].map((l) => l.trim()).filter(Boolean);
+    if (code !== 0)
+        throw new Error(said.at(-1) ?? `yt-dlp -U exited ${code}`);
+    return said.at(-1) ?? "";
+}
+/**
+ * Install yt-dlp when it is missing, else update it — the body of each app's `bun run yt-dlp`.
+ * Resolves to the sentence to print.
+ */
+export async function installOrUpdateYtDlp(binary) {
+    if (!(await isFile(binary))) {
+        await installYtDlp(binary);
+        return `installed the latest release at ${binary}`;
+    }
+    return updateYtDlp(binary);
+}
+const isFile = async (path) => {
+    try {
+        return (await stat(path)).isFile();
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * The fetcher an app's download agent is handed. See the header for what it heals by itself
+ * and what it leaves as a sentence.
+ */
+export function createYtDlp(options) {
+    const run = options.run ?? runLines;
+    const install = options.install ?? ((binary) => installYtDlp(binary));
+    const update = options.update ?? ((binary) => updateYtDlp(binary, run));
+    const now = options.now ?? Date.now;
+    const label = options.label ?? "[yt-dlp]";
+    const jsRuntime = options.jsRuntime ?? (process.versions.bun ? process.execPath : undefined);
+    let lastUpdate = Number.NEGATIVE_INFINITY;
+    const describe = (kind, detail, updated) => describeYtDlpFailure(kind, detail, { updated, fixCommand: options.fixCommand, profile: options.profile });
+    const ensureInstalled = async () => {
+        if (await isFile(options.binary))
+            return;
+        options.log?.(`${label} yt-dlp: not at ${options.binary} — installing the latest release`);
+        try {
+            await install(options.binary);
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            throw new YtDlpError(describe("missing", detail, false), "missing");
+        }
+    };
+    /** One yt-dlp run into a fresh directory. Throws a classified error on failure. */
+    const attempt = async (videoId, onProgress) => {
+        const dir = await mkdtemp(join(options.tmpRoot ?? tmpdir(), "ytdlp-"));
+        const dispose = () => rm(dir, { recursive: true, force: true });
+        try {
+            let info = null;
+            const { code, stderr } = await run(options.binary, ytDlpArgs(videoId, dir, options.profile, {
+                ...(options.cacheDir ? { cacheDir: options.cacheDir } : {}),
+                ...(jsRuntime ? { jsRuntime } : {}),
+            }), (line) => {
+                const fraction = parseYtProgress(line);
+                if (fraction !== null)
+                    onProgress?.(fraction);
+                info = parseYtInfo(line) ?? info;
+            });
+            const found = info;
+            if (code !== 0 || !found?.filepath) {
+                const kind = code === 0 ? "failed" : classifyYtDlpFailure(stderr);
+                throw new YtDlpError(code === 0 ? "yt-dlp finished without saying where the file went" : lastYtDlpError(stderr), kind);
+            }
+            if (!(await isFile(found.filepath)))
+                throw new YtDlpError(`yt-dlp named ${found.filepath} and it is not there`, "failed");
+            const extension = (found.ext || found.filepath.split(".").at(-1) || "bin").toLowerCase();
+            return { path: found.filepath, extension, info: found, dir, dispose };
+        }
+        catch (error) {
+            await dispose();
+            throw error;
+        }
+    };
+    return async (videoId, onProgress) => {
+        await ensureInstalled();
+        let updated = false;
+        let last = null;
+        for (let tries = 1; tries <= ATTEMPTS + 1; tries++) {
+            try {
+                return await attempt(videoId, onProgress);
+            }
+            catch (error) {
+                last =
+                    error instanceof YtDlpError ? error : new YtDlpError(error instanceof Error ? error.message : String(error), "failed");
+                if (isFinalYtDlpFailure(last.kind))
+                    break;
+                if (tries < ATTEMPTS)
+                    continue;
+                // Out of plain retries. One more, after an update, if it reads as out of date.
+                if (last.kind === "outdated" && !updated && now() - lastUpdate >= SELF_UPDATE_EVERY_MS) {
+                    lastUpdate = now();
+                    try {
+                        const said = await update(options.binary);
+                        updated = true;
+                        options.log?.(`${label} yt-dlp: updated after "${last.message}" — ${said}`);
+                        continue;
+                    }
+                    catch (updateError) {
+                        options.log?.(`${label} yt-dlp: update failed — ${updateError instanceof Error ? updateError.message : String(updateError)}`);
+                    }
+                }
+                break;
+            }
+        }
+        const failure = last ?? new YtDlpError("no attempt ran", "failed");
+        throw new YtDlpError(describe(failure.kind, failure.message, updated), failure.kind);
+    };
+}

package/docs/ctgr.md

@@ -0,0 +1,24 @@
+# ctgr + getOnly — the server invariants (don't reinvent the transport)
+
+This package owns the GET-tunnel ("ctgr") and the auth guards (`src/server/ctgr.ts`,
+`src/server/ctgrTunnel.ts`, `src/server/middleware/`). Use the primitives; do
+not re-implement the wiring per app or per route.
+
+- **Register routes with `buildRoutes`.** One `register(method, path, ...handlers)` call wires
+  both the real verb route **and** its `/ctgr<XX>` GET twin from a single call. Don't register
+  the twin by hand.
+- **Mount the decode middleware on `CTGR_ROUTE_PATTERN`**, never on a literal `/ctgr*`. Hono's
+  router does **not** treat `/ctgr*` as a prefix wildcard (a bare-suffix `*` matches only one
+  following segment) — `CTGR_ROUTE_PATTERN` (`/:ctgrTwin{ctgr.+}`) is the correct portable
+  matcher. Reuse it everywhere a `/ctgr*` mount is meant.
+- **`unGETify` only decodes** — it turns a `/ctgr<XX>` twin's query params back into the
+  original request and stashes the decoded request/method on the context. Protection lives
+  elsewhere by design:
+  - **getOnly** keys off the **RAW** request method (always `GET` on a twin) in the auth
+    middleware — that's what makes a tunneled write safe.
+  - **CSRF** double-submit fires on **every** `/ctgr*` path.
+- **Binary/download routes MUST NOT go through the tunnel.** Register those as a plain
+  `app.get(path, handler)` so their bytes never ride the base64url codec and get mangled.
+
+Moved here from `cursedbelt/docs/STANDARDS.md` §5 on 2026-10-05: it described this package's
+server tier, which `cursedbelt` stopped shipping at the 2026-09-15 split.

package/docs/skipped-tests.md

@@ -7,13 +7,13 @@ carrying one goes red until it is removed. Inherited from `cursedbelt` at the
 
 | file | waiting for |
 | --- | --- |
-| `src/server/search/pgSearchProvider.pg.test.ts` | 24 | 22 | 2026-09-13 |
-| `src/server/storage/transcode.integration.spec.ts` | 7 | 5 | 2026-09-13 |
-| `src/server/storage/binaryServerProcessing.integration.spec.ts` | 4 | 2 | 2026-09-13 |
-| `src/server/storage/chunked.integration.spec.ts` | 3 | 1 | 2026-09-13 |
-| `src/server/media-bun/image.spec.ts` | the optional `sharp` peer | no |
-| `src/server/media-bun/video.spec.ts` | `ffmpeg` + `ffprobe` on `PATH` | no |
-| `src/server/storage/imageThumbnail.spec.ts` | `ffmpeg` on `PATH` | no |
-| `src/server/storage/videoProcessor.posterOnly.spec.ts` | `ffmpeg` on `PATH` | no |
-| `src/server/storage/files/adapter.photo.display.spec.ts` | `ffmpeg` on `PATH` | no |
-| `src/server/storage/fileUploadClient-chunked.integration.spec.ts` | a real `binary-server` checkout — set `BINARY_SERVER_DIR`. No default by design: a published package must not go looking in one machine's directory layout, and `binary-server` has not been re-homed into this generation, so it skips on every host today. Moved here from `cursedbelt` at the 2026-09-15 split, with the storage internals it drives. |
+| `src/server/search/pgSearchProvider.pg.test.ts` | `CC_PG_URL` naming a throwaway Postgres | `bun run test:pg` supplies one |
+| `src/server/storage/transcode.integration.spec.ts` | a real `binary-server` checkout — set `BINARY_SERVER_DIR`. It starts binary-server's processing worker beside the store, because only the worker runs a job |
+| `src/server/storage/binaryServerProcessing.integration.spec.ts` | a real `binary-server` checkout (`BINARY_SERVER_DIR`) and `ffmpeg` on `PATH`. It starts the processing worker too |
+| `src/server/storage/chunked.integration.spec.ts` | a real `binary-server` checkout — set `BINARY_SERVER_DIR` |
+| `src/server/media-bun/image.spec.ts` | the optional `sharp` peer |
+| `src/server/media-bun/video.spec.ts` | `ffmpeg` + `ffprobe` on `PATH` |
+| `src/server/storage/imageThumbnail.spec.ts` | `ffmpeg` on `PATH` |
+| `src/server/storage/videoProcessor.posterOnly.spec.ts` | `ffmpeg` on `PATH` |
+| `src/server/storage/files/adapter.photo.display.spec.ts` | `ffmpeg` on `PATH` |
+| `src/server/storage/fileUploadClient-chunked.integration.spec.ts` | a real `binary-server` checkout — set `BINARY_SERVER_DIR` to its path (`apps/binary-server` in this generation). No default by design: a published package must not go looking in one machine's directory layout. Moved here from `cursedbelt` at the 2026-09-15 split, with the storage internals it drives. |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-server",
-	"version": "4.42.0",
+	"version": "4.43.1",
 	"license": "ISC",
 	"type": "module",
 	"description": "The app-facing Bun/Hono server tier of the cursedbelt split — storage, sharing, activity, guard, sync. React-free; cursedbelt-core below it.",
@@ -343,6 +343,18 @@
 			"source": "./src/server/sync/index.ts",
 			"import": "./dist/server/sync/index.js"
 		},
+		"./youtube": {
+			"types": "./dist/server/youtube/youtubeApi.d.ts",
+			"bun": "./src/server/youtube/youtubeApi.ts",
+			"source": "./src/server/youtube/youtubeApi.ts",
+			"import": "./dist/server/youtube/youtubeApi.js"
+		},
+		"./youtube/ytdlp": {
+			"types": "./dist/server/youtube/ytdlp.d.ts",
+			"bun": "./src/server/youtube/ytdlp.ts",
+			"source": "./src/server/youtube/ytdlp.ts",
+			"import": "./dist/server/youtube/ytdlp.js"
+		},
 		"./ws": {
 			"types": "./dist/server/ws/index.d.ts",
 			"bun": "./src/server/ws/index.ts",
@@ -353,7 +365,7 @@
 	"dependencies": {
 		"argon2id": "1.0.1",
 		"cursedbelt-core": "^2.1.1",
-		"cursedops": ">=0.8.1 <0.14.0",
+		"cursedops": ">=0.8.1 <1.0.0",
 		"cwip": "^4.6.0",
 		"jose": "^6.2.3"
 	},

package/src/cursedopsRange.spec.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'bun:test';
+import pkg from '../package.json';
+
+/**
+ * `cursedops` is a dependency here, so an app that takes a cursedops this range does not admit
+ * installs TWO copies — the app's at the top and a nested one under `cursedbelt-server`. The
+ * range used to stop at the next 0.x minor (`<0.10.0`, `<0.12.0`, `<0.13.0`, `<0.14.0`), and every
+ * cursedops minor needed a hand-widening here before the ship could bump apps onto it with one
+ * copy (4.30.1, 4.40.3, 4.40.4, and again for cursedops 0.14.0 — forge task 2832). All this
+ * package takes from it is `forgeState` from `cursedops/roots`, and `tools/publish-libs.sh`'s
+ * consumer preflight runs every app on a new cursedops before it ships, so the cap bought nothing
+ * but the chore. It is gone; this keeps it gone for the whole 0.x line.
+ */
+describe('cursedops range', () => {
+	const range = pkg.dependencies.cursedops;
+
+	it('admits every later cursedops 0.x minor, so an app bumping cursedops keeps one copy', () => {
+		for (const version of ['0.14.0', '0.15.0', '0.20.3', '0.99.0']) {
+			expect({ version, admitted: Bun.semver.satisfies(version, range) }).toEqual({ version, admitted: true });
+		}
+	});
+
+	it('still refuses what predates forgeState', () => {
+		expect(Bun.semver.satisfies('0.8.0', range)).toBe(false);
+	});
+});

package/src/leafSubpathsImportNothing.spec.ts

@@ -225,6 +225,24 @@ const LEAVES = [
     evaluates: 'argon2Cost',
     siblings: ['src/server/satellite/door.ts'],
   },
+  {
+    subpath: './youtube',
+    /**
+     * The YouTube Data API reader (4.43.0, forge task 2349) — out of Music so Collections lists
+     * the same playlists. Collections calls it from a Worker, so it may reach nothing but
+     * `fetch`; its one import is `import type` of `./google-oauth`'s `FetchLike`, which is erased.
+     */
+    evaluates: 'createYouTubeApi',
+  },
+  {
+    subpath: './youtube/ytdlp',
+    /**
+     * The yt-dlp runner (4.43.0, forge task 2349) shared by Music's audio and Collections' video
+     * agents. Mac-only, and its promise is `node:*` and nothing else — no `cursedops`, so the
+     * caller says where the binary is.
+     */
+    evaluates: 'createYtDlp',
+  },
 ] as const;
 
 /**

package/src/server/storage/binaryServerProcessing.integration.spec.ts

@@ -1,4 +1,5 @@
 import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import type { Subprocess } from 'bun';
 import { existsSync, mkdirSync } from 'node:fs';
 import { mkdtemp, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
@@ -19,7 +20,11 @@ const FFMPEG_PRESENT = Bun.which('ffmpeg') !== null;
 
 // SKIPPED until a real binary-server checkout is present: point BINARY_SERVER_DIR at one.
 // There is deliberately no default — a published package must not go looking in one machine's
-// directory layout — and `binary-server` has not been re-homed here, so this skips on every host today.
+// directory layout. In this generation that checkout is `$FORGE/apps/binary-server`.
+// BS_ALLOW_NEW_STORE=1: the spawned server refuses to invent a store it was not given, and this
+// throwaway one is exactly a store it should create.
+// BS_SECRETS_FILE=/dev/null: otherwise it folds in this machine's binary-server.env — the real R2
+// keys and passcode — and a throwaway store has no business holding them.
 // ffmpeg must be on PATH too: the proof is that the REMOTE side runs real ffmpeg, not that the client posted a job.
 describe.skipIf(!BS_PRESENT || !FFMPEG_PRESENT)(
   'binaryServerProcessing → real binary-server (integration)',
@@ -27,6 +32,7 @@ describe.skipIf(!BS_PRESENT || !FFMPEG_PRESENT)(
     let port: number;
     let storeDir: string;
     let server: TestServer | null = null;
+    let worker: Subprocess | null = null;
     let tmpData: string;
     const INTERNAL_SECRET = 'test-processing-secret';
     const APP = 'ptest';
@@ -36,21 +42,33 @@ describe.skipIf(!BS_PRESENT || !FFMPEG_PRESENT)(
       storeDir = path.join(tmpData, 'binaries');
       mkdirSync(storeDir, { recursive: true });
       port = await pickFreePort();
+      const env = {
+        PORT: String(port),
+        HOST: '127.0.0.1',
+        STORAGE_ROOT: storeDir,
+        DB_PATH: path.join(tmpData, 'test.sqlite'),
+        BS_ALLOW_NEW_STORE: '1',
+        BS_SECRETS_FILE: '/dev/null',
+        INTERNAL_SECRET,
+        NODE_ENV: 'test',
+      };
       server = await startTestServer({
         cwd: BS_DIR,
         cmd: ['bun', path.join(BS_DIR, 'src', 'index.ts')],
         port,
-        env: {
-          PORT: String(port),
-          HOST: '127.0.0.1',
-          STORAGE_ROOT: storeDir,
-          DB_PATH: path.join(tmpData, 'test.sqlite'),
-          INTERNAL_SECRET,
-          NODE_ENV: 'test',
-        },
+        env,
         healthPath: '/healthz',
         timeoutMs: 90_000,
       });
+      // The store only ENQUEUES a job; binary-server's processing worker (its own process since
+      // bs task 2694) leases and runs it, and writes each output back through the store's API.
+      // Without one, every job stays `pending` and the client times out.
+      worker = Bun.spawn(['bun', path.join(BS_DIR, 'src', 'processingWorker.ts')], {
+        cwd: BS_DIR,
+        env: { ...process.env, ...env },
+        stdout: 'inherit',
+        stderr: 'inherit',
+      });
 
       // Register the tenant, the way `register-app` does for a real one. This is
       // not harness ceremony: since binary-server started INDEXING every transcode
@@ -71,7 +89,7 @@ describe.skipIf(!BS_PRESENT || !FFMPEG_PRESENT)(
         ],
         {
           cwd: BS_DIR,
-          env: { ...process.env, STORAGE_ROOT: storeDir, DB_PATH: path.join(tmpData, 'test.sqlite') },
+          env: { ...process.env, STORAGE_ROOT: storeDir, DB_PATH: path.join(tmpData, 'test.sqlite'), BS_ALLOW_NEW_STORE: '1', BS_SECRETS_FILE: '/dev/null' },
           stdout: 'inherit',
           stderr: 'inherit',
         },
@@ -80,6 +98,8 @@ describe.skipIf(!BS_PRESENT || !FFMPEG_PRESENT)(
     }, 90_000);
 
     afterAll(async () => {
+      worker?.kill();
+      await worker?.exited;
       await server?.stop();
       await rm(tmpData, { recursive: true, force: true }).catch(() => void 0);
     });
@@ -97,7 +117,7 @@ describe.skipIf(!BS_PRESENT || !FFMPEG_PRESENT)(
       `;
       const proc = Bun.spawn(['bun', '-e', helper, `${APP}/${key}`, localFile], {
         cwd: BS_DIR,
-        env: { ...process.env, STORAGE_ROOT: storeDir, DB_PATH: path.join(tmpData, 'test.sqlite') },
+        env: { ...process.env, STORAGE_ROOT: storeDir, DB_PATH: path.join(tmpData, 'test.sqlite'), BS_ALLOW_NEW_STORE: '1', BS_SECRETS_FILE: '/dev/null' },
         stdout: 'inherit',
         stderr: 'inherit',
       });

package/src/server/storage/chunked.integration.spec.ts

@@ -40,7 +40,11 @@ const pem = (der: ArrayBuffer, label: string) =>
 
 // SKIPPED until a real binary-server checkout is present: point BINARY_SERVER_DIR at one.
 // There is deliberately no default — a published package must not go looking in one machine's
-// directory layout — and `binary-server` has not been re-homed here, so this skips on every host today.
+// directory layout. In this generation that checkout is `$FORGE/apps/binary-server`.
+// BS_ALLOW_NEW_STORE=1: the spawned server refuses to invent a store it was not given, and this
+// throwaway one is exactly a store it should create.
+// BS_SECRETS_FILE=/dev/null: otherwise it folds in this machine's binary-server.env — the real R2
+// keys and passcode — and a throwaway store has no business holding them.
 describe.skipIf(!BS_PRESENT)('chunked upload → real binary-server (integration)', () => {
   let server: TestServer | null = null;
   let tmp = '';
@@ -83,7 +87,7 @@ describe.skipIf(!BS_PRESENT)('chunked upload → real binary-server (integration
         PORT: String(port),
         HOST: '127.0.0.1',
         STORAGE_ROOT: path.join(tmp, 'binaries'),
-        DB_PATH: path.join(tmp, 'bs.sqlite'),
+        DB_PATH: path.join(tmp, 'bs.sqlite'), BS_ALLOW_NEW_STORE: '1', BS_SECRETS_FILE: '/dev/null',
         FILE_TOKEN_PUBLIC_KEY: spki,
         FILE_TOKEN_ISSUER: ISSUER,
         CA_APP_ID: APP_ID,

package/src/server/storage/fileUploadClient-chunked.integration.spec.ts

@@ -50,7 +50,11 @@ const pem = (der: ArrayBuffer, label: string) =>
 
 // SKIPPED until a real binary-server checkout is present: point BINARY_SERVER_DIR at one.
 // There is deliberately no default — a published package must not go looking in one machine's
-// directory layout — and `binary-server` has not been re-homed here, so this skips on every host today.
+// directory layout. In this generation that checkout is `$FORGE/apps/binary-server`.
+// BS_ALLOW_NEW_STORE=1: the spawned server refuses to invent a store it was not given, and this
+// throwaway one is exactly a store it should create.
+// BS_SECRETS_FILE=/dev/null: otherwise it folds in this machine's binary-server.env — the real R2
+// keys and passcode — and a throwaway store has no business holding them.
 describe.skipIf(!BS_PRESENT)('fileUploadClient chunked path → real binary-server (integration)', () => {
   let server: TestServer | null = null;
   let tmp = '';
@@ -90,7 +94,7 @@ describe.skipIf(!BS_PRESENT)('fileUploadClient chunked path → real binary-serv
         PORT: String(port),
         HOST: '127.0.0.1',
         STORAGE_ROOT: path.join(tmp, 'binaries'),
-        DB_PATH: path.join(tmp, 'bs.sqlite'),
+        DB_PATH: path.join(tmp, 'bs.sqlite'), BS_ALLOW_NEW_STORE: '1', BS_SECRETS_FILE: '/dev/null',
         FILE_TOKEN_PUBLIC_KEY: spki,
         FILE_TOKEN_ISSUER: ISSUER,
         CA_APP_ID: APP_ID,