fix: the heartbeat URL leaves the command line (C-331, #423)

[Polichinel]

Closes #423 (by hand — Closes #N does not fire on PRs to a non-default branch). Part of #421, Story 2.

HEARTBEAT_URL is a capability: whoever holds the string can send a success ping, mark the monthly pipeline healthy, and silence the dead-man alert permanently. It was an argv element at three curl sites, and /proc/<pid>/cmdline is world-readable (-r--r--r--) while four accounts hold shells on the box. All three now pass it on stdin as a curl config file.

C-331's own prescribed fix was the bug

The entry did not merely describe the problem — it prescribed the remedy, in its body: printf 'url=%s\n'. Unquoted. Measured against curl 7.81.0 before shipping it, with a value carrying a stray space:

form	result
url=%s	parses http://h/uuid, drops the /fail, and sends it anyway
url = "%s"	exit 3, nothing sent

A trailing space or CR — a CRLF-edited .profile, a copy-paste — would have turned the failure ping into a success ping. Silently. The register's own remedy for a fails-green concern carried a fails-green defect, unexamined since 2026-07-31 because a prescribed fix reads like a settled thing.

Shipped form is quoted, and the reason lives in the script's comment rather than only in the register, so it survives the next rewrite.

Drills — control first

A clean scan proves only that the scanner is broken. Canary is a literal not-a-secret string against an unrouted RFC1918 address, so the request hangs until --max-time and stays in flight while /proc is walked. Nothing here is sensitive.

DRILL A — NEGATIVE CONTROL (must LEAK)
  LEAK /proc/1037255 :: curl -fsS --max-time 20 http://10.255.255.1:8099/CANARY-7f3a1e9c-not-a-secret/fail

DRILL B — THE FIX (must be CLEAN), once per ping
  in flight: 1038214 curl -fsS --max-time 20 -K -
  (clean — no process carries the canary in argv)
  in flight: 1039268 curl -fsS --max-time 20 -K -
  (clean — no process carries the canary in argv)
  in flight: 1040235 curl -fsS --max-time 20 -K -
  (clean — no process carries the canary in argv)

DRILL C — DELIVERY, re-run against the three lines extracted VERBATIM from the committed file
  GET /shipped-verbatim/fail
  GET /shipped-verbatim/start
  GET /shipped-verbatim

DRILL D — BEHAVIOUR under set -euo pipefail
  REACHED, rc=0                                   <- fire-and-forget still fires and forgets
  TRAP ran, original exit_code=1 (must be 1)      <- ERR-trap site does not clobber $?
  script exit=1

printf is a bash builtin, so no helper process carries the URL in its own argv either — which is what Drill B establishes, rather than the weaker "stdin implies safety". Drill C was deliberately re-run against text pulled out of the file with grep, not retyped: that proves the file is right, not just the form.

The guard was wrong first

tests/test_heartbeat_secret.py initially asserted "no line contains both curl and HEARTBEAT_URL" — which fails against the fixed script, because printf … "$HEARTBEAT_URL" | curl … legitimately puts both on one line. The property is "HEARTBEAT_URL never appears after the curl token". Drilling the guard is what found that. It now fails on the pre-change file (naming all three offending lines) and passes on this one.

A second test asserts all three pings still exist, so the first cannot be satisfied by deleting them. Neither asserts the printf text, -K -, -fsS, line numbers or indentation — a curl ≥ 8.3 --variable/--expand-url migration should not redden this.

Three stale citations, and the hole that hid them

• ADR-018 cited a line range in refresh_pipeline.sh that had drifted ~55 lines
• ADR-051 cited three line numbers, one of which had never been right
• C-331's own Location field read 93,163,290 against real lines 112/182/309 — in an entry whose trigger was "next edit to this file"

tests/test_docs_citations.py could see none of them: its pattern was \.py:\d+ — .py only. Widened to \.(?:py|sh):\d+ and drilled (reintroduce a .sh:NNN → red). Those three were the only offenders, so it starts green.

Also corrected

docs/guides/server_operations.md said "two signals" while listing three, and a 24-hour grace where the live check is 48 h (observed on the dashboard 2026-08-10). Its two operator verification commands used the argv form — telling the operator to run, on the box, the exact exposure this story removes. Replaced with the stdin form, quoting verified against a local listener before being written down.

Not live on the server

#423's note said "no server change is required — the script is deployed by tag." Per C-343 that is false: bash buffers the script, so this lands one run after a deploy, and deploying is three steps. Worst case it is in production two months from merge, and the argv exposure continues until then. The issue has been corrected.

Residual, left open deliberately

HEARTBEAT_URL still lives in ~/.profile. If that file is not mode 600 it is readable by all four accounts permanently, which would dominate the ≤10 s × 3 window closed here. Its mode is not in evidence; the register entry carries a pending marker rather than an assumption, and the check is stat -c %a /home/views-deploy/.profile.

Also not closed: the process environment (/proc/<pid>/environ, mode -r--------, owner and root only), and root.

Verification

• bash -n scripts/refresh_pipeline.sh → OK
• ruff check src/ tests/ scripts/ → All checks passed
• mypy src/ → Success, 89 source files
• pytest → PYTEST_EXIT=0, zero FAILED (exit captured unpiped)
• docs/validate_docs.sh → PASSED
• Register: 343 IDs, 301 resolved, 39 open (0 T1, 3 T2, 11 T3, 19 T4, 6 deferred), 117 struck, header 1912 ≤ 3500, tier sum == open count, cluster eight open of ten rows

🤖 Generated with Claude Code

[Polichinel]

Ritual complete — /code-review medium → /register-risk → /review-diff → /register-risk

The shell change came back clean. The guard did not, three times.

/code-review medium — one confirmed bug, in the guard

The reviewer independently verified the three curl sites: || true binds to the whole pipeline under pipefail, printf 'url = "%s"\n' "$ARG" never reinterprets % or \ inside the substituted argument (only the fixed format string is escape-processed), local exit_code=$? runs before the heartbeat block so nothing clobbers it, and missing errtrace is a non-issue since every site is || true-guarded anyway. No shell bug.

But tests/test_heartbeat_secret.py had a false negative:

FAIL_URL="$HEARTBEAT_URL/fail"
curl -fsS --max-time 10 "$FAIL_URL"

C-331 fully reintroduced — secret back on argv, readable via /proc/<pid>/cmdline — with the test still green. Not contrived: that is precisely what collapsing the three WET ping lines into a helper would produce, and this file's own docstring anticipates a future rewrite.

And the fix for it didn't work either

Assignment-tracking was added. The drill returned rc=0 where it had to return rc=1: the regex anchored at ^ with no allowance for indentation, and every assignment in that script is indented. The hardening did nothing until it was drilled.

version	claimed	what it actually did
v1	line contains both curl and HEARTBEAT_URL	failed on the FIXED script — printf … | curl … has both on one line
v2	literal HEARTBEAT_URL after curl	passed a two-line reintroduction of the defect — caught by review, not the author
v3	assignment-tracking to a fixpoint	matched no indented assignment — caught by drill, not by reading

v4, drilled four ways:

rc=0  clean tree              (want 0)
rc=1  direct argv form        (want 1)
rc=1  one level indirection   (want 1)
rc=1  two levels indirection  (want 1)

/review-diff — 2 warnings, both mine, both fixed

The test's docstring still described v2's property after the logic moved to a taint set — doc/code mismatch. And bare substring matching would over-match a one-character tainted name (the two-level drill produces A); word boundaries now, which costs nothing and weakens nothing.

/register-risk — 0 new, 1 merged

This is C-336's mechanism a third time — a claim narrower than the property it names, failing green — so it became a second addendum on C-336 rather than a new ID. The generalisation worth keeping:

A guard is a claim about a property, and the claim is usually narrower than the property. Only running it against states it was not written for tells them apart.

Three gaps here, all three failing green.

Verification

• bash -n scripts/refresh_pipeline.sh → OK
• ruff check . → All checks passed
• mypy src/ → Success, 89 source files
• pytest → PYTEST_EXIT=0, zero FAILED (read from the output file, not the task notification — a trailing echo masked a real failure earlier this session)
• docs/validate_docs.sh → PASSED
• Register: 344 IDs, 302 resolved, 39 open (0 T1, 3 T2, 11 T3, 19 T4, 6 deferred), 118 struck, tier sum == open count