testsAndMisc/DOCS-installer-fix.md

# Next session: make `install_core_system.sh` actually work on a fresh machine

Paste everything below into a **fresh** Claude session (`/clear` first).

---

`~/src/testsAndMisc/linux_configuration/install_core_system.sh` is the documented
way to set this machine up from scratch. It does not work. Three defects were
found on 2026-08-22 by running the real installer in a disposable Arch VM
(`~/src/utils/vmbox`) rather than by reading it — 2 of its 7 modules cannot install
at all, and a third installs something that silently does nothing.

**Do not trust this file's line numbers without re-checking them.** They were
correct on 2026-08-22; the repo moves.

## The evidence

The sandbox progression, measured with the repo's own hardening checks:

| State                                                    | Result                             |
| -------------------------------------------------------- | ---------------------------------- |
| Bare guest, nothing installed                            | 0 passed / 17 skipped              |
| After `install_core_system.sh --all`                     | 10 passed / 14 skipped             |
| After manually installing guard-lib + the shutdown timer | 14 passed / 10 skipped             |
| After manually running the hosts migration               | **18 passed, 6 skipped, 0 failed** |

The remaining 6 skips are legitimately screen_locker's. The gap between row 2
and row 4 is entirely defects 2 and 3 below: everything needed to reach a green
machine already exists in the repos, but the documented install path never runs it.

## Defect 1 — two module paths no longer exist

`install_core_system.sh` invokes:

- line 129: `bash "$REPO_ROOT/python_pkg/screen_locker/install_systemd.sh"` — **gone**
- line 143: `sudo bash "$REPO_ROOT/python_pkg/steam_backlog_enforcer/install.sh"` — **gone**

Both packages were extracted into their own repos. Verified on disk 2026-08-22:

- `~/src/screen-locker/install_systemd.sh` (5637 b, executable)
- `~/src/steam-backlog-enforcer/install.sh` (3248 b, executable)

"Workout screen locker" is a **CORE** module, so a fresh machine fails on the
first thing the installer does.

Note this makes the installer **cross-repo**: `~/src/testsAndMisc` no longer owns
that code. That is design question (b) below — do not just hardcode `~/src/screen-locker`
and call it done without putting the question to kuhy.

## Defect 2 — guard-lib is required but never installed

`scripts/periodic_background/digital_wellbeing/setup_midnight_shutdown.sh`
depends on `guardctl` and dies with `guardctl not found on PATH`. Nothing in
`install_core_system.sh` installs guard-lib, which lives at
`~/src/utils/guard-lib/install.sh` — a **third** sibling repo.

So the CORE module "Midnight shutdown timer" always fails on a fresh machine.

## Defect 3 — the hosts file-guards are installed only by a one-shot script

`install.sh` in the extracted `hosts-blocker` repo
(github.com/kuhyx/hosts-blocker, checked out at `~/src/hosts-blocker`; it was
`scripts/periodic_background/hosts/install.sh` when this was written)
never installs the
hosts/nsswitch/resolved file-guards. Its own comment block around **line 109**
claims otherwise:

> Enforcement does not depend on these sources being immutable: /etc/hosts
> itself is chattr +i, guard-lib's "hosts" file-guard instance (`guardctl
file-guard status hosts`) watches and re-enforces it against its canonical
> snapshot, and the same instance's bind mount pins it.

That is only true after running
`scripts/single_use/fixes/migrate_hosts_guard_to_guard_lib.sh` (169 lines),
which is filed under `single_use/fixes/` and is not part of any install path.

A fresh machine following the documented path therefore gets `chattr +i` and
**no watcher, no canonical copy, no bind mount** — immutability with nothing
re-enforcing it. Verified both ways in the sandbox: 5 hardening checks stayed
skipped until the migration was run, then passed.

## Two design questions — ask kuhy, do not guess

Run these as a `grilling` round before writing any code.

**(a) Where should defect 3's fix live?** Either `hosts/install.sh` calls the
migration script, or the migration's logic moves into `install.sh` and the
one-shot script is deleted (or becomes a thin wrapper). The first is a smaller
diff; the second stops `single_use/fixes/` from being load-bearing, which is
arguably what "single use" is supposed to mean.

**(b) How should a testsAndMisc installer reach code in sibling repos?**
`~/src/screen-locker`, `~/src/steam-backlog-enforcer` and `~/src/utils/guard-lib` are
separate repos now. Options, none obviously right:

1. **Expect-adjacent** — check for `~/src/screen-locker` etc., fail with a clear
   message naming the repo to clone. Simple; the installer stops being
   self-contained.
2. **Clone if missing** — the installer clones the siblings it needs. Works on
   a truly bare machine; puts network access and repo URLs into an installer
   that currently has neither.
3. **Drop those modules** — `install_core_system.sh` installs only what
   testsAndMisc owns, and each sibling repo installs itself. Cleanest ownership;
   means there is no longer one command that sets up the machine.
4. **Invert entirely** — a top-level bootstrap outside all four repos.

Do not assume `~/` layout is stable; whatever is chosen must fail loudly with
an actionable message rather than silently skipping a module.

## Done — checkable in a sandbox, not a sentence

The fix is done when, in a **fresh** vmbox guest:

```bash
vm share ~/src/testsAndMisc && vm share ~/src/utils
vm new inst
vm run inst 'git clone --no-hardlinks -q /mnt/hostrepo/testsAndMisc ~/tam'
# plus whatever cloning question (b)'s answer implies for the sibling repos
vm run inst 'cd ~/tam && echo y | bash linux_configuration/install_core_system.sh --all'
```

1. Every module reports installed or **explicitly** skipped with a reason —
   zero entries in the installer's own `Failed (...)` summary section.
2. The hardening checks reach **18 passed, 6 skipped, 0 failed**, matching the
   row-4 measurement above, with **no manual steps after the installer**.
   The 6 skips must be the screen_locker ones; if a different 6 skip, that is
   a regression, not a pass.
3. `guardctl file-guard status hosts` in the guest shows a live watcher with a
   canonical copy and a bind mount — not just `chattr +i` on `/etc/hosts`.
4. Re-running the installer a second time is a no-op that still exits 0
   (it must be idempotent; the sandbox makes this cheap to check).

## How to work on this

- **Sandbox first, always.** This is a root installer that writes `/etc`,
  systemd units, pacman hooks and `chattr +i`. Never run it on the host to
  test it. `~/src/utils/vmbox`: `vm new` / `vm run` / `vm reset`. A sandbox pass
  does **not** prove the host is fine — report it that way.
- Installers prompt; `vm run` closes stdin, so pipe `echo y |`.
- vmbox is fast: `vm run` ~14s cold / ~3s warm, `vm reset` ~2s. Reuse one
  sandbox, do not rebuild per command.
- `~/src/utils/vmbox/SESSION_RESULTS.md` has the full 2026-08-22 measurements.
- The 250-line file cap applies (`~/src/utils/file_length`). `install.sh` is at
  130 lines and the migration at 169 — merging them wholesale will breach it,
  which is worth weighing in design question (a).
- `~/src/testsAndMisc` requires a `docs/superpowers/evidence/*.json` artifact for
  any code change (pre-commit gate `ai-evidence-contract`); copy
  `docs/superpowers/evidence/template.json`.

## Out of scope

Do not fix `boot-repair` — its BIOS/GRUB guard landed 2026-08-22 in commit
`aec2b275`. Do not refactor the installer's module-runner machinery
(`run_installer` / `ask_install`); the defects are all in what it points at.