Bootstrap-marker: per-session HMAC provenance + round-trip test

[michael-wojcik]

Background

The bootstrap marker introduced by PR #663 (closes #662) carries a SHA256 fingerprint over session_id|plugin_root|plugin_version|schema_version. The fingerprint is documented as a fingerprint, not a MAC — all signature inputs are same-user-readable. The integrity property bounds typo / wrong-window foot-guns rather than same-user adversaries.

This issue tracks two follow-ups identified during PR #663 review that are out-of-scope for the patch but worth doing.

Task A — Per-session HMAC marker provenance

Replace the bare SHA256 fingerprint with an HMAC keyed on a session-derived secret that is not filesystem-readable from the same-user surface. Candidates for the key derivation:

• A per-session ephemeral key written by the harness into a memory-only env-var (no filesystem trace)
• A key derived from ~/.claude/keyring/ or platform keychain, accessed only by the bootstrap producer

Net effect: a same-user adversary who can read all filesystem state cannot forge a marker because they lack the keying material the producer used. Lifts the marker from "fingerprint" (typo defense) to "MAC" (limited adversarial defense, bounded by the keying-material disclosure surface).

This is not required for v4.1.3's threat model. Surfaced as security-blind S-1 in PR #663 review with verdict "blocking-but-architectural". Resolved as deferred because the marker's documented role is fingerprint-not-MAC; the architectural question is whether the role itself should change.

Task B — Marker round-trip test

Add a unit test that exercises the full round-trip:

1. Bootstrap producer writes the marker
2. bootstrap_gate.is_marker_set validates the marker
3. Counter-test: mutate each marker field independently and assert is_marker_set returns False

Currently the producer (heredoc in commands/bootstrap.md, soon a hook per #664) and the verifier (bootstrap_gate.is_marker_set) are tested separately. A round-trip test catches drift between the two surfaces — particularly relevant once #664 lands and the producer migrates to a hook.

Surfaced by architect-blind in PR #663 review as Future #1.

Relationship to other follow-ups

• Hook-driven bootstrap marker write #664 — Hook-driven bootstrap marker write. Migrates the producer to a hook. Independent of this issue's tasks but the round-trip test (Task B) becomes more valuable post-Hook-driven bootstrap marker write #664 because the producer logic will live in Python rather than markdown.
• PR Dispatch-protocol hardening: rename Task→Agent + dispatch_gate + task_lifecycle_gate + bootstrap_gate F24/F25 (#662) #663 (closed) — established the fingerprint-not-MAC framing this issue's Task A would update.

Out of scope

• Replacing the fingerprint with a per-session HMAC requires rethinking the keying-material disclosure model — see Task A's bullet list. This is a design decision, not a patch.
• The bootstrap-ritual pre-condition checks (team config exists, secretary spawned, paused-state surfaced) are tracked under Hook-driven bootstrap marker write #664's hook design and explicitly out-of-scope here.