# Channel priority — one tier per channel, one focus, four compiled trees

**Status: SHIPPED** on branch `channel-priority/s5` (unmerged), 2026-09-11. All six slices
are implemented; see **"As shipped"** at the foot of this file for the shas, the divergences
and the live migration's dry-run numbers. Anchors are in
[`FACTS.md`](FACTS.md#channel-priority-verified-2026-09-11). Everything above that section is
the plan as written, kept as-is.

Operator decisions taken, numbered as the Open questions section below: **Q1 — collapse** the
two live per-lane channel orders to ONE (the model has one rank per channel). **Q2 — no**, a
Paused channel still runs a MANUAL run; paused gates the sync scheduler, *Sync all* and the
four auto lanes, nothing else. **Q3 — resolved by design**, by the per-operation override map
(see the Model): all 15 migrate to a `sync` override and no lane's membership moves. **Q5 —
no**, activating a focus never changes any lane's `enabled`. Q4 is still open and does not
affect S0.

The ask: *"focus on one group of channels (e.g. jeralyzer) and pause all others until the
priority channels are done … rip out the current enable/disable feature on the channels page
and replace it with a unified channel priority system … heavily influence the auto queue."*

## What the tree says

**The premise that `ChannelConfig.enabled` exists is FALSE.** `common/lib/channelConfig.ts:47`
is `enabled: boolean` inside **`AudioCheckConfig`** (`:46-57`). `ChannelConfig` runs
`:59-160` and has no `enabled`. What the `/channels` row actually carries is **two negative
exclusion flags**, and they gate different things:

| Fact | Where | What it gates |
|---|---|---|
| `excludeFromSync?: boolean` | `common/lib/channelConfig.ts:113`, sanitized `:278-280` | **Sync only.** |
| — scheduler skip | `common/jobs/syncScheduler.ts:99` | `continue` in the due loop, no skip log |
| — status projection | `common/jobs/syncScheduler.ts:193-197` | `autoSyncEligible` false |
| — manual *Sync all* | `editor/app/channels/actions.ts:466-472` | skip reason `"excluded from sync all"` |
| — social due check | `common/controller/fetchPosts.ts:180` | same predicate |
| `excludeFromBuild?: boolean` | `common/lib/channelConfig.ts:112`, sanitized `:275-277` | **Publishing only.** |
| — index build | `common/controller/buildIndex.ts:289` | channel never enters the built index |
| — stats build | `common/controller/buildStats.ts:172` | contributes no stats |
| `excludeFromCleanup?` | `common/lib/channelConfig.ts:117` | the `/cleanup` aggregate total only |
| Writers | `editor/app/channels/actions.ts:394-409` (build), `:411-425` (sync) | both via `writeChannelConfig` (`common/controller/channels.ts:452-463`) |
| UI | `editor/app/channels/components/ChannelsTable.tsx:423-428` / `:429-434` | `ChannelBuildToggle.tsx:18-42`, `ChannelSyncToggle.tsx:18-42`; row dimmed `:406-411`; sortable `:54-63,129-163` |

**Neither flag reaches dispatch.** `common/controller/autoRunner.ts`,
`common/controller/operationBatch.ts` and `common/jobs/autoQueuePolicy.ts` contain zero
`excludeFrom*` references. `listChannelMeta` (`autoRunner.ts:288-296`) maps
`listChannelConfigs` straight to `{slug, platform}` with no filter, so today an
excluded-from-sync channel is still drawn by every lane. Snapshot generation, `recencyIndex`,
the export app and `mcp/src` never read a channel config at all.

**The lane trees are already a priority system, and the live ones are trivial.** From the
repo-root `settings.json` (gitignored):

| lane | enabled | order | held | root |
|---|---|---|---|---|
| transcription | true | listed | false | strict, 10 children: 9 bare `{type:"channel"}` leaves then `{type:"all"}` |
| download | true | listed | false | strict, 10 children: 9 bare `{type:"channel"}` leaves then `{type:"all"}` |
| digest | false | cheapest | false | strict, 1 child `digest-all` `{type:"all"}` |
| backfill | false | newest | false | strict, 1 child `backfill-all` `{type:"all"}` |

**Every one of the 22 live leaves is a bare channel or `all` leaf. Zero carry `match.bucket`;
zero carry `match.operation`.** The two hand-made lists disagree: transcription names
`quartering-live, the-quartering-rumble, the-quartering, HasanAbiVODs3, hasanabi,
rekietalaw-rumble, nux-taku, nuxanor, leaflit-rumble`; download names `quartering-live,
the-quartering, the-quartering-rumble, nuxanor, darlingstrawb, chibi-reviews, destiny,
omnivods-odysee, piratesoftware`. Six channels are ranked in one lane and not the other, and
the three shared Quartering channels are in two different orders.

**A strict group is already "hold the rest until the higher one is empty".**
`pick()` (`common/jobs/autoQueuePolicy.ts:487-513`) filters children to those with work
(`:501`) and on `mode === "strict"` descends into the FIRST of them (`:503-505`). It is
re-asked on every single grant, so: focus work present ⇒ nothing below it is picked; focus
work exhausted ⇒ the next child runs; new focus work arrives ⇒ the very next pick retakes the
lane. The runner rebuilds `pending` every tick from fresh snapshots (`autoRunner.ts:1087-1092`)
and re-reads the policy each iteration (`:1093-1095`).

**Sites are a clean partition.** 63 distinct slugs across six `transcripts/sites/*/site.json`,
**zero in two sites**; 69 directories under `transcripts/channels/` (68 real + `.stfolder`),
so 5 are in no site (`angryjoeshow`, `jfg-tonight`, `leaflit-rumble`, `omnimirror`,
`piratsoftware-x`). `jeralyzer` = 30, `anilyzer` = 22, `hasanalyzer` = 5, `bonnellyzer` = 3,
`rekietalyzer` = 2, `jasolyzer` = 1.

**Sync ordering today.** `selectDueChannels` (`common/jobs/syncScheduler.ts:85-127`) gates on
`scheduler.enabled` (`:87`), quiet hours (`:88-92`), `!config.url` (`:98`), `excludeFromSync`
(`:99`), interval ≤ 0 (`:101-102`), already-running (`:104-107`), failure backoff (`:109-118`)
and not-due (`:120-121`); it sorts **most-overdue-first** at `:125`, ties resolving
alphabetically because `listChannelConfigs` returns slug order
(`common/controller/channels.ts:401-403`). The tick caps the list at
`maxConcurrentSyncs - running` (`editor/app/scheduler/runTick.ts:127-131`). No pause gate is
consulted in selection (`pauseGates.ts:64-67`: sync's lane is `null`); dispatch refuses when
the **download** lane is held (`editor/app/channels/[slug]/pipelineActions.ts:109-117`).

## Decision

**One document in `settings.json`, one tier per channel plus one focus selector, compiled into
the four `AutoQueuePolicy.root` trees by the model's own writer. Paused is a filter on the
runner's channel list, not a tree shape.**

1. **`settings.json`, not 68 `config.json` files.** A focus is one corpus-wide fact with an
   ordering *between* channels; 68 files cannot express a total order and cannot be written
   atomically. `parseChannelConfig` is allow-list style (`channelConfig.ts:211-375`) and
   silently drops unknown keys, so a per-channel rank would need a schema change in the file
   that every downloader, sweep and build reads. `settings.json` already holds every other
   dispatch decision (`autoQueue`, `syncScheduler`) behind one sanitizer and one writer.

2. **COMPILE, not consult.** The deciding fact is the pair above: strict descent
   (`autoQueuePolicy.ts:503-505`) is *exactly* the focus/hold semantics the operator described,
   re-evaluated per pick at zero cost, and **the live trees contain nothing a compiler would
   destroy** — 22 leaves, all bare. Consulting the model from the claim ladder would mean a
   second priority mechanism beside the tree, two things to explain on
   `HowPriorityWorks.tsx`, and a new re-evaluation clock. Compiling means **no dispatch code
   changes at all**: `buildPendingByLeaf`, `selectNextWork`, `operationBatch`, `laneLimit`,
   `pauseGates` and every `held` key are untouched, and "a zero limit is a hold, never a stop"
   is preserved trivially because nothing new ever returns a limit.

3. **Paused is removed from the channel LIST, not from the tree.** A tree cannot express
   exclusion (an `{type:"all"}` catch-all matches everything, and first-match-wins would let a
   catch-all placed above the Low group swallow Low's work). `listChannelMeta`
   (`autoRunner.ts:288-296`) is the single source of the channel list for **both** the runner
   loop (`:1080-1092`) and the status panel (`computeLeafPending`, `:574-582`), refreshed on a
   30 s TTL (`CHANNEL_LIST_TTL_MS`, `:141`). Filtering Paused there makes a paused channel
   invisible to all four lanes, catch-all included, in one predicate.

4. **`excludeFromSync` dissolves into a `sync` OVERRIDE, not into the Paused tier;
   `excludeFromBuild` stays.** The three are different axes: one is the sync cadence, one is
   dispatch, one is publishing, and the brief's own rule is that the lowest tier must not gate
   export. A per-operation override says "stop syncing, keep everything else" exactly, so the
   migration moves no lane's membership. The `/channels` row keeps its Build toggle and loses
   its Sync toggle.

5. **No drag-and-drop, and no per-lane RANK.** Tier is a `<select>`; intra-tier order is an
   optional integer `rank` (migration seeds it; ties fall back to slug order), and there is
   ONE rank per channel. Per-operation *tier* overrides do exist (above) — they change which
   lane a channel is on, never its order within one.

## The model

`common/lib/channelPriority.ts` — new, pure, imports only `./autoQueueTypes` (lib → lib, so
**`common/architecture.test.ts`'s ALLOWED list gains no entry**; `FORBIDDEN` at `:31-35` only
bars `lib → controller|jobs`).

```ts
export const CHANNEL_TIERS = ["focus", "normal", "low", "paused"] as const;
export type ChannelTier = (typeof CHANNEL_TIERS)[number];
// What may be STORED on a channel — "focus" is a compiled POSITION, never a stored tier.
export const STORED_CHANNEL_TIERS = ["normal", "low", "paused"] as const;

// The operations a tier can be pinned to: the four lanes plus `sync` (which is
// not a lane — it is a per-channel cadence, the answer pauseLaneFor already gives it).
export const PRIORITY_OPERATIONS = ["sync", ...LANES] as const;
export type PriorityOperation = (typeof PRIORITY_OPERATIONS)[number];

export type ChannelFocus =
  | { kind: "none" }
  | { kind: "site"; siteId: string }      // live membership: a channel added to the site joins
  | { kind: "channels"; slugs: string[] };

export type ChannelPriority = {
  focus: ChannelFocus;
  // Only channels that differ from the default appear. Absent slug = normal, no rank.
  channels: Record<string, {
    tier: StoredChannelTier;
    rank?: number;
    // PER-OPERATION OVERRIDES of the base tier. Only operations that DIFFER appear.
    overrides?: Partial<Record<PriorityOperation, StoredChannelTier>>;
  }>;
};
```

**Per-operation overrides are the advanced half, and they are what makes the migration
lossless.** The operator's case: *"I find the download on channels that sync to be an issue
(e.g. omnibased)"* — a channel must be able to keep its playlist and metadata current while
its download lane is parked, and in general any operation may sit at a different tier than
the channel's base. That is also precisely what `excludeFromSync` meant, read the other way
round, so the flag this model replaces becomes `{tier: "normal", overrides: {sync: "paused"}}`
and nothing else moves.

- `effectiveTier(model, slug, op)` = `overrides?.[op] ?? tier`, and **every dispatch-side
  question asks it**: the compiler per lane, `listChannelMeta` for the lane it is listing,
  the sync scheduler for `"sync"`. `tierOf` stays the BASE tier and is the display answer.
- **The focus set stays ONE, corpus-wide.** A focused channel whose override for some
  operation is `paused` is simply not drawn for that operation — focus wins over the stored
  tier, paused wins over focus, per operation.
- **Two presets, each the other's inverse.** `{tier:"normal", overrides:{sync:"paused"}}` is
  "everything but sync"; `{tier:"paused", overrides:{sync:"normal"}}` is "sync only".
- **Sanitizer normalisation:** an unknown operation key is dropped; an unknown tier VALUE is
  dropped rather than coerced (coercing to `normal` would silently unpause an operation on a
  paused channel — an override's job is to differ from the base, so a junk one falls back to
  the base); an override equal to the base is normalised away, and an empty map with it; a
  `rank` on a channel paused for *every* operation is dropped, while a "sync only" channel
  keeps one because the sync scheduler still orders it. Keys are emitted in
  `PRIORITY_OPERATIONS` order and slugs sorted, so the on-disk document has a stable diff.
- **The four compiled trees are identical unless an override moves a channel.** One rank per
  channel means the only thing that can differ between lanes is membership, and the only
  thing that changes membership is an override.

- `focus: {kind:"site"}` is the first-class answer to *"focus = the channels of site X"*, and
  it is resolved at compile time against `transcripts/sites/<id>/site.json`'s `channels[]`, so
  it tracks membership rather than freezing a list. `{kind:"channels"}` backs "Focus these".
- The `focus` tier in `CHANNEL_TIERS` is the compiled *position*, produced by the focus
  selector; a channel is never stored with `tier: "focus"`. Storing it would give two ways to
  say the same thing and no way to end a focus in one click.
- **Absent document = today's behaviour**, byte for byte: no focus, every channel normal, the
  compiler is never run, the stored trees stand.

`sanitizeChannelPriority(value)` in the same file, called from `getSettings`
(`common/lib/settings.ts:1312-1436`, beside `merged.syncScheduler = …` at `:1396`) and from
`saveSettings` (`:1613-1620`). Unknown tiers → `normal`; non-finite ranks dropped; blank slugs
dropped; `focus.siteId`/`slugs` trimmed and de-duplicated.

### The compiler

```ts
export function compileLaneRoot(
  lane: AutoQueueKind,
  model: ChannelPriority,
  slugs: readonly string[],     // every non-paused channel, from listChannelConfigs
  focusSlugs: readonly string[],// resolveFocusSlugs(model, siteChannels)
): AutoQueueGroup
```

Output, per lane:

```
root            strict
├─ focus        strict   — one bare channel leaf per focus slug   (omitted when focus is none)
├─ normal       strict   — one bare channel leaf per normal slug
├─ low          strict   — one bare channel leaf per low slug
└─ catch-all    leaf {type:"all"}      ← safety net, last
```

Within a group: `rank` ascending (unranked last), then slug. Leaf ids are
`prio-<tier>-<slug>`, group ids `prio-<tier>`, so a compiled tree is recognisable on sight and
a hand-authored leaf is too. The trailing `{type:"all"}` only ever claims a channel with no
leaf of its own — i.e. one created since the last compile — so drift is always *safe*
(bottom priority) and self-heals on the next write. Paused channels never reach it because
they are gone from the channel list (change 2).

**Cost.** `buildPendingByLeaf` (`autoQueuePolicy.ts:357-428`) is O(leaves × draws × channels)
in `matchesChannel` string compares: today 10 × 2 × 68 ≈ 1.4 k per tick, compiled 69 × 2 × 68
≈ 9.4 k. The id-push work is unchanged (each video is claimed once). Against the ~6.5 MB of
snapshot JSON the same tick parses (memoized at 256 ms, FACTS.md "the snapshot memo"), this is
noise. `flattenLeaves`/`hasWork` walk ~69 nodes per pick.

## Changes

1. **`common/lib/channelPriority.ts`** — the types above, `defaultChannelPriority()`,
   `sanitizeChannelPriority()`, `tierOf(model, slug)`, `resolveFocusSlugs(model, siteChannels)`,
   `compileLaneRoot(...)`, `compileLanes(model, slugs, focusSlugs)` returning
   `Record<AutoQueueKind, AutoQueueGroup>`, `focusSummary(model, focusSlugs, pendingByLeaf)`
   for the banner, and `channelPriorityFromLegacy(configs, autoQueue)` for the migration.

2. **`common/controller/autoRunner.ts:288-296`** — `listChannelMeta` drops
   `isChannelPaused(priority, slug, lane)` — the EFFECTIVE tier for the lane being listed,
   so a channel paused for `download` and normal for `transcription` is absent from one and
   present in the other. One predicate; both the runner loop and `computeLeafPending`
   inherit it, and the 30 s TTL (`:141`) is the re-evaluation clock. *Nothing else in
   dispatch changes.*

3. **A new idle reason is NOT added.** A lane whose focus group holds the rest is not idle —
   it is dispatching focus work. When the whole tree is empty the existing `no-pending`
   (`autoRunner.ts:197-199`) is still the true answer. The "M channels held" statement is a
   *display* fact computed from `pendingByLeaf` and belongs in the banner (change 6), not in
   `AutoRunnerIdleReason`.

4. **Sync** — `common/jobs/syncScheduler.ts`:
   - `selectDueChannels` takes the model. The `excludeFromSync` skip at `:99` becomes
     `isChannelPaused(priority, slug, "sync")` — the effective tier for the `sync`
     operation, which is exactly what the flag meant — with the same silent `continue`.
   - The sort at `:125` becomes **tier rank, then rank, then `overdueMs` descending**:
     `focus < normal < low`, all read through `effectiveTier(·, "sync")`. Most-overdue-first
     survives *within* a tier, so a focus channel
     due by a minute outranks a low channel due by a day, and the tick's cap
     (`editor/app/scheduler/runTick.ts:127-131`) therefore spends its slots on focus first.
   - `autoSyncEligible` (`:193-197`) follows the same predicate.
   - `tierOrder(tier)` in `channelPriority.ts` is the one sortable form of the tier order.
   - `syncAllChannelsAction` (`editor/app/channels/actions.ts:466-472`) swaps its
     `excludeFromSync` skip for the same one and sorts the candidate list the same way.

5. **`/channels`** — `editor/app/channels/`:
   - `ChannelSyncToggle.tsx` is deleted and its cell (`ChannelsTable.tsx:429-434`) becomes a
     `ChannelTierSelect` — a four-option `<select>`, `aria-label={`tier for ${slug}`}`, posting
     `setChannelTierAction(slug, tier)`. `ChannelBuildToggle` is untouched.
   - Row selection: checkboxes + a bulk bar, copying `SyncConsole.tsx:29,107,115,169,196-199`
     and `BulkCadenceBar.tsx:37,41` verbatim rather than inventing an idiom. Bulk actions:
     **Set tier**, **Focus these**, and a **Focus site: `<id>`** menu built from
     `listSites()` (no selection needed).
   - **Advanced: per-operation selects behind a disclosure**, beside the tier control, plus a
     **Sync only** preset (and its inverse, which is what every migrated `excludeFromSync`
     channel already carries). The row shows the base tier and a marker when any operation is
     pinned; the disclosure is where the five operations are set.
   - Sort key `sync` (`ChannelsTable.tsx:54-63,129-163`) becomes `tier` (tier order, then
     rank, then slug). Row dimming (`:406-411`) keys off `tier === "paused"`.
   - `channelGroupSections.ts:124`'s excluded-from-sync section becomes the Paused section.
   - **One writer.** `saveChannelPriorityAction` in `editor/app/channels/actions.ts` is the
     only function that writes `settings.channelPriority`; every control above funnels through
     it, and it **recompiles the four roots in the same `saveSettings` call** —
     `autoQueue[lane].root = compileLanes(...)[lane]`, spreading each policy so `held`,
     `snoozeUntil`, `enabled`, `order` and `maxWorkers` survive (the rule
     `withGateHeld`/`saveAutoQueueAction:47-80` already state). `createChannel` /
     `deleteChannel` recompile too, so a new channel gets a real leaf rather than the net.

6. **The focus banner** — `editor/app/channels/components/FocusBanner.tsx`, rendered on
   `/channels` (`page.tsx`, above the table at `:192`) and on the lane consoles at
   `editor/app/operations/components/OperationDetail.tsx:127` — between `HowPriorityWorks` and
   `RunnerOperationView`, i.e. **outside** the `<section data-lane>` that `RunnerOperationView`
   opens (`:89-93`) and whose contract comment (`:22-36`) reserves `role="status"` and forbids
   a nested `<section>`. Content: `Focus: <name> (N channels) · <units> pending in this lane ·
   M channels held`, and an **End focus** button posting `endFocusAction()` (which sets
   `focus: {kind:"none"}` and recompiles). The numbers come from `computeLeafPending`
   (`autoRunner.ts:574-662`) — already computed for the status panel, so the banner costs one
   sum over `counts` keyed `prio-focus-*` and one over the rest. On `/channels` the banner
   shows the per-lane line only for lanes whose policy is `enabled`.

7. **A held row says why.** `ChannelsTable` renders `Held — focus: <name>` beside the tier of
   any non-focus channel while a focus is active and the focus set still has pending work in
   at least one enabled lane. Derived from the same `focusSummary`, not from a new read.

8. **`HowPriorityWorks.tsx`** gains one paragraph: the tree is *generated* from the channel
   priority model, and `PolicyTreeEditor.tsx` (360 lines) becomes read-only for compiled
   groups — it keeps editing `enabled`, `maxWorkers`, `order`, `replaceAutoSubs` and any
   hand-added `bucket`/`operation` leaf, and shows compiled channel leaves with an
   "edit on /channels" link. It is not deleted: the bucket/operation axis it can express has no
   equivalent in the priority model.

## Migration

Live data: **15 of 68 channels carry `excludeFromSync: true`** — `community-notes`,
`angryjoeshow`, `cornbreadman`, `friendofrc`, `hex-headquarters`, `mevsme`, `omnivods-odysee`,
`exclusively-games`, `rcflightschool`, `rcspotlight`, `teamrcn`,
`the-incredible-salt-mine`, `steven-crowder`, `midwestly`, `redbar` — and **zero** carry
`excludeFromBuild`. One of the 15, `omnivods-odysee`, is also the 8th ranked leaf of the live
download tree: today it is excluded from sync yet still drawn by the download lane.

**The mapping is LOSSLESS, and that is what the override map is for.** `excludeFromSync`
meant "stop syncing", not "stop everything", so it becomes
`{tier: <base>, overrides: {sync: "paused"}}` — the base tier stays `normal` and the rank
(if the channel has one) stands. `omnivods-odysee` keeps downloading exactly as it does
today; **no lane's membership moves**, which makes the migration a settings rewrite rather
than a behaviour change. An operator who wants one of the 15 paused outright sets its base
tier afterwards, deliberately, on `/channels`.

- **Pure function**, `channelPriorityFromLegacy(configs, autoQueue): ChannelPriority`, in
  `common/lib/channelPriority.ts`, in the `laneMigration.ts` style (no I/O, idempotent over its
  own output, asserted through `sanitizeChannelPriority`):
  - `config.excludeFromSync === true` → `overrides: {sync: "paused"}` on the channel's entry,
    never a base tier. A channel that also has a lane leaf (`omnivods-odysee`) keeps its rank
    and every lane it was drawn by.
  - A channel named by a bare channel leaf in **either** the download or the transcription root
    → `{tier: "normal", rank: <the lower of its two indices>}`, where the index is its
    position among that root's **bare channel leaves** (a dense order; identical to the leaf
    index when every leaf is bare, which all 22 live leaves are — so a bucket or operation
    leaf the model cannot express leaves no hole). Channels ranked in one lane only keep that
    lane's index.
  - Everything else → absent (normal, unranked).
  - `focus: {kind: "none"}`.
- **It is NOT run from `getSettings`.** That function is synchronous and reads one file; the
  migration needs 68 `config.json` reads. It is a one-shot script,
  `common/bin/migrate-channel-priority.ts`, run offline with `tsx` (never a second editor), that
  reads the configs and `settings.json`, writes `channelPriority`, recompiles the four roots and
  prints a diff. Idempotent: a second run is a no-op because the document already exists.
- **The order collapse is the migration's ONE behaviour change, and must be measured.** Six
  channels are ranked in one lane only, and the three Quartering channels are in different
  orders in the two lanes; after the migration both lanes get one order. Gate it with `plans/tools/phase1-numbers.ts`
  before/after over the live corpus, the way every Phase 1 slice was gated — the `*_leaves`
  lines will move by construction, so the number that must not move is each lane's total
  pending count.
- `excludeFromSync` stays in the type and the sanitizer as the migration's **input only**,
  exactly as the four retired pause fields did (FACTS.md, slice 1.4), and is deleted with its
  sanitizer, its action (`actions.ts:411-425`), its toggle and `channel-sync-toggle.spec.ts` in
  the last slice.

## Tests

**Unit** — `common/lib/channelPriority.test.ts`, run by
`pnpm --filter yt-dlp-transcript-common test` (`common/package.json` glob covers
`lib/*.test.ts`):
1. `sanitizeChannelPriority`: unknown tier → normal; junk rank dropped; blank/dup slugs;
   absent document → `{focus:{kind:"none"}, channels:{}}`; idempotent over its own output.
2. `resolveFocusSlugs`: site focus resolves through a site's `channels[]`; an unknown siteId
   resolves to `[]` (and therefore compiles **no** focus group — a typo must not hold the whole
   corpus); channel focus keeps order and drops unknown slugs.
3. `compileLaneRoot`: group order focus → normal → low → catch-all-last; paused slugs never
   appear; rank ordering with unranked tail; ids are `prio-*`; an empty focus emits no focus
   group; a per-operation override moves a channel on **one** lane's tree and not the others.
   The half that must import the engine — *the output survives `sanitizeAutoQueue`
   unchanged*, with no id reassigned — is `jobs/channelPrioritySanitize.test.ts`.
4. **The focus/hold/done transition, asserted through the real engine**: build two
   `ChannelWork` objects, compile a tree with channel A focused, and drive `buildPendingByLeaf`
   + `selectNextWork` — every pick is A's while A has work; the first pick after A's list is
   drained is B's; re-adding an id to A's bucket makes the next pick A's again. This is the
   whole design in one test. It lives in **`common/jobs/channelPriorityCompile.test.ts`**, not
   in `lib/`, because it must import `jobs/autoQueuePolicy` and `architecture.test.ts` forbids
   `lib/ → jobs/` — the same reason `laneMigration.test.ts` sits in `jobs/`.
5. `channelPriorityFromLegacy`: the live shape (9+9 leaves, 6 one-lane channels, 3 reordered);
   an `excludeFromSync` config becoming a `sync` override only; and **the 15-channel case
   round-tripping with no lane change** — every channel still on every lane's compiled tree,
   only the `sync` operation losing anyone.
6. Sync ordering: `selectDueChannels` with one focus channel 1 min overdue and one low channel
   1 day overdue returns the focus channel first; a paused channel is never due.

**e2e** — from a `git worktree` with a composed fixture site in its `export/public`, detached
behind the queue lock (`setsid nohup`, ~25 min), never in the primary checkout while
`editor/content` is a symlink (STATE.md).
- `channel-priority.spec.ts` (new): the tier `<select>` persists and re-renders; select two
  rows → **Focus these** → the banner appears on `/channels` with "2 channels"; **End focus**
  clears it; a `paused` channel's row dims and its Build toggle still works.
- `channel-sync-toggle.spec.ts` is deleted in the last slice; its "excluded from Sync all"
  assertion moves onto the paused tier.
- Focus hold/release in a runner: `two-slow-channels` (`slow-a`, `slow-b`) is the **only**
  multi-channel fixture corpus, so it is the fixture. Arm the digest lane (the lane the
  existing `lane-runner.spec.ts` drives through the Ollama stub, and the one whose `held` is
  observable — transcription's is not, by design), focus `slow-a`, assert every dispatched unit
  is `slow-a`'s and the banner says "1 channel held", then exhaust `slow-a` and assert the next
  unit is `slow-b`'s.
- **Focus-by-site needs a fixture edit**: `editor/e2e/fixtures/sites/testsite/site.json` names
  `test-channel`, which is not a slug in any fixture corpus. Add `slow-a` to that site's
  `channels[]` so **Focus site: testsite** has something to resolve.

**Gates per slice**: `pnpm --filter yt-dlp-transcript-common exec tsc --noEmit`,
`pnpm --filter yt-dlp-transcript-editor exec tsc --noEmit`,
`pnpm --filter yt-dlp-transcript-common test` (includes `architecture.test.ts` — **no ALLOWED
entry may be added**), and the named spec files.

## Slices

**S0 — the contract (lands first, small, blocks everything).** Branch `channel-priority/s0`.
Files: `common/lib/channelPriority.ts` (all types including the per-operation overrides, the
sanitizer, `effectiveTier`/`isChannelPaused`/`channelsForOperation`, the focus resolver, the
compiler, `focusSummary` and the legacy function), the sanitizer wired into
`getSettings` (`settings.ts:~1396`) and `saveSettings` (`:1613-1620`), `SiteSettings` gains
`channelPriority` (and `editor/app/settings/actions.ts` PRESERVES it, the way it preserves
`autoQueue` — rebuilding it would undo a focus), plus **empty-but-exported stubs** for the
files S3/S4 import: `editor/app/channels/components/ChannelTierSelect.tsx` and
`editor/app/channels/components/FocusBanner.tsx`. Tests 1-3 and 5. Nothing reads the
model yet, so the live tree is untouched and no number moves.

The sanitizer round-trip half of test 3 lives in **`common/jobs/channelPrioritySanitize.test.ts`**,
not in `lib/`: `architecture.test.ts` scans test files like any other and forbids `lib/ -> jobs/`,
and its ALLOWED list may only shrink. Same reason `laneMigration.test.ts` sits in `jobs/`.

**S1 — dispatch.** Branch `channel-priority/s1`. Only `common/controller/autoRunner.ts`
(`listChannelMeta` paused filter) + `common/jobs/channelPriorityCompile.test.ts` (test 4).

**S2 — sync.** Branch `channel-priority/s2`. Only `common/jobs/syncScheduler.ts` (`:99`, `:125`,
`:193-197`) + test 6.

**S3 — `/channels`.** Branch `channel-priority/s3`. `editor/app/channels/page.tsx`,
`components/ChannelsTable.tsx`, `ChannelTierSelect.tsx`, a `ChannelBulkBar.tsx`,
`lib/channelGroupSections.ts`, and `actions.ts` gaining `saveChannelPriorityAction` /
`setChannelTierAction` / `endFocusAction` (the recompile lives here). `channel-priority.spec.ts`.

**S4 — the banner on the lane consoles.** Branch `channel-priority/s4`.
`FocusBanner.tsx` (filled in), `editor/app/operations/components/OperationDetail.tsx:127`,
`HowPriorityWorks.tsx`, `PolicyTreeEditor.tsx` read-only mode. Reads `focusSummary` from S0 and
renders nothing when `focus.kind === "none"`, so it is green before S3 exists.

**S5 — migration and deletion (lands last).** Branch `channel-priority/s5`.
`common/bin/migrate-channel-priority.ts`, deletion of `excludeFromSync` from
`channelConfig.ts:113,278-280`, `actions.ts:411-425`, `ChannelSyncToggle.tsx`,
`syncScheduler.ts`'s legacy read, `fetchPosts.ts:180`'s comment, and
`channel-sync-toggle.spec.ts`. The before/after numbers run.

**Graph.** `S0 → {S1, S2, S3, S4} → S5`. S1, S2, S3 and S4 touch **disjoint file sets** and run
fully in parallel on separate branches once S0 merges; S5 waits on S3 (both edit
`editor/app/channels/actions.ts`) and on S2 (both edit `syncScheduler.ts`'s skip). Hotspots and
how they are avoided: **`common/lib/settings.ts`** is touched by S0 alone; **`actions.ts`** by
S3 then S5, never concurrently; **`syncScheduler.ts`** by S2 then S5; **`autoRunner.ts`** by S1
alone; **`ChannelsTable.tsx`** by S3 alone; the two stub components exist from S0 so S3 and S4
each edit one file the other does not. e2e cannot run in parallel regardless — one machine-wide
queue lock, ~25 min per suite — so the four branches should each run only their own new spec
plus `channels*.spec.ts`, and the full suite runs once at the merge.

## Out of scope

Per-lane *rank* (a channel has one order, not four); drag-and-drop ordering; time-boxed focus ("focus until Friday");
auto-ending a focus when its work hits zero (the banner reports it, the operator ends it);
`excludeFromBuild` and `excludeFromCleanup`; the site-membership editor; any change to
`operationBatch`, `laneLimit`, `pauseGates`, the `held` keys or `.auto-queue/state.json`.

## Open questions for the operator

1. ~~**The two live trees disagree on six channels and on the Quartering ordering.** Collapse to
   one order, or keep a per-lane `rank`?~~ **DECIDED: collapse.** One rank per channel.
2. **Does Paused stop a *manual* run? DECIDED: no.** Paused gates the sync scheduler,
   *Sync all*, and all four auto lanes; the per-video and per-channel Run buttons
   (`runDigestChannelJob`, `runBackfillChannelJob`, the pipeline actions) still work, with a
   "Paused — automatic work is off for this channel" badge on the channel page.
3. ~~**Are all 15 `excludeFromSync` channels really meant to be Paused everywhere?**~~
   **RESOLVED BY DESIGN (per-operation overrides).** The question only existed because the
   first model could not say "stop syncing, keep everything else". It can now: all 15 migrate
   to `overrides: {sync: "paused"}` with their base tier and rank untouched, no lane's
   membership moves, and no list from the operator is needed. Pausing one outright is a
   deliberate later edit on `/channels`.
4. **Do the 5 channels in no site belong in a tier by default?** They are normal today; a
   site-scoped focus will hold them like any other non-focus channel.
5. **Should a Focus also raise the lane's `enabled`? DECIDED: no** — focusing must not
   start a stopped lane, for the same reason `saveAutoQueueAction` refuses to unhold one.

## Roadmap placement — a recommendation, not applied here

**Run it as a standalone plan sequenced as one-core "Phase 1.5": after
`relocate-channel-media.md`, before Phase 2 (`ArchiveReader`), and only once
`one-core/phase-1` merges.**

- It must come **after** `relocate-channel-media.md`: `/home` is at 100 % with 6.9 G free, that
  work is already being refreshed in parallel, and focusing a lane means *more* downloading, not
  less. Prioritising Jeralyzer onto a full disk fails at the disk gate.
- It must come **after** the `one-core/phase-1` merge, not beside it: this plan rewrites
  `autoQueue[lane].root`, which is the artifact slice 1.3's migration produces and slice 1.4's
  writers spread. Two unmerged branches editing those trees is the one merge conflict worth
  paying to avoid.
- It should come **before** Phase 2: Phase 2 is the read contract (`ArchiveReader`) and touches
  none of `autoQueue`, `syncScheduler` or `/channels`. The two are independent, and this one has
  an operator waiting on it.
- **Standalone, not a phase of one-core.** One-core's phases each collapse one concept into the
  core and delete code; this one *adds* a model and a UI surface, carries its own live-data
  migration and its own operator gate. But it inherits one-core Phase 1's invariants verbatim
  (one scheduler, one gate definition, one writer per settings block, a hold is never a stop),
  so it belongs in the same interlude slot as `relocate-channel-media.md` and should cite them
  rather than restate them.


## As shipped (2026-09-11)

Branch `channel-priority/s5`, off S0's `28bfee3` on top of `e74f005` (`one-core/phase-1`).
**Unmerged**, and the migration has **not** been run — that is the operator's step at rollout.

### The slices, in merge order

| slice | branch | tip | what it is |
|---|---|---|---|
| S0 | `channel-priority/s0` | `28bfee3` | the model, the sanitizer, the compiler, the legacy read |
| S1 | `channel-priority/s1` | `2710195` | `listChannelMeta`'s paused filter, `laneDispatchRoot`, the focus-hold log line |
| S2 | `channel-priority/s2` | `76c5784` | `selectDueChannels`' predicate and its tier/rank/overdue order |
| S3 | `channel-priority/s3` | `88da736` | `/channels` tier + bulk controls, `saveChannelPriorityAction` |
| S4 | `channel-priority/s4` | `9fcc8b4` | the focus banner, the compiled ladder, the read-only tree |

S1–S4 merged into S5 in order with **no conflicts** — the graph's disjoint-file-set claim held
exactly. S5's own commits: the duplication fold (`7e3b282`), the keep decision (`13c5da4`),
dense ranks and idempotence (`8c335d5`), one writer of `root` plus the legacy seed
(`a5bb23f`), the seeding e2e (`a12aa14`), the migration script (`278e648`), the deletion of
`excludeFromSync` (`dca3109`), the End-focus recompile (`d487519`), the records, the onboarding spec (`305fd7b`) and the
review's three should-fixes (`a8e908a`: the rename writer, the migration's own backup, the
rollout warning).

### Divergences from the plan

1. **`isDefaultChannelPriority` lives in `lib/channelPriority.ts`, not in the runner.** S1 kept
   it private ("a dispatch-side question"), S4 shipped a second copy in the editor. Five
   callers in two packages ask it, and `controller/backfillReacquire.ts` is one of them — a
   controller importing the runner opens an import cycle. The model owns it; `laneDispatchRoot`
   is exported from `autoRunner.ts` and is what the status payload calls, so there is one
   definition of the dispatched tree as well.
2. **`siteChannelIndex(paths)` is new, in `lib/site.ts`.** The plan did not name it; four
   inlined copies of "read every site.json, map siteId → slugs" did.
3. **The keep decision is in scope after all.** The plan said dispatch was untouched except for
   `listChannelMeta`. `backfillReacquire.decideKeep` reads the transcription ROOT, which the
   compiler rewrites, and on a compiled tree a transcription-paused channel has no leaf — so
   the unchanged code would have unlinked re-acquired audio for every paused channel. It now
   asks the pause first and keeps (`"paused"`), then asks the leaf question of the compiled
   root. This is the one dispatch-adjacent change the plan did not foresee.
4. **The legacy ranks are renumbered densely**, with a stated tie rule (merged index, then the
   transcription lane's order, then slug). The plan's "lower of its two indices" leaves four
   collisions on the live trees, and a collision falls through to slug order — neither lane's.
5. **The migration is idempotent by DETECTION, not by "the document already exists".** Compiled
   channel leaves are bare channel leaves, so a second run would re-derive ranks from its own
   output. `hasCompiledLaneRoots` (a `prio-*` id anywhere in a lane root) is the gate.
6. **The one writer seeds from the legacy trees**, and a corpus whose roots are already
   compiled recompiles even for a DEFAULT document. Neither is in the plan, and both are
   correctness: without the first, the first tier click destroys the hand-made order; without
   the second, End focus leaves `prio-focus` at the head of the tree the runner bypasses to.
7. **One writer now means `root` as well as the document.** `saveAutoQueueAction` and
   `armLaneAction`-with-a-scope refuse server-side while a model exists, and
   `prioritizeChannelDownloadAction` is a `{kind:"promote"}` priority edit. The writer takes
   one option, `enableLanes`, so "Add to the top of the download queue" stays one write.
8. **`channel-sync-toggle.spec.ts` went in S3**, not S5 — S3 removed the control it drove.
9. **`renameChannelAction` is a priority writer too.** Not in the plan, which named only
   create and delete. The document keys by slug, so a rename without it loses the channel's
   tier, rank and overrides under a dead slug, drops it out of a `{kind:"channels"}` focus,
   and leaves a `prio-*-<oldSlug>` leaf in every compiled root. The re-key is the pure
   `renameChannelInPriority`; the write goes through the one writer.
10. **The migration takes its own backup.** The plan left that to the operator. An operator
   step on the destructive path is a step someone skips.

### The banner's End focus, and why the link stayed

S4 built `FocusBanner` with an `endFocus?: ReactNode` slot and a "Channel priorities" link,
and deliberately no writer of its own. S5 fills the slot on the lane consoles with
`EndFocusButton`, a client component that posts `endFocusAction` — S3's named gesture, so it
is the same writer, not a second one. The link stays beside it: the button ends a focus, the
link is the way to everything else the document says.

### Gates

`tsc --noEmit` clean in common, editor, export and mcp.
`pnpm --filter yt-dlp-transcript-common test`: **985 passed** (974 at the merge — 951 + S1's
11 + S2's 12 — plus 6 `laneDispatchRoot`/`priorityContextFor` cases, 4 `decideKeep` cases and
1 idempotence case).
**Full editor e2e at `a8e908a`: 528 passed, 0 failed, 22.9 min.**

### The live migration, dry-run

`SETTINGS_FILE` pointed at a read-only copy of the live `settings.json`, `TRANSCRIPTS_DIR` at
the real corpus; no `config.json` or `settings.json` mtime moved. **68 channels, 28 entries,
14 ranked, 15 pinned `sync=paused`, no focus, every base tier `normal`**, all four compiled
roots `prio-normal(68) > prio-all`. Ranked order, dense 0–13:

`quartering-live, the-quartering-rumble, the-quartering, HasanAbiVODs3, nuxanor, hasanabi,
darlingstrawb, rekietalaw-rumble, chibi-reviews, nux-taku, destiny, omnivods-odysee,
leaflit-rumble, piratesoftware`

`omnivods-odysee` is the channel that is both ranked and excluded: it keeps its rank, keeps
downloading, and loses only `sync`. No lane's membership moves.

### Rollout — MIGRATE BEFORE THE FIRST BOOT, not after

**This is a warning, not a recipe.** `excludeFromSync` is deleted and the parser drops the
key, so until the migration has run the 15 channels that carried it read as saying nothing
about sync, and four places act on that from the first render: `syncScheduler.ts:132`
(selection), `:259` (`autoSyncEligible`), `channels/actions.ts:524` (*Sync all*) and
`channelGroupSections.ts:140` (a group's Sync). The automatic tick is off on the live box
(`heartbeatSeconds: 0`), so the scheduler will not act on its own — but one *Sync all* click
in that window sweeps every channel the operator had excluded. No lane's membership moves and
nothing downloads or transcribes differently; it is the sync pool alone.

1. **Stop the editor.** Never migrate under a running one: it holds settings in memory and
   writes them back on its own schedule.
2. `pnpm -C common exec tsx bin/migrate-channel-priority.ts --dry-run` — read the table.
3. `pnpm -C common exec tsx bin/migrate-channel-priority.ts` — it writes
   `settings.json.pre-priority-<ISO>` beside the file first, refusing to overwrite an
   existing backup name, so the backup is not a step anyone can skip.
4. **Start the editor.** The runner re-reads the document per tick; the worker pool and the
   heartbeat arm at boot.

Idempotent: a second run changes nothing.