felhom-agent/REPORT.md

# REPORT — v0.63.0: B3 + B2 fresh-install fixes (token reload-on-miss + guesthook dir)

**Date:** 2026-07-03 · **Class:** implementation, correctness+security discipline (agent v0.62.0 →
**v0.63.0**, live on felhom-pve) · **Source findings:**
`felhom.eu/documentation/audits/DRILL-day0-cleanroom-2026-07-03.md` B3/B2.

## Baselines & commits

| What | Value |
|---|---|
| Base | `84f3f7d` (v0.62.0, as spec'd) |
| Fix commit | `f31a76f` — v0.63.0: B3+B2 (tokenstore.go, guesthook/install.go, sudoers, tests, CHANGELOG, REUSE) |
| Docs commit | (this one — REPORT/CONTEXT) |

## What changed

- **B3 — `TokenStore.Lookup` reload-on-miss** (`internal/localapi/tokenstore.go`): the one-shot
  provisioner Mints into the shared append-only JSONL while the daemon serves Lookup from an index
  built once at open — the daemon 401'd any token minted after it started (the drill's
  `/controller/swap: HTTP 401` until a manual restart). Lookup now re-reads the file once on a miss
  (`reloadLocked()`, factored from `load()`; idempotent under `apply`'s last-write-wins) and
  re-checks with the same constant-time compare, all under the existing single mutex. Append-only
  size short-circuit: an unknown token against an unchanged file costs one `stat`, no re-read
  (`loadedSize` kept accurate by in-process `Mint`). Fail-closed on an unreadable store; missing
  file = empty. Entirely behind the `TokenAuthority` seam — `server.go` untouched. No token/hash
  material logged (nothing new is logged at all).
- **B2 — `guesthook.InstallSnippet` ensures the snippets dir** (`internal/guesthook/install.go`):
  fenced `mkdir -p /var/lib/vz/snippets` before the `install` op (fresh PVE lacks the dir; `install`
  without `-D` fails ENOENT — the drill's silent no-hook finding).
  `configs/felhom-agent.sudoers` FELHOM_GUESTHOOK gains exactly the one grant
  `/usr/bin/mkdir -p /var/lib/vz/snippets` (comment ties it to B2). Kept the separate-mkdir shape —
  `install -D` would have changed the allowlisted install argv.

## Tests & red-proofs (both run, shown failing, restored; `git diff` clean)

| Test | Asserts | Result |
|---|---|---|
| `TestTokenStore_ReloadOnMiss_CrossProcessMint` (Scenario A) | token minted by a SECOND store handle after the daemon handle opened resolves to (120,true) | PASS. **Red-proof:** pre-fix Lookup shape (plain miss, no reload) → FAIL with `got (0,false), want (120,true)` — the exact drill 401 |
| `TestTokenStore_ReloadOnMiss_BoundedReloads` (Scenario B) | unknown token → (0,false); exactly 1 reload after an external append; 0 further reloads on an unchanged file (size short-circuit) — no loop, no per-candidate re-read | PASS |
| `TestTokenStore_ReloadOnMiss_RemintCoherence` (Scenario C) | cross-process rotation: new hash → (120,true), rotated-out hash 401s, `byHash`/`byVMID` coherent after full reload | PASS |
| `TestTokenStore_ReloadOnMiss_MissingFile` (§8 edge) | store deleted → fail closed, no crash | PASS on linux (felhom-pve run); skipped on Windows (can't unlink an open handle) |
| `TestInstallSnippet_EnsuresSnippetsDirFirst` (Scenario D) | a `mkdir -p /var/lib/vz/snippets` op with exactly the sudoers-fenced argv PRECEDES the install op | PASS. **Red-proof:** mkdir call removed → FAIL with `no mkdir -p /var/lib/vz/snippets op issued … calls: [[install …]]` |
| Pre-existing suites | tokenstore_test.go originals, `TestInstallSnippet_RandomTempName` (only adapted to filter install calls from the recorded vector — assertions unchanged), full repo | all PASS; green gate `go build && go vet && go test ./...` exit 0 |

## Deploy verification (felhom-pve)

- Built on 180 from `f31a76f`; binary backed up as `felhom-agent.bak-0.62.0`; **sudoers shipped WITH
  the binary** (CRLF-stripped, `visudo -cf` on the file AND the live /etc/sudoers context: parsed OK;
  the new mkdir grant present).
- Service active; `--selftest` OK (incl. `pool read pool "felhom", 1 member`); daemon hub report:
  **agent 0.63.0, 47/47 capabilities ok, `pve:pool-read` ok** (host_reports id 2412). No
  reassert/rebind or error lines in the journal after restart.
- Published to Gitea: `felhom-agent/0.63.0`, HTTP 201, sha256 `b4a89c81c33d51ea…`.
  **OPERATOR FOLLOW-UP: bump the hub Day-0 artifact manifest to agent 0.63.0** (password-gated UI —
  CC cannot). Until then, fresh installs fetch 0.62.0 and still need the D.1b restart.

## Scenario E method + result (stated per §7-E; live store NOT polluted)

felhom-pve's guest 9201 already has its token in the daemon index, so a live swap cannot reproduce
the fresh-install miss, and minting into the production store is forbidden. Method used (the spec's
sanctioned alternative): (1) **compiled the localapi test binary on 180 and ran the full TokenStore
suite ON felhom-pve** — all 4 reload-on-miss tests PASS on the real platform, including the
linux-only deleted-file case; (2) **live hit-path/no-regression:** the in-guest controller's
`agent-channel-health` scheduler job completed cleanly every minute after the restart (no 401, no
channel event) — the deployed daemon authorizes the existing token exactly as before.

## Guide follow-through (felhom.eu)

D.1b's unconditional "restart the agent first" step was **narrowed, not dropped**: the fix is
deployed and platform-proven, but the Day-0 manifest still vouches agent 0.62.0, so a box installed
today still gets a pre-fix agent. The guide now says: restart first only when the installed agent is
< v0.63.0; the troubleshooting row records the fix version. Drill ledger B2/B3 marked FIXED
v0.63.0. (The step drops entirely once the manifest vouches ≥ 0.63.0.)

## Observations (not acted on)

- The one-shot `--selftest=hub` report carries an EMPTY `capabilities` list (the probe is composed
  only into the daemon loop) — a hub-side capability checker reading the newest report could
  transiently see 0 capabilities after an operator runs the one-shot. Cosmetic today; worth a look
  when touching the capability checker.
- `OpenTokenStore` calls `load()` before `MkdirAll(dir)` — harmless (read tolerates ENOENT) but the
  ordering reads oddly; left as-is (out of scope).