# Release 21 — playable archives: local media for held videos, WebTorrent playback on the sites

Written 2026-10-09. Pilot: the TISM (The Incredible Salt Mine) v1 torrent archive →
`the-incredible-salt-mine` (a Jeralyzer member channel). Two outcomes:

1. **Agents can clip TISM** — every held TISM video gets its media on disk, through the editor, so
   `fetch_clip` / `fetch-windows` / `reports prepare` / report-to-video cut it locally.
2. **Readers can play TISM** — the site plays the video in the transcript page (click-to-seek works) from a
   torrent. Nothing is hosted on Cloudflare: the bytes come from peers, and a home seeder behind a VPN is the
   **peer of last resort** — it seeds a torrent only while no other seeder has it.

## Rulings (operator, 2026-10-09)

- **Pilot on `jeralyzer-private` first**; public Jeralyzer is a later, separate ruling.
- **No web seed, no R2.** A **home seeder only**, behind a VPN, with an app layer that seeds a torrent only when no
  other seeder exists (peer of last resort). Accepted consequence: a torrent with no other seeder plays only while
  the home seeder is up.
- **ASR for the 3 new videos only** (`pnpm ops transcribe-one`); the other 161 keep their YouTube captions.
- *Open:* the attribution line for the archived copy on the video page (the archive's README names its maker and
  sources). Records state facts; the wording is the operator's.

## What is there (measured 2026-10-09)

| | |
|---|---|
| Archive | `<archive drive>/v1-torrent/`: `Uploads/YouTube.zip` (36.5 GB, **stored**, 183 folders), `SoundCloud.7z` (2 mp3: TISM001/002), `3rd-party-Odysee.7z` (2 mp4, solid LZMA2), `Images.7z`, `Official-page-archives.7z`, `README-v1.html` |
| YouTube.zip folders | 183: **169 with media** (36.4 GB, **222.7 h**), 10 `[LOST]` (source.txt only), 4 others without media; 33 carry an archive.org `youtube-<id>_archive.torrent`; each folder has yt-dlp `.info.json`/`.description`/thumbnail, or `description.txt` + `source.txt` |
| Codecs (ffprobe, in place) | 124 mp4 h264/aac with the **moov at the back**, 21 mp4 h264/aac faststart, 9 webm vp9/opus, 11 mkv vp9/aac, 2 mkv h264/opus, 1 mp4 av1/aac, 1 mkv av1/opus. Heights: 109×360p, 35×720p, 21×1080p, 4×144p |
| Corpus | `the-incredible-salt-mine` (handling youtube, the channel is deleted): 171 videos, each `metadata.info.json` + cues (161 YouTube VTT, 10 `transcript.json`), **no media**. All 171 ids are in the archive. 3 archive videos with media are **not held**: `6ijPdSuZdws`, `VcFA_LOnQoc`, `xLgf_MGQzXk` |
| Disk | the archive drive has 849 GB free; the saved-video store already lives on it (`archilyzer-media/saved-videos`) |

## Gaps in the code (verified)

- **No local-file ingest.** Every import takes a URL or an archive.org identifier (`import-one`,
  `import-archive-org`); `sourceKind` is `video | social`. Only the downloader attaches a container to a held
  record (`persistSourceVideo`, `common/lib/savedVideo-server.ts:102`).
- **A clip window never reads a saved container.** `fetchWindowAction`
  (`editor/app/channels/[slug]/videos/[id]/videoActions.ts`, ~1080) asks `findContainingClipWindow`, then the
  network; only `full: true` returns the saved container (~1259), and only `evidenceClip-server.ts` (reports
  prepare, report-to-video) cuts from it. For a deleted channel, a window request fails every time today.
- **The sites already play files and seek**: every player behind `PlayerProvider.tsx` exposes `seekTo`, and cue
  rows call it (`TranscriptModal.tsx` `CueRow`), so click-to-seek needs nothing new.
- **No torrent code beyond archive.org ingest** (aria2c, `archiveOrgTorrent*.ts`). No WebTorrent anywhere.
- **The export site ships a root-scope service worker** (`export/service-worker/site-sw.js`). WebTorrent 2's
  browser streaming needs a service worker (`client.createServer({ controller })`), so the two must be one worker.
  The site sends no CSP, so wss trackers and blob media are not blocked.

## Slices

### D1 — attach local media to held videos `[unit]` (clippability; nothing public)

- `common/controller/attachMedia.ts` + job kind `attach-media` (drainable, `needsMedia`), ops action
  `attach-media {slug, source, items?:[{id, path}], match?, createRecords?, dryRun?}`, CLI `archilyzer media attach`.
- **Sources:** a directory, or a **zip read in place** (a stored entry is copied straight out, no temp dir; a
  deflated or 7z entry is extracted to a scratch dir on the target disk first). The id comes from the folder's
  trailing `(<11-char id>)`, else the media file's `-<id>.` suffix, else an explicit item. `dryRun` lists matched,
  unmatched, already attached, not held and `[LOST]`.
- **Writes** through `persistSourceVideo` (the one writer): the container into the saved-video store as
  `source-media.<ext>`, `keepReason: "pin"`, a new `origin: {kind: "local-archive", archive, entry, sha256,
  attachedAt}` (which archive, which entry, its hash). Refuses over an existing pointer unless `replace`; never
  modifies the archive. Guards: `assertSavedVideosStoreWritable`, the media-reachable guard.
- **Not held** (the 3): `createRecords: true` writes `metadata.info.json` from the folder's yt-dlp `.info.json`
  (else from `description.txt`/`source.txt`, the title from the folder name), then `pnpm ops transcribe-one` for each.
- `[LOST]` folders are listed, never attached.

### D2 — clip windows cut from a saved container `[unit]` + `[spec ops-api]`

- In `fetchWindowAction`, after the clip-window cache and BEFORE the network: when the video has a saved container
  covering `[from − pad, to + pad]`, cut the window locally (evidenceClip's ffmpeg path), write it into
  `data/<id>/clips/` like a fetched window with provenance `{source: "saved-video"}`, and answer `cached: true`.
  `fetch-windows` batches then use no network for such videos. Helps every persisted video, not only TISM.
- `mcp/src/instructions.ts`: a video held locally is cut without a fetch.
- Starts after release 19's A5 merges (A5 edits the same fetch-window code: dedupe + queue key).

### D3 — streamable copies + torrents `[unit]`

- `common/lib/playableMedia.ts` picks a **lossless** remux (`-c copy`) per container: h264/vp9/av1 + aac/opus → mp4
  `+faststart`; vp9/av1 + opus in webm stays webm. 169 copies, ~36 GB, on the archive drive under
  `archilyzer-media/playable/<slug>/<id>/<id>.<ext>`, keyed by the source's sha256 (a re-run is a no-op).
- One **single-file torrent per video** (`create-torrent`, from the WebTorrent ecosystem): piece length scaled to the
  size (256 KiB–1 MiB), no `urlList`, `name` = `<id>.<ext>`, no `comment`/`createdBy` naming a person or a private
  URL. The announce list is not in the info dict, so the infohash depends only on the bytes. The pilot announces
  only to a **self-hosted tracker**, so nothing public learns the infohashes. Going public later means adding public
  WSS trackers (browsers) and UDP trackers (desktop clients) to the magnet: same infohash, no re-hash.
- Job kind `prepare-playable` (heavy: runs in release 19 B1's `pnpm heavy` slot once that lands).

### D4 — publish the torrents `[unit]`

- `site.json` gains `playable: { channels: string[], trackers: string[] }` (schema + SITE.md regenerated): the
  channels whose records carry a torrent, and the announce URLs that site's magnets name (the pilot: the
  self-hosted tracker only).
- The index stage writes `.export-index/sites/<id>/playable.json` (id → infohash, magnet, mime, bytes). The site's
  `inputSig` includes it, so adding a torrent makes the build stale. No media bytes leave the machine.
- Compose: records of a playable channel gain `playable: {magnet, infoHash, mime, bytes}` in the published JSON;
  each `.torrent` ships in the bundle (`/t/<id>.torrent`, ~170 small files, within the 15,000 cap).
  `corpus.json` / `llms.txt` name the field.

### D4b — the seeder: peer of last resort, behind a VPN `[unit]` + a manual network test

- `archilyzer seed`, a long-running node service: WebTorrent 2 in node, with WebRTC via `node-datachannel` so it
  serves browsers, and TCP/uTP for desktop clients. It seeds the playable manifests of the sites named in settings
  (`seeder: { sites, maxUploadKiBps, maxConnections, pollSeconds, standbyAfterSeconds }`, SETTINGS.md regenerated).
- **Last resort**, per torrent: the seeder polls the trackers' scrape (`complete`, minus itself) and its own peer
  view.
  - Other seeders present for `standbyAfterSeconds` → **standby**: stop announcing, close peers, keep the data.
  - No other seeder (`complete` = 0) while a leecher announces, or a connected leecher with no other source → resume.
  - Both edges have hysteresis, so it does not flap, and the log names each transition and why.
  - Known cost: if the last other seeder leaves mid-stream, the viewer stalls for up to `pollSeconds` until the
    seeder resumes.
- **Behind a VPN, with no way around it:** the seeder runs in its own network namespace or container whose only
  route is the VPN tunnel (a docker compose profile `seeder` with a WireGuard sidecar). Kill switch: tunnel down
  means no network, never the home connection. ICE gathers candidates only from the tunnel interface, so WebRTC
  never offers the home address (the classic WebRTC leak). `archilyzer doctor` reports the seeder's egress IP
  against the host's and refuses to call the seeder healthy if they match.
- **The risk to measure first:** whether the VPN's NAT lets browser peers connect directly (UDP hole punching).
  If it does not, the options are a VPN with port forwarding or a TURN relay. That is a ruling, not a default.
- Manual network test (recorded): a browser on another network plays a torrent through the seeder, and the
  seeder's candidates and the tracker's view of its address show only the VPN exit.

### D5 — the player `[unit]` + `[spec]` (export e2e)

- `common/components/TorrentPlayer.tsx`: WebTorrent 2 (npm, bundled, dynamically imported only on a playable record),
  `client.add(magnet)` → streamed into a native `<video>` through the service worker; the same
  `seekTo`/`onReady`/`onProgress` shape as `FilePlayer`.
- **One service worker:** `site-sw.js` gains WebTorrent's stream handler on its own path prefix (no second
  registration); sites with `pwa: false` register a minimal worker for it alone.
- **Choice rule in `PlayerProvider`:**
  - A playable record whose platform copy is gone (`isDeleted`/unavailable, as for all of TISM) plays the archived
    copy by default.
  - A record whose embed still works shows "Play archived copy".
  - There is no file fallback: with no peer after a timeout, the player says no one is seeding it right now and
    offers the magnet and `.torrent` ("seed this").
  - A status line shows peers and download rate.
- e2e: a fixture torrent (a few seconds of video) seeded by a node WebTorrent peer the export e2e starts, announced
  to a local tracker the e2e starts. Checks: it plays, a cue click seeks, and the no-peer state shows once the seed
  is stopped.

### D6 — the rest of the archive `[none]` → `[unit]`

- SoundCloud TISM001/002 (audio) and the two Odysee mirrors: a dryRun maps them to held episodes by title and
  duration; each is attached as alternate media or skipped, by operator ruling. `Official-page-archives.7z` and
  `Images.7z` are out of scope.

## Graph and order

```
D1 (attach) ──► D2 (window cut; after release 19 A5)        ← agents can clip TISM from here
D1 ──► D3 (copies + torrents) ──► D4 (publish torrents) ──► D5 (player) ──┐
                              └──► D4b (seeder + VPN) ─────────────────────┴► pilot on jeralyzer-private ──► public ruling
```

D1, D3 and D4b touch no file owned by tracks A/B/C and may start now. D2 waits for A5. D4 and D5 wait until release
19 merges (the ops routes, `_cli.ts`, the `site.json` schema docs).

## Record

### Track D

One Opus implementer, branch `worktree-agent-a4b4aebbb6c0d28bb` off `5bc20d32` (`r19/integration` with this plan),
`r19/integration` merged in before this record (`2e3a9395`: tracks B and C — the docs cli, the heavy slot). Slices
D1, D3, D4b, in that order; D2, D4, D5 are not this track's. Nothing ran against the real corpus or the real
archive beyond read-only listings of the archive's central directory (`unzip -l`, `zipinfo`, and the new zip
reader over it); every fixture is synthetic.

#### D1, as shipped — attach local media to held videos

**What was found before building.**
- The archive is ZIP64 (790 entries, 36.45 GB, every entry stored): its later offsets do not fit 32 bits. No zip
  library is in the workspace, so `common/lib/zipReader.ts` reads the central directory itself (EOCD, the ZIP64
  locator and record, the 0x0001 extra, the Info-ZIP Unicode-path extra) and copies a stored entry as a byte range
  of the archive, a deflated one through `inflateRaw`, checking the size and CRC32 against the central directory.
  Over the real archive (read-only) it lists the 790 entries and their byte total matches `zipinfo`'s exactly.
- One media file name in the archive is non-ASCII (a full-width `｜` and `？`); the folder's `(<id>)` names it.
- The archive's folder classes, from the listing alone (no corpus read): 182 folders with files, 169 with media,
  10 `[LOST]`, 2 with an id and no media, and the archive's root (no media, no id).
- `persistSourceVideo` MOVES `<videoDir>/<sourceFilename>`. Copying a 36 GB archive into the corpus SSD first would
  be the wrong disk twice, so it gains `sourcePath` (the file to move, a staging file beside the store dir on the
  store's disk — a same-filesystem rename) and `sha256` (recorded when the caller hashed while copying).
- Every consumer of `SavedVideoOrigin` reads `requestedBy` as required (the video page's "Requested by", the clip
  requester line in `videoActions.ts`, which this track may not touch). So the local-archive origin keeps
  `requestedBy: "attach-media"` and adds `kind: "local-archive"`, `archive`, `entry`, `sha256`, `attachedAt`;
  `parseOrigin` reads them only under that kind, and a pointer without `kind` parses exactly as before.
- The non-yt-dlp writer of `metadata.info.json` for a new record is `withMetadataHistory` around
  `writeJsonAtomic(…, {indent: 0, newline: false})`, as `archiveOrgDownload` writes its records; a new writer
  `local-archive` joins `METADATA_HISTORY_WRITERS`.

**What it does.** `common/lib/attachMediaPlan.ts` (pure): folders grouped by parent; the id from the folder's
trailing `(<11-char id>)`, else the file's `-<id>.`, ` [<id>].` or bare `<id>.`; classes `attach`, `create`,
`already-attached`, `not-held`, `lost`, `no-media`, `unmatched`, `ambiguous` (two video files in a folder, or two
folders claiming one id), plus the held videos no folder supplied (only when the whole archive was considered).
`common/controller/attachMedia.ts`: sources are a directory, a `.zip` read in place, or a `.7z` (listed with
`7z l -slt`, one entry extracted with `7z e -so -spd` into the staging file); the store's root must exist (an
unmounted drive is never materialised), `assertSavedVideosStoreWritable` before each copy, size plus 2 GiB free
on the store's disk or the run stops (a re-run resumes); drain and cancel between videos, a cancel aborts the copy
and removes its staging file; `keepReason: "pin"`; refuses over a pointer unless `replace` (a replaced container of
another name is removed after the new pointer is written). `createRecords` writes the folder's own yt-dlp
`.info.json` (refused when its `id` is another video's) or one built from `description.txt` ("Published on …" →
`upload_date`, last key) and the folder name, the duration from ffprobe, and appends `youtube <id>` to the
channel's `archive`. The log ends with `summary: {…}`. Job kind `attach-media` (drainable, `needsMedia`, an ingest
kind — its pointers and records are what the index reads; not replayable; the channel's queue). The action is
`editor/app/channels/[slug]/attachMediaActions.ts` (a new file); `POST /api/ops/attach-media` on the `_lib.ts`
precedent; one `ACTIONS` entry and one usage paragraph in `scripts/archilyzer-ops.mjs`; `archilyzer media attach
<slug> <source>` (offline; asks the channel's media guard itself).

#### D3, as shipped — playable copies and torrents

`common/lib/playableMedia.ts` (pure) is the decision table: h264/vp9/av1 with aac/opus/mp3 (or no audio) → mp4
`+faststart`; vp9/vp8/av1 with opus/vorbis in a `.webm` → webm with `-cues_to_front 1`; anything else (HEVC,
MPEG-4 Part 2, AC-3 audio, no video) is listed as not playable, never re-encoded. Only the first real video stream
(`0:V:0`, not cover art) and the first audio are kept; subtitles, data, global metadata and chapters are dropped;
`+bitexact`, so the same source remuxes to the same bytes (tested). The measured mix in this plan is every row of
the table's playable half. `common/controller/preparePlayable.ts`: copies, torrents and `playable.json` under
`playable/<slug>/<id>/` beside the saved-video store's real directory (or `root`); keyed by the source's sha256 (a
pointer with none is hashed once and the hash recorded on it), so a re-run with the files on disk at their size is
a no-op; each copy written to a `.part` and renamed; the manifest rewritten after each video. Each remux takes the
heavy slot (`scripts/queue-lock.mjs --heavy`, release 19 B1) per video, so a long run interleaves with builds and
e2e; a checkout without the gate runs ffmpeg directly. **The torrent:** `create-torrent` with `name` `<id>.<ext>`,
piece length a power of two in 256 KiB–1 MiB scaled to ~2,048 pieces, a fixed creation date, the announce list from
the `trackers` parameter (an explicit empty list, never create-torrent's default public trackers), and NOT passed:
`createdBy`, `comment`, `urlList`, `private` — even `private: false` would put `private: 0` inside the info dict and
move the infohash. Tested: same bytes and piece length → same infohash whatever the path or the trackers; another
piece length → another; the .torrent byte-identical across runs. Job kind `prepare-playable` (drainable,
`needsMedia`, ingest — D4's build reads the manifest; one `playable` queue machine-wide), `POST
/api/ops/prepare-playable`, one ops row, `archilyzer media playable <slug>`.

#### D4b, as shipped — the seeder of last resort, behind a VPN

- **The state machine** (`common/lib/lastResortSeeder.ts`, pure): a torrent starts seeding; other seeders (the
  scrape's `complete` minus itself, or connected seeds, whichever is more) on every poll for `standbyAfterSeconds`
  → standby; in standby, no other seeder and a leecher waiting (the scrape's `incomplete` or a wire) → seeding at
  once, or no other seeder on every poll for the resume window → seeding; trackers silent for the window while in
  standby → seeding (a last resort assumes it is the only one). A transition restarts both clocks. The resume window
  is `standbyAfterSeconds` (no separate key). 13 tests against a scripted scrape: both edges, hysteresis on each,
  a flapping swarm that never flaps it, the plan's rollout step 7 as a script.
- **The service** (`common/controller/seeder.ts`): WebTorrent 3 in node — TCP, and WebRTC through
  `webrtc-polyfill` → `node-datachannel` (WebTorrent's own dependency chain). Standby removes the torrent from the
  client with its data kept (`stopped` announced, peers closed); seeding adds it back with `skipVerify` after a
  size check of the copy. No DHT, LSD, UPnP/NAT-PMP or web seeds. Scrapes are one request per tracker for every
  infohash, merged per torrent by max; wires are counted by peer (two peers that dialled each other hold two
  wires — found by the integration test, which first saw "2 other seeders"). `bindInterface` held: the seeder
  waits for it and drops every torrent when it disappears. Targets are re-read each poll from the playable
  manifests of every channel of `settings.seeder.sites`.
- **The tracker** (`archilyzer tracker`): bittorrent-tracker, HTTP + WebSocket, no UDP, no stats page, bound to
  `--host` (default 127.0.0.1), refusing every infohash not in the manifests (re-read at most once a minute).
- **Settings** `seeder: {sites, trackers, maxUploadKiBps, maxConnections, pollSeconds, standbyAfterSeconds,
  bindInterface}` (`common/lib/seederSettings.ts`, SETTINGS.md and settings.json.example regenerated); not
  configured = `sites: []`, and `archilyzer seed` refuses to start.
- **The VPN** (`docker-compose.seeder.yml`, profile `seeder`, an overlay on `docker-compose.yml`): gluetun
  `v3.41.3` (custom provider, WireGuard; its firewall is always on in v3 — there is no switch, and the file names
  none), the seeder and the tracker with `network_mode: service:seeder-vpn`, no networks or ports of their own,
  waiting for a healthy tunnel, the corpus read-only. The WireGuard config is the operator's: `${SEEDER_WG_CONF:?…}`
  mounted read-only — compose refuses the file without it (checked with `docker compose … config`). Inbound only
  through `SEEDER_VPN_INPUT_PORTS` (empty by default). `lib/seederCompose.test.ts` pins that construction.
- **Doctor** `seeder` section: "seeder not configured" (a note, no network) while `sites` is empty; else the host's
  egress address and the seeder container's (`docker exec archilyzer-seeder-1 node -e fetch(…)`, one echo URL):
  the same address FAILS, either unanswered warns, different is ok.
- **Measured (localhost, the integration tests):** a TCP leecher completes from the seeder; it then seeds, the
  seeder logs `seeding → standby — 1 other seeder(s) on every poll for 1s`; the leecher leaves and it logs
  `standby → seeding — no other seeder on every poll for 1s`. A WebRTC leecher completes through the WebSocket
  tracker over a `webrtc` wire (node-datachannel). Two node peers that announce in the same instant each answer the
  other's offer and each keep the connection the other dropped; the test starts the leecher after the seeder's
  announce is in, as a browser arriving at a running seeder does.
- **Not measured, owed to the rollout:** whether the VPN's NAT lets browser peers connect (the plan's risk), and
  the manual network test. WebTorrent's default `rtcConfig` asks public STUN servers for the seeder's address:
  inside the profile that address is the VPN exit; on a bare host it would be the home address — run it in the
  profile.

**New dependencies (common):** `create-torrent` 6.1.3, `parse-torrent` 11.0.24 (D3: the torrent and its
infohash), `webtorrent` 3.0.21 (node ≥ 22; the repo runs 22.23), `bittorrent-tracker` 11.2.3 (D4b). Types for the
four are `common/types/webtorrent-modules.d.ts` (they ship none). `pnpm-workspace.yaml` `allowBuilds`:
`node-datachannel: true` (its prebuilt binary); `bufferutil`, `utf-8-validate`, `utp-native`, `ip-set` false (pure-JS
fallbacks, optional uTP, a package-manager check).

**Commits**

| Commit | What |
|---|---|
| `9686fe67` | `common:` attach-media — zip reader, plan, controller, origin kind, `sourcePath`, job kind, ops route + action, ops row, CLI; 33 tests (31 common, 2 editor) |
| `f1370406` | `common:` prepare-playable — decision table, remux, torrents, manifest, job kind, ops route + action, ops row, CLI; 13 tests (11 common, 2 editor) |
| `2f704bc6` | `common:` the seeder — state machine, service, tracker, settings, compose profile, doctor; 26 tests |
| `2e3a9395` | merge `r19/integration` |
| `0f79dd6e` | `common:` each remux takes the heavy slot (per video; 1 test); COMMANDS.md regenerated |
| `c066fb37` | `common:` the plan test's titles and ids synthetic throughout |

**Gates.** `pnpm -r --no-bail --workspace-concurrency=1 exec tsc --noEmit` clean at each commit and after the
merge. Common 3,530 / 3,533 at `2f704bc6` (+68 over the base, 3,465): the three failures are two `autoRunner.test.ts`
cases (`computeLeafPending …`, `a channel with a move marker …`) that fail identically with the base's
`jobKinds.ts`, and `fetchPosts.test.ts`'s drain case, which passes alone (load). Editor 163/163 (+4 route tests).
`test:scripts` 676 + 3 skips at `2f704bc6`, one `queue-lock` banner case failing under load and passing alone (11/11).
No builds, no e2e (none in this track's budget). After the merge, an operator hold (no heavy runs) left only tsc
and single test files: preparePlayable 5/5 (the heavy-slot gate included), cli-docs + jobKinds 21/21, and (before the merge) the settings/doctor/CLI/env tests 95/95.

**Left.** `COMMANDS.md` gains the four rows (`media attach`, `media playable`, `seed`, `tracker` — regenerated
after the merge brought `docs cli`). The rollout's dryRun on the live editor is the parent's. Transcription of
the three new records is the operator's (`transcribe-one`), as ruled. D2, D4, D5 are other slices.

**Landed with release 19** (2026-10-09 evening; release-19.md, "Landing, as it went"): D1, D3 and D4b in
`r19/integration`, under its gates — the whole common suite 3,634/3,634 (the `fetchPosts` drain case among them),
`test:scripts` 708 + 3 skipped, four builds, the full editor suite (start mode) green after re-running three load
flakes alone. The pilot below waits for D2.

#### D2, as shipped — clip windows cut from a saved container

Release 21's D2, on `r20/d2-r20` off `r20/integration` (`585be292`), overnight 2026-10-10 (Track D, part 1).

**What it does.** `common/lib/savedVideoWindow-server.ts`: `savedWindowSource` reads the video's saved-video
pointer (any pointer — a persist, a `full: true` fetch, a D1 `local-archive` attach), stats the container through
the drive watchdog (`onDrive`) and probes it once (`probeMedia`), answering `none` (no pointer), `unreadable`,
`not-covering` (the window ends past the container's duration, to `WIN_EPS`) or `covers`; `cutSavedVideoWindow`
cuts with evidenceClip-server's `evidenceCutArgs` (input-seeked, H.264 + AAC mp4 fitted inside 1280×720; a container
with no picture is cut as sound) to a temp name, renames it to `clips/<from>-<to>.mp4`, and writes the fetched
sidecar shape (`requestedBy`, `manifest`, `clipId`, `reason`, `requestedAt`, `pad`, `bytes`, `fetchedAt` = when it
was cut) plus `source: "saved-video"` — a new optional `ClipProvenance.source` that `parseClipProvenance` reads;
absent on every fetched window.
- **Single** (`fetchWindowAction`): the clip cache, then the in-flight jobs (A5), then the saved container, then
  the network. `covers` → the channel's text guard (`assertChannelTextReadable`, which a `fetch-window` job's
  `needsText` would have asked), the cut, `cached: true` with the window's probed `height`, no job. `unreadable` →
  503 with the media guard's sentence (`Channel "<slug>": media is not reachable — its saved video <path> is not
  there (drive not mounted?)`, or `… could not be read by ffprobe`, or the watchdog's `drive not answering …`), or
  the store guard's (`SavedVideosStoreInTransitionError`) when the file is missing while the store's move marker
  is present. `none` and `not-covering` → the network path, unchanged. A failed cut → 500 with ffmpeg's last lines.
- **Batch** (`fetchWindowsAction` → `controller/fetchWindows.ts`): after the cache and the in-flight check, a
  covered window joins one group of its own — platform `saved-video` on `clips:saved-video`
  (`SAVED_VIDEO_CLIP_QUEUE` / `SAVED_VIDEO_CLIP_PLATFORM`, `lib/queueKeys.ts`), which `groupRefusal` does not
  ask about a hold or cooldown; an unreadable one is `unresolved` with the guard's sentence; a not-covering one joins
  its platform's group. The controller asks the same tier for every item before the URL and the gap: a cut costs no
  pause and is not a network attempt (`result.cut`, logged `✂`, and "N cut from saved videos" in the summary);
  `unreadable` fails the item as `unreachable`; a failed cut is the new class `cut-failed` and the run carries on.
  A5's dedupe covers the new queue unchanged: a queued `saved-video` job's items are in its spec.
- The video page's fetched-windows card adds "· cut from the saved video" to such a window. `mcp/src/instructions.ts`
  (the clip step): "A video the archive holds locally is cut from its saved copy without a fetch (cached at once)."

**Rulings applied.** No pointer → the network exactly as before; a pointer whose container is unreadable → refused,
never a fall-through; a container that does not cover the window → the network (orchestrator, 2026-10-10).

**Found and left.**
- A local cut is at most 1280×720 (evidenceCutArgs' box), whatever `maxHeight` asks; the answer carries the window's
  `height`, as a cached window's does. A smaller `maxHeight` gets a cut taller than it asked for.
- `ops-api.spec` cannot reach a cut: the e2e server runs with `FFMPEG_BIN`/`FFPROBE_BIN` set to the fixture fakes
  (`editor/package.json` `dev:test`/`start:test`), whose ffprobe answers a bare duration, never `-of json`, so every
  saved container there probes as unreadable. The nearest tests run the real thing instead: the route test cuts
  over HTTP with real ffmpeg, and the action test runs the `saved-video` batch job through `runManagedFunction` to
  `done` (below). No e2e case was added.

**Commits**

| Commit | What |
|---|---|
| `11753809` | `channels:` release 21 D2 — the saved-container tier in the single and batch window paths, `ClipProvenance.source`, the `clips:saved-video` queue, the card's marker, the MCP line; 18 tests |

**Gates.** `pnpm -r --no-bail --workspace-concurrency=1 exec tsc --noEmit` clean. New tests, all real ffmpeg over
8 s lavfi containers in temp dirs: `lib/savedVideoWindow-server.test.ts` 9 (no pointer; not covering; a missing
container; an unmounted store dir; the store mid-move; a file ffprobe cannot read; the cut and its sidecar, read
back by the clip cache; sound only; a failing ffmpeg leaves nothing), `controller/fetchWindows.test.ts` +2 (cut /
unreadable / not-covering in one run with no request and no pause; a failed cut), `app/api/media/fetch-window/
route.saved.test.ts` 4 (a covered window → 200 `cached: true`, `provenance.source` `saved-video`, height 90, no job,
then a clip-cache hit; past the container's end → the network door, a YouTube cooldown's 409; a missing container
→ 503 with the guard's sentence; no pointer → the network door), `app/channels/[slug]/videos/
fetchWindowsAction.test.ts` 3 (the dry run's groups and unresolved; a real run whose `saved-video` job ends `done`
with the window and sidecar on disk while the cooling YouTube group is refused; A5's dedupe on `clips:saved-video`).
Editor unit 225/225; the touched common files (clipWindow, evidenceClip, savedVideo*, fetchWindows, windowJobs)
61/61; architecture 6/6; mcp 293/293. The whole common suite runs once at the end of the track (part 2).

## Rollout (pilot)

1. `pnpm ops attach-media --json '{"slug":"the-incredible-salt-mine","source":"<archive>/Uploads/YouTube.zip","dryRun":true}'`.
   Expect about 166 held and matched, 3 with media but not held (`6ijPdSuZdws`, `VcFA_LOnQoc`, `xLgf_MGQzXk`) and
   10 `[LOST]`; the dryRun gives the exact counts, including held videos with no media in the archive.
2. The same without `dryRun`, plus `createRecords`, then `transcribe-one` for the 3.
3. MCP `fetch_clip` on a TISM cue → `cached: true`, provenance `saved-video`, no network.
4. `prepare-playable`.
5. Start the self-hosted tracker and `archilyzer seed` in the VPN namespace, and check its egress IP.
6. Build `jeralyzer-private` and deploy it locally.
7. From a browser on another network: play and seek. A second browser that finishes and seeds sends the home
   seeder to standby; closing it makes the seeder resume.
8. Public ruling → Jeralyzer (public trackers added to the magnets, same infohashes).

## Verification

- D1: unit tests over a fixture zip (stored and deflated entries, id matching, dryRun, refusing an overwrite,
  provenance).
- D2: route/action unit tests plus one `ops-api.spec` case.
- D3: the remux decision table, and torrent determinism (same input → same infohash).
- D4: a compose test (the field, the `.torrent` files, `inputSig` moves).
- D4b: the standby/resume state machine against a fake scrape source (both edges, hysteresis), a kill-switch config
  test, and the manual network test.
- D5: the export e2e above.
- Privacy: no personal identifier of the archive's maker (donation addresses and the like) in any published file;
  no private site URL in any torrent.