fix: leverage sensors write state JSON with a trailing newline (BRO-1973, v0.37.1)

[broomva]

Closes BRO-1973 — https://linear.app/broomva/issue/BRO-1973

The defect

leverage-sensor.py:364 and leverage-ship-sensor.py:330 both serialize their snapshot with json.dump(..., indent=2) and stop — no POSIX trailing newline. The sibling JSONL write in the very same store() (f.write(json.dumps(record) + "\n")) has always been correct, so this is an inconsistency inside one function, not a deliberate format choice.

A bstack-governed repo that tracks .control/leverage-state.json or .control/leverage-ship-state.json therefore goes git-dirty after every session, and formatter gates (biome / ultracite / prettier) report Formatter would have printed … — so bun run lint fails spuriously on a repo that is otherwise green.

Observed live downstream: a composed-on-main verify failed on lint for exactly this and nothing else. Byte-confirmed with od -c — committed copy ends 7d0a 7d0a, working copy ends 7d0a 7d.

The ship sensor was not in the original report; it is the same defect at leverage-ship-sensor.py:330 and was reproducing live in the same downstream repo at the time of writing.

.gitignore-ing the state file masks the symptom rather than fixing it — the sensor is emitting a malformed text file either way, and any fresh bstack bootstrap that commits its state hits it.

The fix

f.write("\n") after each json.dump. The ship sensor's write stays inside its tempfile + os.replace atomic swap, so a concurrent reader still never observes a partially-written file.

New regression test

tests/leverage-state-trailing-newline.test.sh — 10 assertions, fully hermetic (the ship sensor is driven with an empty repo allowlist, so it makes zero gh calls: no network, no auth required in CI):

• both .control/*.json snapshots end with 0x0a (checked via tail -c 1 | od, not a text-mode read, so an editor cannot mask it)
• .control/leverage-metrics.jsonl still ends with \n — guards the sibling write that was already correct
• both files still parse as JSON with the newline appended
• exactly one trailing newline after a second run — the state file uses "w", so this catches an append/truncate confusion
• the ship sensor's atomic swap leaves no .ship-*.tmp behind

Test plan

Gate	Result
tests/leverage-state-trailing-newline.test.sh	8 passed, 0 failed
Full tests/*.test.sh (37 files)	all pass
tests/canary/*.test.sh (5 files)	all pass
bash scripts/doctor.sh --quiet	100/100 checks passed
shellcheck --severity=warning on the new test	clean
python3 -m ast on both sensors	parses

Mutation proof — each fix is independently load-bearing:

• revert only leverage-sensor.py's f.write("\n") → 3 failures, all in the main-sensor block (5 passed, 3 failed)
• revert only leverage-ship-sensor.py's f.write("\n") → 1 failure, in the ship block (7 passed, 1 failed)
• both restored → 8 passed, 0 failed

Release

Patch bump 0.37.0 → 0.37.1 per RELEASE.md ("Bug fixes … safe to auto-upgrade"), with the matching ## 0.37.1 CHANGELOG section for validate-release.yml.

Migration

None. Existing tracked state files pick up the newline on the next sensor run — a one-line diff to commit once, after which the file stops moving.

Noted, not fixed here

Running scripts/doctor.sh or the canary suite inside the bstack checkout itself generates untracked METALAYER.md + schemas/*.json in the working tree. Deliberately left out of this diff; worth a .gitignore entry or a --workspace redirect in a follow-up.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • Sensor-generated JSON state files now consistently end with a standard trailing newline.
  • Repeated sensor runs no longer add extra blank lines or leave temporary files behind.
  • Existing state files are updated automatically on the next sensor run; no migration is required.

• Tests

  • Added regression coverage for newline formatting, JSON validity, repeated writes, and atomic state updates.

• Release

  • Updated the release version to 0.37.1.

[coderabbitai]

📝 Walkthrough

Walkthrough

Both leverage sensors now append POSIX trailing newlines to serialized JSON state output. A regression test verifies newline presence, JSON parsing, repeated rewrites, and atomic temporary-file cleanup. Release metadata is updated to version 0.37.1.

Changes

State output newline contract

Layer / File(s)	Summary
Sensor JSON newline writes scripts/leverage-sensor.py, scripts/leverage-ship-sensor.py, tests/leverage-state-trailing-newline.test.sh	Both sensors append trailing newlines to JSON output. The regression test validates state and metrics files, repeated rewrites, JSON parsing, and cleanup of temporary ship-state files.
Release metadata VERSION, CHANGELOG.md	The release version changes to 0.37.1, and the changelog documents the newline fix and regression test.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 14.29% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: both leverage sensors now write state JSON with a trailing newline.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/bro-1973-leverage-state-trailing-newline

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@tests/leverage-state-trailing-newline.test.sh`:
- Around line 89-90: Extend the repeated-run scenario in the trailing-newline
test to invoke the ship sensor a second time, then use the exact-one-newline
assertion for leverage-ship-state.json. Keep the existing leverage-state.json
check and reuse the test’s established assert_newline helper.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 08129b21-e26e-4252-b699-459de5a7061e

📥 Commits

Reviewing files that changed from the base of the PR and between a2fb3a1 and e5c180f.

📒 Files selected for processing (5)

• CHANGELOG.md
• VERSION
• scripts/leverage-sensor.py
• scripts/leverage-ship-sensor.py
• tests/leverage-state-trailing-newline.test.sh

[broomva]

Accepted the ship-sensor asymmetry finding — real gap, fixed in 26973b4.

Factored the byte count into assert_single_trailing_newline() and applied it to both sensors. The ship writer swaps a fresh tempfile in via os.replace rather than reopening the target, so it is structurally immune today; the assertion exists so a future refactor away from os.replace cannot regress it silently.

Mutation re-verified: reverting leverage-ship-sensor.py's f.write("\n") now fails 3 assertions (was 1). Suite is 10 passed / 0 failed.