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`](../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 rm`d 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

**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:
```bash
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](https://github.com/alliedmodders/sourcemod/releases)
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.