felhom-controller/REPORT.md

# REPORT — R-204 item 4 (controller v0.199.0), 2026-08-05

**A rebuilt box declares that it needs a credential.** The box half of the last manual intervention
the 2026-08-04 drill needed. Hub half: `felhom.eu` v0.96.0, reported in that repo's
`REPORT-r204-item4.md`.

## 1. Baselines

`felhom-controller` at `68f195676b91` / v0.198.0 — **exact match**, tree clean, `HEAD == origin/main`.
§4's landmarks held: `backup.OffboxReportStatus` returned `nil` when no target existed (the ambiguity),
and the ACK's `escrow` object was discarded on an unconfigured box because
`EscrowAutoConfirmer.Reconcile` returns early when the box is neither pending nor escrowed.

**Register drift worth flagging:** the task states R-204 is the highest ID in use. It is **R-211**;
grepped before minting, and the hub session mints R-212.

## 2. What changed

**The ACK field stopped being discarded.** `RecordPresence` is called FIRST in `Reconcile`, before
every gate. It lives in the auto-confirmer because that is already the one place the ACK escrow object
arrives and is already wired — a second consumer would be a second wiring point, and this project's
built-but-never-wired count is six. Last-write-wins, not set-only, so a customer RESET turns the
declaration back off; a nil ACK escrow records nothing (absence of a statement is not a statement of
absence); a record failure is logged and does not block the auto-confirm.

**The declaration needs BOTH halves** (`needsOffsiteCredential`): a fresh data area (no repository
password) AND a hub-held recovery package. Freshness alone is a box that never had off-site backups —
declaring on it would make every un-configured box in the fleet ask for a credential. A merely
DISABLED target is the customer's own choice and never declares.

**Inert to every existing reader**, established from the hub's code: `enabled:false` + zero sizes, so
`isStale` short-circuits on `!Enabled` and `fillBand` returns OK on a zero quota/size; an unknown
`state` string is ignored by `encoding/json`. **A configured box's JSON is byte-identical to
v0.198.0's.** The one reader that would have misread it is the hub's `reportHasOffsite`, tightened in
hub v0.96.0.

## 3. Files modified

| File | Change |
|---|---|
| `controller/internal/settings/settings.go` | **new** `HubEscrowIdentityPresent` field + accessors (saves only on a change) |
| `controller/internal/report/escrow_confirm.go` | **new** `RecordPresence` seam, called before every gate |
| `controller/internal/backup/offbox.go` | **new** `OffsiteStateNeedsCredential`, `needsOffsiteCredential`; `State` on the report object |
| `controller/cmd/controller/main.go` | wires `RecordPresence` |
| `controller/internal/backup/offbox_declare_test.go` | **new** — Scenarios A and B + the two exclusions + the byte-compat assertion |
| `controller/internal/report/escrow_presence{,_wiring}_test.go` | **new** — the recorder and its AST wiring test |
| `.githooks/pre-push` | the workspace-root assertion (rider) |

**Commits on `main`:** `1214bae` (the declaration) · `a91f055` (rider) · `992803c` (CHANGELOG).
**Deployed:** `felhom-controller:0.199.0` on demo-felhom 9201 and demo-hp 9201, both healthy.

## 4. Tests and red-proofs

Green gate: `go build ./... && go vet ./... && go test ./...` — **rc=0**.
`python3 controller/scripts/controller_gates.py --fast` — **all eight gates OK**.

| Scenario | Test | Result | Red-proof — what was mutated | Outcome |
|---|---|---|---|---|
| A | `TestOffsiteDeclare_RebuiltBoxDeclaresNeedsCredential` | PASS | dropped the escrow condition from `needsOffsiteCredential` | **Scenario B FAILED** — *"a box that never had off-site backups DECLARED a need… every un-configured box in the fleet would now ask for a credential"*. This is the plausible wrong fix, and B is the guard that catches it. |
| B | `TestOffsiteDeclare_NeverHadOffsiteSaysNothing` | PASS | (as above) | **FAILED** |
| — | `TestOffsiteDeclare_BoxThatStillHoldsItsRepoPasswordDoesNotDeclare` | PASS | — | — |
| — | `TestOffsiteDeclare_DisabledTargetIsNotStranded` | PASS | — | — |
| — | `TestOffsiteDeclare_ConfiguredBoxJSONIsUnchanged` | PASS | — | — |
| — | `TestEscrowConfirm_RecordsPresenceEvenWhenOffboxUnconfigured` (+ nil-ACK, record-failure) | PASS | — | — |
| seam | `TestMainWiresRecordPresence` | PASS | commented out `RecordPresence:` in main.go | **FAILED** — *"EscrowAutoConfirmer is constructed WITHOUT RecordPresence — R-204 item 4 ships inert"* |

## 5. Live validation

1. **The recorder works on a HEALTHY box** — the case that used to return early. Both demo boxes now
   carry `hub_escrow_identity_present = true` in `settings.json`.
2. **The declaration, produced live without wiping a box.** demo-felhom 9201 was arranged
   **reversibly** into the stranded shape (settings + `offbox/` backed up first). The hub received
   report **id=16743**: `{"enabled":false,"escrow_state":"","state":"needs_credential",
   "snapshot_count":0,"repo_size_bytes":0,"quota_gb":0}`. Restored the same minute — report id=16744 is
   healthy. **The single declaration was absorbed by the hub's debounce; no self-heal event fired.**
3. **A push from outside the workspace is refused**, naming the expected root, before the gates run;
   with the assertion removed the same push succeeds. Both directions demonstrated.
4. **Part 4 (the deletion) HALTED at its STOP** — the measured paths do not match the register. See
   `felhom.eu/REPORT-r204-item4.md` §8 and R-212.

**Teardown:** demo-felhom restored and verified (`enabled=True`, `escrow_state=escrowed`,
`repo_password present=True`); the pre-change backup remains at `/root/r204-backup` on that guest.
Scratch clones removed. Nothing provisioned.

## 6. CI and hooks

**`--no-verify` was NOT used.** Every push ran the pre-push gate, including the new workspace-root
assertion. CI runs were confirmed green by head_sha for each push.

## 7. Observations — noticed, NOT acted on

- The workspace-root assertion is per-clone like the rest of the hook, so it binds only an armed
  clone; CI remains the half that is neither per-clone nor skippable (R-168).
- `felhom-agent`'s `reuse-refs` gate incidentally also fails outside the workspace (the shared checker
  lives in the `felhom.eu` sibling). Repo-specific and not a substitute for the assertion.