docs(pmoves-yt): service runbook — two deployment paths run different yt-dlp builds

[POWERFULMOVES]

The pmoves-yt lane had README.md and UPDATE_NOTES.md but no operations doc. This adds
pmoves/docs/services/pmoves-yt/RUNBOOK.md (652 lines) covering bring-up (all six variants), health
verification, the cookie chain, log locations, failure triage by operator-visible symptom, and
teardown.

Every command in it was run on B850/Knuckles and its real output pasted. Claims that could not be
verified from this node are marked UNVERIFIED rather than written as plausible text — §9 lists
all four.

It leads with the discriminator

Because it makes every other answer right or wrong:

	up-yt	up-yt-published
Builds from	../PMOVES.YT — the fork's vendored yt-dlp	pmoves/services/pmoves-yt/Dockerfile
yt-dlp	CHIT signing, NATS publish, SoundCloud fixes, phase9c multi-client	pip install yt-dlp[default] — stock PyPI, without those commits

The published image is built by integrations-ghcr.matrix.json from the path README.md itself
calls "a compatibility mirror/shim, not the source of truth".

Verification sharpened that in two ways

1. The image name is a hint, not the fact. docker-compose.integrations.images.yml overrides
only image: — the base service's build: {context: ../PMOVES.YT} survives the merge,
confirmed with docker compose config on both chains. A node with the submodule checked out can end
up running a locally-built fork image wearing the GHCR name. The runbook therefore gives three
commands, not one, and names /healthz's yt_dlp_version as authoritative.

This refines YTDLP_CURRENCY.md §1b (merged as #2793 mid-session), which maps
ghcr.io/... → "published image (stock PyPI yt-dlp)". The runbook says so explicitly rather than
silently diverging. Both docs agree on the conclusion that matters: when the layers disagree, the
running container wins.

2. RepoDigests does NOT discriminate build-vs-pull. This node's locally-built image carries
one (sha256:bf62dae4...). Checked before documenting it, not after.

Two undocumented failure modes found while verifying

Both in the "healthy but lying" class:

• pmoves-yt on this node runs cookie-less. YT_COOKIES reads the base-compose placeholder
  darkxside.youtube.cookies.txt, that file does not exist (the dir holds only .gitignore), and no
  yt-cookies-vol is mounted. Reading YT_COOKIES is now the documented one-command check for "is
  the cookie chain actually wired in". Stated plainly: up-yt-published and up-yt-hardened are
  cookie-less as written — both use $(DC) and neither passes --profile yt-cookies. Expected on
  those paths, not a fault.
• yt-cookie-writer reports healthy with a dead NATS subscription. Its healthcheck asserts
  only that /tmp/healthy exists — touched once at first subscribe, never removed. Measured: a DNS
  failure at 2026-08-27T14:10:15Z sitting behind a marker file dated Aug 15, FailingStreak: 0,
  RestartCount: 0.

Commands actually run

yt-docs-catalog-smoke (1751 extractors) · yt-jellyfin-smoke (extraction PASSed on
dQw4w9WgXcQ; the FAIL is the Jellyfin bridge on :8093, absent here) · POST /yt/info · bgutil
/ping → 1.2.2 · make -n up-yt-amd (2 amd.yml refs vs 0 for up-yt) · docker compose config
on both chains.

Also documented

• The git submodule update --remote downgrade hazard, with its reproduction: the pin
  ebd39b7f sits on the unmerged feat/upstream-sync-2026.07 (yt-dlp 2026.07.04), while
  .gitmodules declares PMOVES.AI-Edition-Hardened (2026.02.04) — --remote moves it back five
  months.
• AMD/ROCm nodes need the -amd targets (fix(compose): the AMD overlay no Known Road could reach — retroactive review of 6a7499dfc #2798), with the could not select device driver "nvidia"
  symptom and the DeviceRequests check.
• No down-yt Known Road exists (grep -c → 0), so teardown uses docker compose ... stop —
  permitted, since the enforcer's regex blocks only up|restart|down.
• make seed-data destroys pmoves_chunks_qwen3, flagged loudly.
• yt-cookies-status fails from the host on in-network SUPABASE_URL (papercut, not a pipeline fault).

Scope

Version/currency questions are deferred to YTDLP_CURRENCY.md, not restated; §2.1 was compressed
to a pointer once #2793 merged. No Makefile or compose file touched. Register resolved as UNION —
git diff origin/main --numstat shows 8 insertions, 0 deletions on AGNOTE4482PHI.t1.md.

CHIT trail signed: hmac BkvRVrRYkKYV1GD8JtqA4ZUfCxOIGcPduZe9fiITnAE=, kid chit-signing-v01.

🤖 Generated with Claude Code

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 5d1aaffd-efa2-47e3-b93d-964aeb9645fe

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 31b1c1b8bc

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[POWERFULMOVES]

Severity note — this is the delivery artifact, not an edge case

Recording the deployment framing alongside §1.3, because the runbook states the defect correctly but understates who it reaches.

The operator corrected my framing while this PR was in review: this is an infra node on a private AI lab, not a dev node. The repo is public, the nodes are private, and the delivery is public-good — education, community programs, creator collectives. The platform vision states the brand promise as "Local-first autonomy, reproducible provisioning, and self-improving research loops."

Under that structure:

• A community, school, or partner install has no PMOVES.YT submodule to build from.
• So it takes the published path — and pulls the artifact §1.3 documents as unable to start.
• The private mesh works because build: survives the images overlay and it compiles the fork locally.

So up-yt-published is not an edge case. It is the path for everyone outside the lab, and it is the one that fails.

Why no node can catch this

#2800 tagged all ten fleet profiles deployment_class: private-mesh, with esp32/orin/nano/hermes deliberately unset. Every classed node in the fleet takes the build path. There is no node whose normal operation exercises the published image, which is why a real service becoming a shim in #883 went unnoticed for five months while CI stayed green.

That makes this structurally invisible rather than merely missed. It cannot be found by a node noticing; it needs a gate.

Two follow-ups this implies

1. Consider removing pmoves-yt from integrations-ghcr.matrix.json until the shim is fixed. Publishing a green-but-unrunnable image is worse than publishing none — a consumer's failure mode is an import crash rather than an honest absence.
2. Nothing verifies a published image starts. The matrix builds and pushes; no step pulls the result and health-checks it. A docker run --rm <image> + /healthz probe would have caught this in February and would catch the next one.

Point 2 is the generalisable half. Six findings landed today and every one was the same shape — a thing that reports success while doing nothing: a workflow triggering on a tree it never collected, an overlay reachable only via a blocked path, an MCP roster pointing at an unreachable host, a provisioner with no Known Road, a bump workflow that discards its own image, and this. In five of six the only symptom was an absence.

Operator decision on both. Documented here rather than acted on, since removing a published image affects consumers I cannot enumerate from this node.