Apply stability-review fixups from PRs 134-139 (PRISM core + infra/vardiff)

[kiwidream]

Summary

Lands the actionable fixups surfaced by the PRs-134-139 stability review (six
independent read-only reviews run on Fable 5 against the merged 2.x.x tree).
The changes split into two disjoint groups — PRISM core Python and infra/vardiff —
implemented in parallel and integrated here. No behavior is changed beyond what
each finding specifies; the production fixes are tight guards and the rest is
honest-disclosure documentation plus a racy-healthcheck repair.

PRISM core (F1-F6)

• F1 — Injectable clock in _acquire_operation_gate (share_ledger.py).
  The admission-wait slicing path read raw time.monotonic() at three sites;
  now reads self._monotonic() so the deterministic harness can drive the
  slicing loop. Production binds self._monotonic = time.monotonic, so behavior
  is unchanged. New virtual-clock test asserts the deadline fires exactly at the
  injected-clock budget.
• F2 — Startup floor on PRISM_WATCHDOG_TIMEOUT_SECONDS (coordinator_config.py).
  Rejects < 1.0 with a clear SystemExit so the x 0.5 landing-budget ceiling
  stays meaningfully below the tolerance. Default unchanged (120s). Review of Cap the escalated landing budget below the watchdog tolerance #135,
  LOW CONFIRMED.
• F3 — Relax a flaky wall-clock assertion (test_prism_share_ledger.py).
  Drops the tight 0.3s per-gap upper bound on the sliced-admission test (a loaded
  CI host can stall a 0.05s slice wakeup past it); keeps the determinism intent
  (>= 2 stamps, elapsed >= 0.4s, < 3.0s) with a maintainer comment. Review of Cap the escalated landing budget below the watchdog tolerance #135,
  LOW PLAUSIBLE.
• F4 — Env-overridable harness baton timeout (prism_concurrency_harness.py).
  BATON_TIMEOUT_SECONDS is now overridable via PRISM_HARNESS_BATON_TIMEOUT_SECONDS
  (default unchanged at 20.0) for heavily oversubscribed CI hosts; remains a
  false-red failure detector that never influences ordering. Review of Add a deterministic concurrency harness for PRISM, proven against the writer-lease lifecycle #139, LOW PLAUSIBLE.
• F5 — Cross-knob validation: idle-in-transaction vs lease acquire budget
  (coordinator_config.py). Warns on stderr at startup when
  postgres_idle_in_transaction_timeout_seconds > lease_acquire_attempts x lease_acquire_lock_timeout_seconds — the condition under which an orphaned
  idle-in-transaction backend holding the lease row lock cannot be reaped
  mid-budget, so startup exhausts every acquire attempt at the same locked row
  instead of self-healing. Warning only (not a crash); names both knobs, their
  values, and the consequence. Review of Bound PRISM writer-lease acquisition and guard coordinator Postgres sessions #137, MEDIUM.
• F6 — Re-verify restore authority after the publication locks
  (block_finalization.py). The superseded-envelope restore's require_fresh_lease
  proof now runs after the payout-balance lock and publication order guard are
  acquired, so a writer deposed during the (unbounded) lock wait no longer
  restores on authority it proved before the wait. Same exception classes, same
  stderr message (deferred until after the locks are released), same degrade
  behavior. New test models a deposal inside the publication guard and fails
  against the old check-then-act shape. Review of Preserve the audit envelope when two found blocks land in one confirm-publish window #136, LOW CONFIRMED.

Infra / vardiff (G1-G4)

• G1 — Replace the racy socket-only Postgres healthcheck (compose.yaml).
  The prism-postgres healthcheck used socket-only pg_isready, which is racy:
  the image's initdb temporary server accepts unix-socket connections and then
  shuts down, so a dependent can be released against the throwaway server (the
  race Gate PRISM Postgres test containers on the real server #134 fixed in the test scripts). Now gates on the real TCP listener
  (pg_isready -h 127.0.0.1 -p 5432) then confirms with psql ... SELECT 1,
  using $$ escaping so the container shell resolves the POSTGRES_* vars.
  Review of Gate PRISM Postgres test containers on the real server #134, out-of-diff.
• G2 — Wire the Bound PRISM writer-lease acquisition and guard coordinator Postgres sessions #137 lease/session-guard env knobs into the ctv scripts
  (run_ctv_broadcaster_daemon.py, backfill_ctv_fanouts.py). Both operator-run
  processes construct PsqlShareLedger directly and got the class defaults for
  all six PRISM_LEDGER_LEASE_ACQUIRE_* / PRISM_POSTGRES_* knobs, so operator
  tuning never reached them. Now mirrors the coordinator: reads the same six env
  vars with the same helpers and defaults. Backfill exposes them as CLI flags with
  env defaults; construction extracted into ledger_from_args for testability.
  Two passthrough tests pin that operator tuning reaches the constructed ledger.
  Review of Bound PRISM writer-lease acquisition and guard coordinator Postgres sessions #137, LOW CONFIRMED.
• G3 — Document that vardiff retention is process-local (.env.example,
  vardiff_service.py, background_services.py). The SessionDifficultyStore is
  in-memory: a coordinator restart — including the watchdog's terminal
  exit_process(1) — empties it, so the post-restart reconnect wave is not
  smoothed by retention. Honest-disclosure comments and .env.example notes only;
  no behavior or default change. Review of Persist per-session vardiff difficulty across miner reconnects #138, MEDIUM CONFIRMED.
• G4 — Document the stuck-high-resume stall risk (.env.example). With the
  idle sweep off (the deployed default), a rig that converged high and reconnects
  within TTL on weaker hardware can resume too high, emit no shares, and give the
  retargeter no signal to come down — stuck for that connection's life (bounded by
  the 900s TTL; harms only that miner). Default unchanged (1024). Review of Persist per-session vardiff difficulty across miner reconnects #138,
  PLAUSIBLE.

Verification

• python -m compileall -q docker lab tests examples scripts — clean.
• python -m unittest tests.test_mainnet_compose_contract — 23 OK.
• python -m unittest tests.test_prism_coordinator_config_loading tests.test_prism_block_candidates tests.test_prism_share_ledger tests.test_ctv_broadcaster_daemon tests.test_prism_vardiff_resume — 453 OK.
• Full suite python -m unittest discover -s tests -p 'test_*.py' — 2106 tests,
  no regressions (5 pre-existing macOS os.splice failures in test_prism_job_builder
  and 9 git-fixture tests that need GIT_CONFIG_GLOBAL=/dev/null for local GPG
  signing config; both pass on Linux CI and are unrelated to these changes).
• shellcheck -x (via docker) on all tracked *.sh — clean (no .sh files
  changed in this PR).
• docker compose config — valid for all four CI profiles: permissionless,
  real-miner-smoke, auxpow, prism.

Review context

Per-PR raw reports and the consolidated write-up live in
.context/pr-stability-reviews/CONSOLIDATED.md. The findings acted on here are
the MEDIUM and LOW items the review flagged as worth fixing; the one HIGH (merge
hygiene for #137) was already resolved on the branch tip before it landed.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.