Skip to content

feat(register): native trackboard reservation adoption (§D.4 Path 1) - #14

Closed
convenientlymike wants to merge 5 commits into
mainfrom
feat/register-adopt-reservation
Closed

convenientlymike wants to merge 5 commits into
mainfrom
feat/register-adopt-reservation

Conversation

@convenientlymike

Copy link
Copy Markdown
Owner

What

Adds adopt_reservation to the Fleet SessionStart hook (register.sh), the authoritative path for a trackboard reservation to become a live agent on the target host. This is scope #3 of the trackboard fleet-agent-D design (docs/fleet-agent-D-v2-design.md §D.4 Path 1) — the signed companion to the daemon/launcher already landed on the trackboard side.

When trackboard mints a reservation targeting this window's cwd + device, register.sh (between reap and the agent-file write) adopts it on-host, deterministically, with no roster-reconcile race:

  • (a) writes identities/<sid>.json — the name/role overlay trackboard's roster reads (survives the heartbeat rewrite by construction).
  • (b) seeds the mission into the window-keyed goalstack on this host (the only reliable cross-device seed, §D.6).
  • (c) hands the device slug to the agent-file writer (a host field).
  • (d) stamps the reservation adopted/bound_sid/bound_host/adopted_via=native and re-signs so trackboard's read path still accepts it.

Why it's safe on a hook that runs on every window

  • Authenticity gate. Reservations are HMAC-SHA256-signed by trackboard; a record whose sig does not verify is a forgery and is ignored (the shared state dir is unauthenticated on the default box). Verify + re-sign reuse trackboard's exact canonicalization via python3 — zero drift; the A1 re-sign-still-verifies selftest is the anti-drift forcing function. Canonical source: trackboard fleet.py:_reservation_sig.
  • Never-guess. Match by explicit $FLEET_RESERVATION (preferred, unambiguous) else a unique cwd+device fallback; ambiguity (>1 match) or a foreign device → adopt NONE, leave pending. Requires a device slug from env — never hostname (a fleet must not guess its own identity).
  • Back-compat, proven by byproduct. With no adopted reservation, ADOPT_HOST is empty and the agent file is byte-identical to the pre-feature baseline (the A2 selftest runs the real register.sh and asserts no host key). Fail-closed (no python3/key) degrades to trackboard's reconcile path — never worse than an un-patched checkout.
  • Guarded so it can never block a normal registration (always returns 0).

Forcing function

selftest-adopt.sh — 12 hermetic bites (each paired with a control that fires), wired into the CI selftest job:

# Bites
A1 explicit-rid adoption writes all four artifacts + a still-valid re-sign (anti-drift)
A2 back-compat: real register.sh writes NO host on a baseline reg; DOES on adopt
A3 unique cwd+device fallback adopts; ambiguity adopts NONE
A4 forged/unsigned reservation ignored; validly-signed adopted
A5 foreign-device reservation never cwd-bound on this host

Verification

  • selftest-adopt.sh — 12/12 green.
  • shellcheck --severity=warning clean on lib.sh / register.sh / selftest-adopt.sh + full-tree sweep.
  • Existing selftest-labels / selftest-collateral still green (no regression).

Host-verify owed (not checkable in CI)

The exact goalstack binary resolution + the launcher exporting $FLEET_RESERVATION/TRACKBOARD_DEVICE_SLUG are runtime facts on the deploy host — smoke with a live trackboard mint before relying on the on-host mission seed.

🤖 Generated with Claude Code

convenientlymike and others added 5 commits September 11, 2026 11:12
… wiring (B7)

Vendored from the trackboard telemetry slice-3 B7 co-land (trackboard @ 9a45077). tb_kpi.sh is a
side-effect-free sourced lib: resolves the trackboard checkout on this box (fail-loud, never a lying default),
runs `python3 -m trackboard.telemetry_report` on a bare python3 via PYTHONPATH=<checkout>/src, and breadcrumbs
LOUD (marker + board note) if unwired — never a silent no-op. heartbeat.sh sources it + calls _tb_kpi
backgrounded/fail-open after ensure_self_registered.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…board slice-5 #8b-2)

Advance the per-target cursor only at a terminal disposition (gone/live/successful-wake); a throttle deferral
(kill-switch/rate-limit/cooldown) holds the cursor so the next scan retries — the rate cap becomes a staggerer,
not a dropper. Selftest gains the DEFER-NOT-DROP control.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…ath 1)

When trackboard mints a reservation targeting this window's cwd+device, adopt
it on the target host at SessionStart — the AUTHORITATIVE adoption path
(deterministic, on-host, no roster-reconcile race).

adopt_reservation (lib.sh), called from register.sh between reap and the
agent-file write, guarded so it can NEVER block a normal registration:
  (a) writes identities/<sid>.json (the name/role overlay trackboard reads);
  (b) seeds the mission into the WINDOW-KEYED goalstack on this host (the only
      reliable cross-device seed, §D.6);
  (c) hands the device slug to register.sh's agent-file writer (host field);
  (d) stamps the reservation adopted/bound_sid/bound_host/adopted_via=native
      and RE-SIGNS so trackboard's read path still accepts it.

Load-bearing invariants (selftest-adopt.sh — 12 bites, wired into CI):
- authenticity: reservations are HMAC-SHA256-signed by trackboard; a record
  whose sig doesn't verify is a forgery and is IGNORED. The verify + re-sign
  reuse trackboard's exact canonicalization (sorted-key, tight-separator JSON
  minus `sig`) via python3 — zero drift; the A1 re-sign-still-verifies bite is
  the anti-drift forcing function. Canonical source: trackboard fleet.py
  `_reservation_sig`.
- never-guess: match by explicit $FLEET_RESERVATION (preferred) else a UNIQUE
  cwd+device fallback; ambiguity (>1) or a foreign device → adopt NONE, leave
  pending. Requires a device slug from env — never `hostname`.
- back-compat: with no adopted reservation, ADOPT_HOST is empty and the agent
  file is byte-identical to the pre-feature baseline (A2 bite via real
  register.sh). Fail-closed (no python3/key) degrades to trackboard reconcile —
  never worse than an un-patched checkout.

shellcheck-clean (--severity=warning); existing selftests still green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@convenientlymike

Copy link
Copy Markdown
Owner Author

Superseded — native reservation adoption was already merged by #13 (feat/native-reservation-adopt, 2026-09-11) while my local main was stale. The merged adopt.sh is strictly more complete than this branch: it has the same HMAC authenticity gate, explicit-$FLEET_RESERVATION path (with path-traversal sanitization), cwd+host fallback with ambiguity→adopt-NONE, re-sign, and fail-OPEN — and is jq/openssl-native (no python3 hard-dependency), in a cleanly separated adopt.sh file. Shipping this would create a second divergent implementation (canonical-single-source violation) and conflict on selftest-adopt.sh. Closing; the merged implementation stands.

@convenientlymike
convenientlymike deleted the feat/register-adopt-reservation branch September 12, 2026 13:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant