Stamp Each Host With What It Carries, and Reject the Flags the Installer Ignored

[ptr727]

Rolling the safety kit across a fleet needs an answer to "is this machine current", and there was none. #365 tracks machines by tick, a tick records that someone ran something once, and the kit has changed three times since the earliest one. Its own body admits this: "a machine ticked below is not necessarily current." Verifying meant typing three grep commands per host and reading them by eye.

The stamp

Every install writes ~/.claude/agent-safety-stamp.json and prints one pasteable line:

server-2 | Debian GNU/Linux 13 (trixie) | hub 31880f0 | payload a1ea65e4e604308f | agent-safety v1, fleet-bootstrap v1 | 2026-08-11T00:48:58Z

Host name, host type, the hub commit it came from, a digest of the bytes installed, the marker versions actually found in CLAUDE.md, and when.

--report

Read-only. Run it from a fresh hub checkout and it compares that machine against that checkout:

• CURRENT — matches, exit 0
• STALE — with the specific reasons, exit 1
• NOT INSTALLED — no stamp, exit 2

It returns before creating anything, so reporting on a clean machine leaves it clean.

Three judgement calls worth stating

Compared on the payload digest, not the commit. A machine installed from an older commit whose kit bytes never changed is current, and calling it stale sends someone to re-run an installer that would write the same file byte for byte.

The digest covers the installed bytes, not the tree state. A clean commit and a dirty checkout install different content under the same SHA. A dirty install is recorded as dirty, because a stamp that claims a commit identifies the bytes when it does not is the thing this exists to prevent.

Blocks are read back off disk. Not assumed from what the installer meant to write. A block edited or deleted by hand since the install reports stale, and a start marker without its end does not count as present — the half-written case a presence check reads as success.

A defect fixed in passing

main() took no arguments while both wrappers pass "$@" through, so every flag was silently discarded. install.py --help performed a full install instead of printing usage. It now parses, and an unknown flag exits 2 having changed nothing — asserted by comparing the stamp before and after.

Verification

test_install.py, 13 cases, each proving a verdict by reintroducing the state it reports:

• Report on a never-installed machine says so and creates nothing
• A changed payload reports stale; a hand-deleted block reports stale
• The printed remedy actually clears it — re-running returns CURRENT, so the verdict is not a dead end
• A half-written block is not counted as present
• --bogus is rejected with the stamp unchanged; --help prints usage and installs nothing
• Every file the kit deploys is in the digest, checked in both directions: changing each listed file moves the digest, and every file install.py reads is in the list

All cases run against a throwaway CLAUDE_HOME, never the invoking user's.

Wired into the self-test step, because a test that runs nowhere is the defect #664 just found in another gate.

Merge order

This touches the same self-test block as #664. Whichever merges second needs a one-line rebase in that list — I will handle it.

Follow-up not in scope here: the issue body still carries the manual grep instructions. I will rewrite it to the one-command-per-platform form once this lands, so the instructions describe a flag that exists.

[Copilot]

Pull request overview

Adds an install-time “stamp” and a read-only --report mode to the host safety kit so operators can quickly determine whether a machine matches a given hub checkout, and fixes argument parsing so installer flags are no longer silently ignored.

Changes:

• Add stamp generation (~/.claude/agent-safety-stamp.json) and a pasteable one-line summary, plus --report verdicts and exit codes.
• Add a standard-library self-test suite (test_install.py) covering report verdicts, argument handling, and stamp/digest invariants.
• Run the new installer self-tests in the validation workflow.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
host-setup/agent-safety/test_install.py	Adds self-tests that exercise --report, stamping, digest coverage, and CLI flag behavior.
host-setup/agent-safety/install.py	Implements stamping, --report, payload digesting, and proper CLI parsing.
.github/workflows/validate-task.yml	Runs the new installer self-test in CI.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (2)

host-setup/agent-safety/install.py:120

• source_ref() assumes the git executable is available; if it is missing (common on minimal hosts or extracted tarball installs), subprocess.run(["git", ...]) raises FileNotFoundError and the installer/report crashes. Handle the missing-binary case and treat it as vcs: none so the stamp/report still work.

 def git(*args):
r = subprocess.run(["git", "-C", str(HERE), *args], capture_output=True, text=True)
return r.stdout.strip() if r.returncode == 0 else None

host-setup/agent-safety/install.py:208

• report() calls stamp_line(stamp) immediately after parsing JSON. A stamp file can be valid JSON but missing required keys (manual edit, partial write, old/experimental format), which currently triggers a KeyError and crashes instead of returning a controlled "stamp unreadable" verdict. Validate required fields (or catch KeyError/TypeError) and return exit 2 with a clear message.

 print(f"This machine: {stamp_line(stamp)}")

[ptr727]

Answering the two suppressed findings here, since they carry no thread to reply on. Both were correct and both are fixed in 6583586.

install.py:120 — source_ref() crashes when git is absent.

subprocess.run(["git", ...]) raises FileNotFoundError and the installer/report crashes. Handle the missing-binary case and treat it as vcs: none.

Correct, and it fails on exactly the host this is most likely to meet. A tarball install on a minimal box is the normal case for a bootstrap, not an exotic one — and --report, which is documented as read-only and safe, would have crashed there too.

The inner git() helper now catches OSError and returns None, so the stamp records vcs: none and both paths still work. Tested by running the installer with PATH="", which asserts the stamp is written and carries vcs: none. It fails against the previous code.

install.py:208 — report() reads a parsed stamp straight into stamp_line().

A stamp file can be valid JSON but missing required keys (manual edit, partial write, old/experimental format), which currently triggers a KeyError.

Also correct, and it defeated the surrounding intent: the json.JSONDecodeError guard immediately above returns a controlled exit 2, and then the very next line assumed a shape. Valid JSON is not a usable stamp.

Required keys are now checked before the stamp is read, returning exit 2 naming what is missing. Two cases added — a stamp with keys missing, and one holding a non-object at its root — each asserting exit 2 and no traceback.

Totals for this round: ten cases added across the four findings, nine of which fail against the previous code. The tenth is the CRLF equivalence check, which guards a regression rather than reproducing a defect, and I would rather say that than count it as ten.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (2)

host-setup/agent-safety/install.py:148

• payload_digest() hashes the raw bytes of claude-md-*.md, but the installer embeds those snippets via read_text(...).strip() (and preserves CLAUDE.md line endings). That means a change that is stripped away (e.g., trailing newlines/whitespace) will flip the payload digest and report STALE even though a reinstall would write identical on-disk content. Compute the digest over the normalized bytes that would actually be installed (same normalization used for expected_installed_digest()/install write path).

def payload_digest():
"""One digest over the bytes this kit installs, in a fixed order.
Fixed order because a set of files has none, and a digest that depends on directory listing
order reports drift on a machine where nothing changed.
"""
h = hashlib.sha256()
for name in PAYLOAD_FILES:
h.update((HERE / name).read_bytes())
return h.hexdigest()[:16]

host-setup/agent-safety/test_install.py:242

• test_the_digest_covers_every_file_the_kit_installs mutates each payload file by appending only a newline. For the snippet files, the installer reads them with .strip() before embedding, so a trailing newline is not necessarily an installed-byte change. Prefer appending a non-whitespace sentinel so the test remains aligned with the digest representing installed bytes.

 try:
target.write_bytes(original + b"\n")
self.assertNotEqual(install.payload_digest(), baseline,
f"{name} is in PAYLOAD_FILES but changing it did not move the digest")

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (2)

host-setup/agent-safety/install.py:148

• payload_digest() hashes the raw bytes of claude-md-*.md, but the installer reads those snippets via read_text(...).strip() (universal-newline normalized) before writing them. That means a source-only change that does not affect what gets installed (for example, adding/removing trailing newlines/whitespace that strip() removes) can still change payloadDigest and cause --report to print STALE even when the installed content matches what this checkout would write. Consider computing payloadDigest over the effective deployed content (same normalization/strip logic as the installer / expected_installed_digest()), so it only changes when what would be installed changes.

 h = hashlib.sha256()
for name in PAYLOAD_FILES:
h.update((HERE / name).read_bytes())
return h.hexdigest()[:16]

host-setup/agent-safety/install.py:261

• --report aims to return a verdict rather than crash on a hand-edited / corrupted stamp, but the current validation only checks for presence of top-level keys. If the stamp is a JSON object with the required keys but unexpected types (for example, "source": null or "host": "..."), stamp_line(stamp) (and later stamp.get("source", {}).get("dirty")) can raise and turn the report into a traceback. It would be safer to validate the nested shapes/types before calling stamp_line() / accessing nested .get().

 # Valid JSON is not a usable stamp: a hand edit or an older format parses and then breaks the read.
missing = [k for k in STAMP_REQUIRED if k not in stamp] if isinstance(stamp, dict) else ["everything"]
if missing:
sys.stderr.write(f"Stamp at {path} is missing {', '.join(missing)}. "
"Re-run the installer to rewrite it.\n")

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (1)

host-setup/agent-safety/install.py:266

• --report validates only that required keys exist, but not that nested fields have the expected types. A hand-edited or corrupted stamp like {..., "source": "git"} will pass the STAMP_REQUIRED key check and then crash in stamp_line() (src.get(...)), contradicting the goal of returning a verdict instead of a traceback for malformed stamps.

 missing = [k for k in STAMP_REQUIRED if k not in stamp] if isinstance(stamp, dict) else ["everything"]
if missing:
sys.stderr.write(f"Stamp at {path} is missing {', '.join(missing)}. "
"Re-run the installer to rewrite it.\n")
return 2
print(f"This machine: {stamp_line(stamp)}")
# The stamp says what was installed; the machine says what is there now.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (2)

host-setup/agent-safety/install.py:245

• The stamp includes a stampVersion field (and the surrounding comment says readers need to detect shape changes), but STAMP_SHAPE/stamp_problems() never validates stampVersion. That means a future format bump could be mis-read as a valid stamp instead of yielding a clear "re-run installer" verdict.

STAMP_SHAPE = {
"host": dict,
"source": dict,
"payloadDigest": str,
"blocks": dict,

host-setup/agent-safety/install.py:305

• --report decides CURRENT/STALE by comparing the deployed hook + CLAUDE.md blocks against this checkout, but it does not verify that settings.json still registers the PreToolUse hook and the managed permission rules. If a user later removes those entries, --report can still say CURRENT even though the safety kit is effectively inactive.

 live_installed = installed_digest(claude_home)
if live_installed is None:
problems.append("the deployed hook or CLAUDE.md is missing, so the kit is not fully installed")
elif live_installed != current:
problems.append("the installed content differs from what this checkout would write")

[ptr727]

Both suppressed findings on the head are correct and fixed in dc0451a. The second is the most serious finding on this PR.

--report decides CURRENT/STALE by comparing the deployed hook + CLAUDE.md blocks against this checkout, but it does not verify that settings.json still registers the PreToolUse hook and the managed permission rules. If a user later removes those entries, --report can still say CURRENT even though the safety kit is effectively inactive.

Correct, and it defeats the point of the feature. The installer does three things — deploy the hook, register it in settings.json, write the CLAUDE.md blocks — and the report checked two of them. A machine with every byte correct and the PreToolUse entry deleted carries a complete, current, entirely inert kit, and every check here called it CURRENT.

The question this tool exists to answer is whether the guard is in force on that machine. Correct bytes on disk are not a running guard.

registration_problems() now reads settings.json and reports:

• the hook not registered at all, so the guard never runs
• the hook registered more than once, so it runs repeatedly
• a managed permission rule absent
• settings.json missing, unreadable, or not an object

The stamp includes a stampVersion field (and the surrounding comment says readers need to detect shape changes), but STAMP_SHAPE/stamp_problems() never validates stampVersion.

Also correct, and it is the sharper kind of finding: the comment above the field promised exactly what the code did not do. A version carried and never read is a version telling nobody anything. It is now in STAMP_SHAPE as an int, and a value this installer does not write is reported rather than accepted — a mismatch is unreadable in either direction, since a newer stamp holds fields this code does not know and an older one lacks fields it reads.

Cases: nine added, all failing against the previous commit, including that re-running the installer clears an unregistered hook. Thirty-four in the file now.

On this PR overall. Eleven findings across six rounds, every one real, and three of them named holes in the central claim rather than edge cases: presence-without-content, source-bytes-without-normalization, and now bytes-without-wiring. The pattern in my own work is consistent — I checked the thing I had just built and not the thing the feature promises. I would rather that be said here than not.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (1)

host-setup/agent-safety/install.py:338

• report() can incorrectly return CURRENT if CLAUDE.md already contains duplicated/malformed marker blocks at the time of the original install. In that situation blocks_present() returns {}, and because the stamp is generated from that same blocks_present() result, live and stamp["blocks"] both remain empty on later runs; installed_digest() will still hash the first matching block, so the corruption can slip through as CURRENT. Treat any file that contains agent-safety/fleet-bootstrap markers but yields no valid block from blocks_present() as STALE (corrupted markers), regardless of what the stamp recorded.

 live = blocks_present(claude_home / "CLAUDE.md")
problems = []

[ptr727]

Correct, and it is the sharpest finding on this PR. Fixed in 23e80ac.

report() can incorrectly return CURRENT if CLAUDE.md already contains duplicated/malformed marker blocks at the time of the original install. In that situation blocks_present() returns {}, and because the stamp is generated from that same blocks_present() result, live and stamp["blocks"] both remain empty on later runs.

Exactly right, and the reason it slipped past every check I added is that I built the comparison out of one function on both sides. The stamp records what blocks_present() returns and the report compares against what blocks_present() returns, so a case where that function reports nothing is a case where both sides agree perfectly. Two wrong answers agreeing reads as a match. Comparing a value against itself proves only that the reader is deterministic.

marker_corruption() now judges the file alone. Markers present that yield no valid block are reported no matter what the stamp says.

And the remedy was a dead end, which I found while fixing this. The installer used re.sub with no count, replacing every match with the snippet — so a file arriving with two blocks kept two. blocks_present() still returned nothing, the report still said re-run, and re-running produced the identical file. The one case where corruption most needs clearing was the one case the printed remedy could not clear.

It now keeps the first occurrence, drops the rest, and reports how many it removed:

CLAUDE.md -> ~/.claude/CLAUDE.md (agent-safety block updated, 1 duplicate(s) removed)

Cases: five added, all failing against the previous commit, including a stamp hand-edited to record no blocks — which cannot agree its way to a clean verdict any more. Thirty-nine in the file.

Counting honestly. Twelve findings across seven rounds on this PR, every one real. The three that mattered most all had the same shape: I verified the mechanism I had just written rather than the property the feature claims. Presence instead of content, source bytes instead of installed bytes, files instead of wiring, and now a self-comparison instead of an independent read. That is a habit rather than four accidents, and the review caught all four.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (1)

host-setup/agent-safety/install.py:158

• payload_digest() claims to normalize line endings the way the installer writes them, but it only normalizes CRLF (\r\n) and not bare CR (\r). Because the installer reads snippet files in text mode (universal newlines) and then writes them back with \n or \r\n, a snippet file that happens to contain CR-only line endings would install normalized content but compute a different payload digest, causing --report to incorrectly return STALE for otherwise identical installed bytes.

 for name in PAYLOAD_FILES:
raw = (HERE / name).read_bytes().replace(b"\r\n", b"\n")
# A snippet is embedded stripped, so trailing whitespace is not installed content.
# The hook is copied byte for byte, so nothing about it is stripped.
if name.endswith(".md"):
raw = raw.decode("utf-8").strip().encode("utf-8")
h.update(raw)

[ptr727]

Correct, and fixed in 6894146.

payload_digest() claims to normalize line endings the way the installer writes them, but it only normalizes CRLF (\r\n) and not bare CR (\r).

Right, and the claim in the docstring is the part that made it worse: it said "normalized the way the installer writes it" while doing something narrower. The installer reads snippets in text mode, so a bare CR arrives as a newline and installs as one, and a digest that left it alone reported the machine STALE against content it had itself just written.

The underlying cause was four hand-written normalizations across the file, two of which disagreed. They now go through one normalized() helper, so the two sides of the comparison cannot diverge again:

payload_digest -> normalized(read_bytes())
installed_digest -> normalized(hook bytes), normalized(CLAUDE.md text)
the install write -> normalized(existing)

Two cases added, and the first one caught me. My initial version built the CR-only variant with original.replace(b"\n", b"\r") and it failed against the fixed code. The reason is worth recording: these snippet files are CRLF in this repository, so a blind newline replace turns every \r\n into \r\r rather than into a bare CR. The test was wrong, not the fix. It now builds the variant from the normalized form.

The second case asserts the helper directly over CRLF, bare CR, and LF in both bytes and text, since a helper two digests depend on is worth pinning rather than inferring.

Thirteen findings, eight rounds, all real. This one belongs to the same family as the rest: I wrote a docstring describing the property I wanted and then implemented a weaker one, and nothing compared the two. Forty-one cases in the file now.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (2)

host-setup/agent-safety/install.py:135

• source_ref() claims to report whether the checkout is dirty, but the git status call only checks PAYLOAD_FILES. If install.py itself is modified (which can change the installed bytes/behavior), dirty will incorrectly remain false, and the stamp can imply the recorded commit identifies what ran when it does not.

 status = git("status", "--porcelain", "--", *PAYLOAD_FILES)
ref["dirty"] = bool(status)

host-setup/agent-safety/install.py:358

• report() reads the stamp with path.read_text(encoding="utf-8"), which can raise UnicodeDecodeError if the stamp file is corrupted or partially written with non-UTF-8 bytes. That exception is not caught, so --report can crash with a traceback instead of returning the intended exit code 2.

 try:
stamp = json.loads(path.read_text(encoding="utf-8"))
except (json.JSONDecodeError, OSError) as e:
sys.stderr.write(f"Stamp at {path} is unreadable ({e}). Re-run the installer to rewrite it.\n")
return 2

[ptr727]

Correct, and fixed in 3894a87.

report() reads the stamp with path.read_text(encoding="utf-8"), which can raise UnicodeDecodeError if the stamp file is corrupted or partially written with non-UTF-8 bytes. That exception is not caught.

Right. UnicodeDecodeError is a ValueError, not an OSError, and it is raised by the decode before the JSON parser is ever reached — so the handler names the subclass it thought of and misses its sibling. A partially written stamp crashed the read-only report with a traceback, which is precisely what that handler exists to prevent.

Both reads catch ValueError now, which covers JSONDecodeError and UnicodeDecodeError alike.

Two call sites, not one. You named the stamp read; registration_problems() two hundred lines above it reads settings.json with the identical except (json.JSONDecodeError, OSError), and I only added that function three commits ago. I fixed both rather than only the one reported, since a finding names a sample and not the population.

Two cases added, one per site, both failing against the previous code.

Fourteen findings, nine rounds, all real. Four of them have now been the same mistake at different depths: I write a guard for the failure I pictured and it does not cover the failure's siblings. Presence not content, source bytes not installed bytes, files not wiring, CRLF not bare CR, and now one exception subclass not the other.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (1)

host-setup/agent-safety/install.py:586

• The post-install guidance says to run the check "from a fresh hub checkout", but the printed command hard-codes this checkout's absolute path via HERE. That makes the pasteable line easy to reuse incorrectly later (running against an old checkout) and it doesn't match the intent that --report compares against whichever checkout you run it from.

 print(f" stamp -> {stamp_path}")

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (1)

host-setup/agent-safety/test_install.py:474

• test_every_deployed_file_is_in_the_digest doesn’t actually check the deployed snippet files. The regex only matches literal HERE / "..." usages (currently just gh-write-guard.py), while the snippet filenames are referenced via the blocks = [(..., "claude-md-*.md"), ...] list. This makes the test a false-positive: adding a new deployed snippet (or forgetting to add one to PAYLOAD_FILES) could slip through.

 for name in re.findall(r'HERE / "([^"]+\.(?:py|md))"', source):
if name == "install.py":
continue
self.assertIn(name, install.PAYLOAD_FILES,
f"install.py reads {name} but PAYLOAD_FILES omits it, so the digest misses it")

[ptr727]

Correct, and this is the best finding on the PR because it is a finding about a test — the one place a false positive is invisible by construction. Fixed in 25cf480.

test_every_deployed_file_is_in_the_digest doesn't actually check the deployed snippet files. The regex only matches literal HERE / "..." usages (currently just gh-write-guard.py), while the snippet filenames are referenced via the blocks = [...] list.

Exactly right. The test asserted coverage over three files and measured one. It was green, it was named for the property, and it verified almost none of it — and I wrote it specifically to catch a file being left out of the digest.

I did not just widen the regex. A wider pattern is another thing to keep in step with the code. The gap is structural, so the fix is:

CLAUDE_MD_BLOCKS= (
("agent-safety", "claude-md-safety.md"),
("fleet-bootstrap", "claude-md-fleet.md"),
)
PAYLOAD_FILES= ("gh-write-guard.py",) +tuple(filenamefor_, filenameinCLAUDE_MD_BLOCKS)

Adding a block now enters the digest with no second edit, so the omission the test was watching for cannot be made. Verified by appending a fourth block and confirming it derives into the payload list.

Same hazard one level down, which the finding did not name. Three readers — blocks_present, installed_digest, marker_corruption — each carried their own literal ("agent-safety", "fleet-bootstrap"). A new block would have reached whichever ones I remembered to edit. All three read BLOCK_MARKERS now, and a case asserts that literal appears nowhere in the file.

Three cases: the scan reads both sources and asserts it matched more than the hook, the derivation holds, and no reader carries its own pair.

Fifteen findings, ten rounds. This one changes how I read the rest: several of my other cases in this file are the same shape as the one you caught, in that they assert a property and exercise a mechanism. The derivation is worth more than any of them, because it removes the property from the set of things a test has to watch.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.