Compare the Installed Bytes, Not Just the Markers That Delimit Them

Four review findings, all real.
`--report` compared marker versions and the source payload, and never what
is actually on the machine. A block edited between its own markers left the
version untouched and reported CURRENT, which is most of what "has someone
weakened this by hand" means. The deployed hook is not marker-delimited at
all, so a modified or deleted one was invisible the same way.
The installed bytes are now digested and compared against what this
checkout would write: the hook, and each block as it appears in CLAUDE.md.
Line endings are normalized first, so a machine holding identical text with
CRLF is current rather than drifted.
`blocks_present` accepted any equal number of start and end markers, so a
duplicated block reported present and named the first version while the
second silently governed. It now requires exactly one pair.
`source_ref` let FileNotFoundError escape when git is absent, crashing both
the install and the read-only report on exactly the minimal host a tarball
install targets. It records `vcs: none` instead.
`report` read a parsed stamp straight into `stamp_line`, so a hand-edited
or partially written file raised KeyError rather than returning a verdict.
Required keys are checked first.
Ten cases added. Nine fail against the previous code.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: ptr727

host-setup/agent-safety/install.py

@@ -116,7 +116,12 @@ def source_ref():
  to prevent. A checkout that is not a git tree at all (an extracted tarball) says so.
  """
 defgit(*args):
-r=subprocess.run(["git", "-C", str(HERE), *args], capture_output=True, text=True)
+# A host with no git is the normal case for a tarball install, and it is not an error here.
+# Letting FileNotFoundError escape would crash both the install and the read-only report.
+try:
+r=subprocess.run(["git", "-C", str(HERE), *args], capture_output=True, text=True)
+exceptOSError:
+returnNone
 returnr.stdout.strip() ifr.returncode==0elseNone
 
 sha=git("rev-parse", "HEAD")
@@ -155,25 +160,67 @@ def blocks_present(claude_md):
 found= {}
 formarkerin ("agent-safety", "fleet-bootstrap"):
 # A start marker alone is a half-written block, which a presence check reads as installed.
+# Exactly one pair, since the installer writes one and a duplicate is a corrupted file.
+# Two blocks mean the second silently governs, and reporting the first as current hides that.
 starts=re.findall(rf"<!-- {marker} (v\d+) start -->", text)
 ends=re.findall(rf"<!-- {marker} (v\d+) end -->", text)
-ifstartsandstarts==ends:
+iflen(starts) ==1andstarts==ends:
 found[marker] =starts[0]
 returnfound
 
 
+definstalled_digest(claude_home):
+"""A digest over the bytes actually on this machine, or None where the kit is not fully there.
+
+ Markers and versions answer whether a block is present, and nothing about its content, so a
+ block edited between its own markers reports current under a presence check. The hook is not
+ marker-delimited at all, so a modified or deleted one is invisible the same way.
+
+ Line endings are normalized first: CLAUDE.md keeps whatever endings it had, and a machine that
+ holds identical text with CRLF is current rather than drifted.
+ """
+hook=claude_home/"hooks"/"gh-write-guard.py"
+claude_md=claude_home/"CLAUDE.md"
+ifnothook.is_file() ornotclaude_md.is_file():
+returnNone
+h=hashlib.sha256()
+h.update(hook.read_bytes().replace(b"\r\n", b"\n"))
+text=claude_md.read_text(encoding="utf-8", errors="replace").replace("\r\n", "\n")
+formarkerin ("agent-safety", "fleet-bootstrap"):
+found=re.search(rf"<!-- {marker} v\d+ start -->.*?<!-- {marker} v\d+ end -->", text, re.DOTALL)
+ifnotfound:
+returnNone
+h.update(found.group(0).encode("utf-8"))
+returnh.hexdigest()[:16]
+
+
+defexpected_installed_digest():
+"""The same digest computed from this checkout, naming what a run here would leave behind."""
+h=hashlib.sha256()
+h.update((HERE/"gh-write-guard.py").read_bytes().replace(b"\r\n", b"\n"))
+forfilenamein ("claude-md-safety.md", "claude-md-fleet.md"):
+h.update((HERE/filename).read_text(encoding="utf-8").strip().replace("\r\n", "\n").encode("utf-8"))
+returnh.hexdigest()[:16]
+
+
 defbuild_stamp(claude_home, installed):
 """The record written to the machine after an install, or computed live for a report."""
 return {
 "stampVersion": STAMP_VERSION,
 "host": host_facts(),
 "source": source_ref(),
 "payloadDigest": payload_digest(),
+"installedDigest": installed_digest(claude_home),
 "blocks": blocks_present(claude_home/"CLAUDE.md"),
 "installedUtc": installed,
  }
 
 
+# Checked before a stamp is read, so a hand-edited or older-format file gives a verdict rather than a traceback.
+# A partial write produces valid JSON with keys missing.
+STAMP_REQUIRED= ("host", "source", "payloadDigest", "blocks", "installedUtc")
+
+
 defstamp_line(stamp):
 """One line naming the machine and what it carries, short enough to paste into a checklist."""
 host=stamp["host"]
@@ -205,13 +252,26 @@ def report(claude_home):
 except (json.JSONDecodeError, OSError) ase:
 sys.stderr.write(f"Stamp at {path} is unreadable ({e}). Re-run the installer to rewrite it.\n")
 return2
+# Valid JSON is not a usable stamp: a hand edit or an older format parses and then breaks the read.
+missing= [kforkinSTAMP_REQUIREDifknotinstamp] ifisinstance(stamp, dict) else ["everything"]
+ifmissing:
+sys.stderr.write(f"Stamp at {path} is missing {', '.join(missing)}. "
+"Re-run the installer to rewrite it.\n")
+return2
 print(f"This machine: {stamp_line(stamp)}")
-# The stamp says what was installed; the file says what is there now.
+# The stamp says what was installed; the machine says what is there now.
 # A block edited or deleted by hand since the install makes both true and only the second current.
 live=blocks_present(claude_home/"CLAUDE.md")
 problems= []
 ifstamp.get("payloadDigest") !=current:
 problems.append("payload digest differs from this checkout")
+# Markers answer presence and say nothing about content, so the installed bytes are compared too.
+# This is what catches a block edited between its own markers, and a modified or deleted hook.
+live_installed=installed_digest(claude_home)
+iflive_installedisNone:
+problems.append("the deployed hook or CLAUDE.md is missing, so the kit is not fully installed")
+eliflive_installed!=expected_installed_digest():
+problems.append("the installed content differs from what this checkout would write")
 iflive!=stamp.get("blocks"):
 problems.append(f"CLAUDE.md now holds {liveor'no blocks'}, where the stamp recorded {stamp.get('blocks') or'none'}")
 ifstamp.get("source", {}).get("dirty"):

host-setup/agent-safety/test_install.py

@@ -122,6 +122,103 @@ def test_an_absent_file_yields_no_blocks_rather_than_raising(self):
 self.assertEqual(install.blocks_present(self.home/"nothing.md"), {})
 
 
+classTestInstalledContent(StampCase):
+"""Presence is not currency. These are the cases markers and versions cannot see."""
+
+deftest_a_block_edited_between_its_own_markers_reports_stale(self):
+"""The marker and version are untouched, so a presence check calls this machine current."""
+self.install()
+text=self.md.read_text(encoding="utf-8")
+edited=text.replace("<!-- agent-safety v1 start -->",
+"<!-- agent-safety v1 start -->\nSomeone weakened this rule by hand.")
+self.assertNotEqual(edited, text)
+self.md.write_text(edited, encoding="utf-8")
+# Presence is unchanged: the markers and versions still read exactly as before.
+self.assertEqual(install.blocks_present(self.md), {"agent-safety": "v1", "fleet-bootstrap": "v1"})
+r=run(self.home, "--report")
+self.assertEqual(r.returncode, 1, r.stdout+r.stderr)
+self.assertIn("installed content differs", r.stdout)
+
+deftest_a_modified_hook_reports_stale(self):
+"""The hook is not marker-delimited, so nothing else on this machine would notice."""
+self.install()
+hook=self.home/"hooks"/"gh-write-guard.py"
+hook.write_text(hook.read_text(encoding="utf-8") +"\n# neutered\n", encoding="utf-8")
+r=run(self.home, "--report")
+self.assertEqual(r.returncode, 1, r.stdout+r.stderr)
+self.assertIn("installed content differs", r.stdout)
+
+deftest_a_deleted_hook_reports_stale_rather_than_crashing(self):
+self.install()
+ (self.home/"hooks"/"gh-write-guard.py").unlink()
+r=run(self.home, "--report")
+self.assertEqual(r.returncode, 1, r.stdout+r.stderr)
+self.assertIn("not fully installed", r.stdout)
+
+deftest_identical_content_with_crlf_is_current_rather_than_stale(self):
+"""CLAUDE.md keeps the endings it had, and a Windows host is not drifted for that alone."""
+self.install()
+raw=self.md.read_bytes()
+self.md.write_bytes(raw.replace(b"\n", b"\r\n"))
+r=run(self.home, "--report")
+self.assertEqual(r.returncode, 0, r.stdout+r.stderr)
+self.assertIn("CURRENT", r.stdout)
+
+deftest_reinstalling_clears_an_edited_block(self):
+self.install()
+text=self.md.read_text(encoding="utf-8")
+self.md.write_text(text.replace("<!-- agent-safety v1 start -->",
+"<!-- agent-safety v1 start -->\nedited"), encoding="utf-8")
+self.assertEqual(run(self.home, "--report").returncode, 1)
+self.install()
+self.assertEqual(run(self.home, "--report").returncode, 0)
+
+
+classTestDuplicateBlocks(StampCase):
+deftest_a_duplicated_block_is_not_reported_as_present(self):
+"""Two blocks mean the second silently governs, and naming the first hides that."""
+self.install()
+text=self.md.read_text(encoding="utf-8")
+block=re.search(r"<!-- agent-safety v1 start -->.*?<!-- agent-safety v1 end -->",
+text, re.DOTALL).group(0)
+self.md.write_text(text+"\n"+block+"\n", encoding="utf-8")
+self.assertNotIn("agent-safety", install.blocks_present(self.md))
+
+deftest_a_duplicated_block_reports_stale_rather_than_current(self):
+self.install()
+text=self.md.read_text(encoding="utf-8")
+block=re.search(r"<!-- agent-safety v1 start -->.*?<!-- agent-safety v1 end -->",
+text, re.DOTALL).group(0)
+self.md.write_text(text+"\n"+block+"\n", encoding="utf-8")
+r=run(self.home, "--report")
+self.assertEqual(r.returncode, 1, r.stdout+r.stderr)
+
+
+classTestDegradedEnvironments(StampCase):
+deftest_a_host_without_git_stamps_rather_than_crashing(self):
+"""A tarball install on a minimal host has no git, which is normal rather than an error."""
+env=dict(os.environ, CLAUDE_HOME=str(self.home), PATH="")
+r=subprocess.run([sys.executable, str(INSTALL)], capture_output=True, text=True, env=env)
+self.assertEqual(r.returncode, 0, r.stdout+r.stderr)
+stamp=json.loads(self.stamp.read_text(encoding="utf-8"))
+self.assertEqual(stamp["source"]["vcs"], "none")
+
+deftest_a_stamp_missing_required_keys_gives_a_verdict_rather_than_a_traceback(self):
+self.install()
+self.stamp.write_text(json.dumps({"stampVersion": 1}) +"\n", encoding="utf-8")
+r=run(self.home, "--report")
+self.assertEqual(r.returncode, 2)
+self.assertIn("missing", r.stderr)
+self.assertNotIn("Traceback", r.stderr)
+
+deftest_a_stamp_holding_a_non_object_gives_a_verdict_rather_than_a_traceback(self):
+self.install()
+self.stamp.write_text("[]\n", encoding="utf-8")
+r=run(self.home, "--report")
+self.assertEqual(r.returncode, 2)
+self.assertNotIn("Traceback", r.stderr)
+
+
 classTestStampContent(StampCase):
 deftest_the_stamp_names_the_machine_the_source_and_what_was_installed(self):
 self.install()