left4me/docs/superpowers/specs/2026-05-15-janitorial-cleanup.md

Janitorial cleanup checklist

Status: TODO list, not a settled design. Collects the "do later" items that surfaced across multiple plans and handoffs during the 2026-05-14/15 idmap + consolidation work. Each is small and self-contained. Knock them out individually or batch them into a single janitorial PR. None are urgent — the project works fine with all of these still present.

2026-05-15 update: items 1, 3, 4, and 5 resolved by docs/superpowers/plans/2026-05-15-deploy-dir-rethink.md. Item 2 partially resolved by the same plan with a third option the original enumeration didn't list: the truly-dead units (cake.service, nft-mark.service) are deleted, the reactor-emitted set (server@, web, workshop-refresh.{service,timer}, slices) stays as curated examples under deploy/files/. Resolved items left in place below, marked RESOLVED, for archaeology. Remaining live items: 6, 7, 8, 9, 10.

Items

1. left4me-apply-cake — dead code [RESOLVED]

What: deploy/files/usr/local/libexec/left4me/left4me-apply-cake (POSIX sh, ~47 lines) that applies/clears CAKE egress traffic shaping via tc.

Why dead: CAKE migrated to systemd-networkd via network/<iface>/cake metadata in ckn-bw's bundles/network/. The service unit that invoked this helper (left4me-cake.service) is also obsolete (see item 2). The script is currently shipping to /usr/local/libexec/left4me/ on every bw apply via the install glob, but nothing on the system invokes it.

Action: delete deploy/files/usr/local/libexec/left4me/left4me-apply-cake. The deploy will stop installing it on next apply. Existing deployed copy at /usr/local/libexec/left4me/left4me-apply-cake on the test server can be sudo rmd at the same time.

Verification:

sudo find /var/lib/left4me /opt/left4me /usr/local -name 'left4me-apply-cake'
# expect: empty after the rm

2. Obsolete systemd unit files in deploy/files/ [PARTIALLY RESOLVED]

Resolution path chosen: third option not in the original enumeration — only the truly-dead two (left4me-cake.service, left4me-nft-mark.service) were deleted. The reactor-emitted set (left4me-server@.service, left4me-web.service, left4me-workshop-refresh.{service,timer}, l4d2-game.slice, l4d2-build.slice) is retained as curated examples under deploy/files/, locked down by deploy/tests/test_example_units.py. The framing in this item — "all six are equally drift" — was wrong: the reactor-emitted units carry useful signal as readable examples of what ckn-bw's systemd_units reactor emits at apply time. Original body below.

What:

• deploy/files/usr/local/lib/systemd/system/left4me-cake.service
• deploy/files/usr/local/lib/systemd/system/left4me-nft-mark.service
• deploy/files/usr/local/lib/systemd/system/{left4me-web.service,left4me-server@.service,left4me-workshop-refresh.service,left4me-workshop-refresh.timer,l4d2-game.slice,l4d2-build.slice}

Why dead: ckn-bw's systemd_units reactor in bundles/left4me/metadata.py emits these units (and slices) from metadata. The static files in deploy/files/usr/local/lib/systemd/system/ are not consulted by the deploy at all. They drifted out of sync with the reactor-emitted versions (e.g. the reactor uses Slice=l4d2-game.slice with current resource caps, the static file might not). Currently kept as "greppable reference" per the README's table; that's been the framing since the historical-reference era.

Action: decide policy in concert with the deploy-dir-rethink handoff. Either:

• Delete them. They're not the source of truth; the reactor is. The README table loses a row but gains accuracy.
• Keep them but stamp obsolete somewhere visible (e.g. a comment header in each file pointing at the reactor).

Recommendation: delete. The reactor output is what actually ships; the static files are a footgun (someone might edit them thinking they matter).

Verification: find deploy/files/usr/local/lib/systemd/system -type f should match the README's "what's canonical" list.

3. deploy/files/etc/left4me/cake.env [RESOLVED]

What: env file referenced by the obsolete left4me-cake.service.

Why dead: bandwidth lives in node metadata under network/external/cake/Bandwidth in ckn-bw. The env file is not read by anything live.

Action: delete deploy/files/etc/left4me/cake.env.

4. deploy/files/usr/local/lib/left4me/nft/ [RESOLVED]

What: nftables fragment for left4me-nft-mark.service.

Why dead: the central bundles/nftables/ bundle consumes the rules from bundles/left4me/'s defaults in ckn-bw. The static fragment isn't read.

Action: delete deploy/files/usr/local/lib/left4me/ recursively.

5. deploy-test-server.sh's fate [RESOLVED]

Resolution: deleted entirely. Content survives in git history.

What: deploy/deploy-test-server.sh, the historical one-shot bash deploy.

Why ambiguous: the deploy-dir-rethink doc (2026-05-15-deploy-dir-rethink-design.md) calls this out as an open decision. Three options listed there:

• Delete entirely (git history preserves the content).
• Relocate to docs/ as a walkthrough, mark non-executable.
• Keep as-is with a louder warning header.

Action: pick one as part of the broader deploy-dir-rethink work, or as an isolated decision now.

6. bubblewrap references in spec docs [RESOLVED]

Resolution: v1 design spec (2026-05-08-l4d2-script-overlays-design.md) got a top-of-file banner pointing at the v2 spec; body left as-is for archaeology. Stale docstring in l4d2web/services/overlay_builders.py corrected to "hardened systemd-run transient service." Stray "/bwrap" in a test comment cleaned up. Plan-doc references left in place (historical action snapshots).

What: docs/superpowers/specs/2026-05-08-l4d2-script-overlays-design.md (if it still exists) describes the sandbox as using bubblewrap. The actual implementation uses systemd-run with hardening properties — no bwrap binary is invoked.

Why misleading: someone reading the spec would go looking for bwrap in the helper and not find it.

Action: grep the specs for bubblewrap / bwrap and either correct to systemd-run or delete the references. Drive-by correction; no rationale needed beyond "matches reality."

7. Empty / unused _sandbox_script_dir after build-overlay-unit refactor

What (conditional on the build-overlay-unit refactor landing — see 2026-05-15-build-overlay-unit-design.md): if Option B in that doc is chosen (unit fetches script from DB), the _sandbox_script_dir() helper in l4d2web/services/overlay_builders.py and the on-disk /var/lib/left4me/sandbox-scripts/ directory become unused.

Action: if that refactor lands, remove the helper function and the dir. ckn-bw can stop creating the directory.

8. Legacy idmap binds on un-checked instances

What: server@2's stale idmap binds (from the idmap-on-mount era) were manually cleaned during this session's verification. Other server instances (left4me-server@1, …, if any are running or have been recently) may still have orphan binds in PID 1's mount namespace.

Why: the old helper had a _is_mountpoint bug that left binds behind on stop. Our fix (dd918ac) cleaned the bug, but binds created by the old version persist until manual cleanup or reboot.

Action: on the test server, run:

sudo findmnt --task 1 -o TARGET | grep '/var/lib/left4me/runtime/.*/idmap/'

For each result, sudo umount it and remove its parent runtime/<n>/idmap/ directory after all binds for that instance are gone.

Alternative: schedule a host reboot. Reboot wipes the entire mount table and gets everything clean in one step.

9. Optimized Settings files-overlay verification

What: overlay id 8 (Optimized Settings, type files) wasn't included in the rebuild test during the build-time-idmap verification. We only rebuilt the 5 script overlays.

Why low-risk: files overlays are populated by the web app (uid left4me) directly via Python file ops, not through the sandbox helper, so the idmap refactor doesn't touch them. But it's worth a 30-second check.

Action: in the web UI, open overlay 8's detail page. Confirm the files list renders correctly. (Or sudo find /var/lib/left4me/overlays/8 -type f -uid 981 should be empty.)

10. SourceMod 1.13 stable bump (calendar item, not a janitorial fix)

What: the example Sourcemod-overlay script in examples/script-overlays/Sourcemod.sh pins MM_BRANCH=1.12 and SM_BRANCH=1.12. When AlliedModders declares 1.13 stable, the seeded script needs updating.

Why not now: 1.12 is current stable as of 2026-05. AlliedModders bumps stable every ~2-3 years.

Action: set a calendar reminder for late 2026 / early 2027 to check the SourceMod releases page and bump the branch pin if 1.13 has been declared stable. When bumping, also test the rebuild on a non-production server first; plugin compat across major SM versions is occasionally non-clean.

Suggested batching

Items 1, 3, 4 are tiny and self-contained — bundle into a single "delete dead cake-related artifacts" commit.

Items 2 and 6 are deploy/spec cleanup — bundle with the broader deploy-dir-rethink decision.

Items 5, 7 are conditional on other decisions — handle when the prerequisite design choices are made.

Item 8 is an operational check, not a code change — run it once and forget.

Item 9 is a 30-second verification, not a change.

Item 10 is a calendar reminder.

Verification (after the bundle of items 1, 2, 3, 4 lands)

# nothing references the deleted artifacts
git grep -i 'apply-cake\|cake.env\|left4me-nft-mark\|left4me-cake' deploy/

# the deploy artifacts are pruned
find deploy/files -type f | sort

# bw apply still works
cd ~/Projekte/ckn-bw && bw apply ovh.left4me --interactive=no

If bw apply errors with a missing source path, the bundle references one of the deleted files; fix the bundle reference before pushing the deletion.