test(node): pin the per-object marker's third-repo residual

record_pin_source's doc already names this residual and accepts it: the
pin_sources_incomplete marker is one boolean per object rather than per
(object, repo), so a genuine record from a third repo clears a marker that a
different repo's failed record set. Its two neighbouring cases are tested,
the same repo re-recording and a no-op insert that must not clear, and this
one sat between them described in prose and guarded by nothing.

The test drives the real path rather than writing rows. Repo A first-pins the
object. Repo B genuinely holds it and pushes, its skip-branch record fails on
the definite-error arm, and the code marks the set incomplete. An anonymous
read is then SERVED from B, which is the assertion that matters: it proves the
unrecorded holder is reachable while the marker stands. Repo C pushes, its
record succeeds, and the clear fires inside C's transaction. The identical
read now 404s, with the preload counter proving the fallback scan never ran.

Nothing here changes behavior. It converts an accepted tradeoff from a comment
into a guard, so widening it takes a deliberate edit rather than going
unnoticed. The doc comment says the residual fails closed, and that holds:
the provenance loop and the fallback scan both serve through the same
gate_and_serve, so clearing the marker only ever removes a gated search and
can never serve an object the caller could not already read. The window is
exactly one to fifteen sources, because at cap the count-guarded insert is a
no-op and the marker survives.

If someone implements the per-(oid, repo) marker the doc proposes, this test
is expected to go red. It should be updated to the new behavior, not deleted.

Proven load-bearing: removing the clear from record_pin_source leaves the
second read at 200 and turns the test red on the marker assertion.

.env.example

@@ -24,8 +24,11 @@ DATABASE_URL=postgresql://gitlawb:changeme@localhost:5432/gitlawb
 # ── Database pool & startup resilience ────────────────────────────────────
 # Maximum connections in the PostgreSQL pool. A cap, not a floor —
 # connections open lazily. Size against the DB server's max_connections,
-# remembering admin tooling opens its own pool.
-GITLAWB_DB_MAX_CONNECTIONS=20
+# remembering admin tooling opens its own pool. Each concurrent write pins one
+# connection for its whole duration (the connection-affine advisory lock), so the
+# node REJECTS at boot any value below GITLAWB_MAX_CONCURRENT_GIT_PUSHES + 8
+# headroom — keep this comfortably above that (default 48 for pushes 32).
+GITLAWB_DB_MAX_CONNECTIONS=48
 # Seconds a request waits for a pool connection before failing with 503.
 GITLAWB_DB_ACQUIRE_TIMEOUT_SECS=5
 # Upper bound on each startup connect+migrate attempt, in seconds. Keep it
@@ -109,15 +112,141 @@ GITLAWB_MAX_PACK_BYTES=2147483648
 
 # Max seconds a served git upload-pack / receive-pack (clone / push) may run
 # before it is aborted with a 504. Bounds a hung git that would otherwise pin a
-# worker and, on push, the repo write lock. Does NOT cover the info/refs
-# advertisement or the withheld-blob path, which remain unbounded. Default 600.
+# worker and, on push, the repo write lock. Also bounds both info/refs
+# advertisements, the withheld-blob pack build, and the push-side candidate
+# discovery (rev-list / cat-file), all reaped via process-group teardown (#174).
+# On the path-scoped upload-pack path the withheld-blob classification walk and
+# the pack serve share ONE deadline, so this value bounds their COMBINED duration
+# rather than giving each stage a full budget: a walk that consumes it leaves the
+# serve nothing and the clone gets a 504. Serving large path-scoped repos may
+# need a higher value here than when each stage was budgeted separately.
+# Must be 1..=3153600000 (100 years): the node derives deadlines from this value,
+# and a larger one cannot be represented. Default 600.
 GITLAWB_GIT_SERVICE_TIMEOUT_SECS=600
 
+# Max seconds the storage-ACQUISITION phase of a served git op may run before the
+# request is shed with a 503, separate from the git-run timeout above. A
+# concurrency permit is taken before this phase and GITLAWB_GIT_SERVICE_TIMEOUT_SECS
+# only starts once git spawns, so without this a stalled backend (a hung Tigris
+# HEAD/GET, or a hung pg advisory-lock iteration on push) pins the permit and drains
+# the pool until every later request 503s. On expiry the permit is released
+# (fail-closed). Kept separate because acquisition and git execution are distinct
+# cost centers. Must be positive; set very large to effectively disable. Default 30.
+GITLAWB_GIT_ACQUIRE_TIMEOUT_SECS=30
+
+# Max concurrent git READ ops (upload-pack + the upload-pack info/refs
+# advertisement) served at once, a global pool separate from the push pool below.
+# The anon receive-pack info/refs advertisement has its OWN pool (see below), not
+# this one. Over-cap sheds a clean 503 + Retry-After. Anonymous reads draw from
+# here, so pair it with GITLAWB_MAX_CONCURRENT_READS_PER_CALLER (below) so one
+# caller cannot monopolize the pool. Default 128.
+GITLAWB_MAX_CONCURRENT_GIT_OPS=128
+
+# Max concurrent git-receive-pack (push) POST operations, in a pool separate from
+# the read pool (GITLAWB_MAX_CONCURRENT_GIT_OPS) so anonymous reads cannot shed an
+# authenticated push at admission. The anon receive-pack info/refs advertisement
+# runs in a SEPARATE pool of the same size (disjoint from this one), so an
+# advertisement flood cannot shed a push either. Over-cap sheds a 503 +
+# Retry-After. Default 32.
+GITLAWB_MAX_CONCURRENT_GIT_PUSHES=32
+
+# Max pushes PARKED at once waiting for the per-repo write lease of the SAME repo.
+# A parked push holds its already-buffered pack body in memory, so this bounds that
+# memory for a hot repo. Past the cap the newest push sheds a clean 503 +
+# Retry-After ("repo is busy with another push") instead of joining the queue; a
+# push to a DIFFERENT repo is never affected. The lease holder is not counted.
+# Raising GITLAWB_MAX_CONCURRENT_GIT_PUSHES does not raise this; set it explicitly.
+# Default 8.
+GITLAWB_REPO_LEASE_MAX_WAITERS=8
+
+# Max concurrent post-push pin loops (IPFS + Pinata pin_new_objects) across all
+# repos. The per-repo encrypt-task set caps the pin-task COUNT; this caps how many
+# of those loops RUN CONCURRENTLY, and so how much MB-scale object-id list memory is
+# held WHILE BEING PINNED. It does not bound retained memory in general: on the local
+# IPFS path the caller builds its list before this pool is entered, so a loop parked
+# waiting for a permit still holds its full list, and how many park is capped only
+# per repo. Do not size memory from this knob alone. A loop DEFERS (waits) when the
+# pool is full, never drops a pin. Default 8.
+GITLAWB_MAX_CONCURRENT_PIN_TASKS=8
+
+# Max concurrent read ops (upload-pack + the upload-pack info/refs advertisement)
+# a single caller may hold, so one caller cannot monopolize the read pool. Keyed
+# on the resolved SOURCE IP, never the DID: a signature does not move a caller off
+# this cap. The source-IP key is only as granular as GITLAWB_TRUSTED_PROXY below:
+# left unset, a node behind an edge/NAT keys all callers on the edge IP and this
+# collapses to one global cap. Set GITLAWB_TRUSTED_PROXY for per-client keying; a
+# high-fanout caller (CI behind one NAT) then needs the operator to raise this.
+# Default 16.
+GITLAWB_MAX_CONCURRENT_READS_PER_CALLER=16
+
+# Two further per-source concurrency caps exist on the PUSH side but have NO
+# environment variable of their own: both are DERIVED as
+# GITLAWB_MAX_CONCURRENT_GIT_PUSHES / 8, with a floor of 1. They are not settable
+# independently, so raising the push pool raises both proportionally, and the
+# default push pool of 32 gives each a cap of 4.
+#   * The anon receive-pack info/refs advertisement cap: one source IP may hold at
+#     most this many slots in the dedicated advert pool, so saturating that pool
+#     takes ~8 distinct source IPs.
+#   * The authenticated receive-pack POST cap: one source IP may hold at most this
+#     many WRITE-pool slots. This one is load-bearing for push availability, since
+#     it is acquired before the global write permit: without it, one host minting
+#     disposable did:key identities could open enough slow pushes to monopolize the
+#     write pool and 503 every other source (owner enforcement defaults off, and
+#     the push rate limiter caps arrival rate, not in-flight concurrency).
+# Keyed on the resolved source IP, never the DID, so a DID farm does not defeat
+# them; keying granularity follows GITLAWB_TRUSTED_PROXY like the read cap above.
+
 # ── Push rate limiting (git-receive-pack flood brake) ─────────────────────
 # Max receive-pack requests (info/refs advertisement + push POST) per client
 # IP per hour. 0 disables. Default 600.
 GITLAWB_PUSH_RATE_LIMIT=600
 
+# ── /ipfs/{cid} visibility-walk admission (#174) ──────────────────────────
+# GET /ipfs/{cid} runs a per-repo full-history git walk in a blocking thread to
+# decide whether the caller may read a path-scoped blob. It is publicly reachable,
+# so it is bounded to keep a permissionless caller from fanning out unbounded
+# concurrent walks and exhausting blocking-pool threads + PIDs.
+# Max concurrent /ipfs walks across all callers (a pool of its own, disjoint from
+# the served-git pools). Over-cap sheds a 503. Default 32.
+GITLAWB_MAX_CONCURRENT_IPFS_WALKS=32
+# Max concurrent /ipfs walks a single SOURCE IP may hold (keyed like the git
+# per-caller caps via GITLAWB_TRUSTED_PROXY; reject-before-insert bounded map).
+# Default 4.
+GITLAWB_IPFS_WALK_PER_SOURCE=4
+# Max legacy (NULL-provenance) repos probed per single /ipfs request, bounding the
+# scan-fallback fan-out (git cat-file per candidate repo) for an anonymous caller. A
+# truncated scan sheds a retryable 503, never a false 404. Default 256.
+GITLAWB_IPFS_MAX_LEGACY_PROBES=256
+# Max EXPENSIVE path-scope visibility walks per single /ipfs request (only a
+# blob in a path-scoped repo costs a full-history walk). Over-cap repos are
+# skipped without a verdict and the scan continues; if the object is then found
+# nowhere the request sheds a retryable 503 instead of a false 404. The effective
+# cap is the tighter of this value and the node's internal per-request ceiling of
+# 17, so values above 17 have no effect; lower values do tighten it. Default 64.
+GITLAWB_IPFS_MAX_REPOS_WALKED=64
+# Ceiling on repos one /ipfs request may VISIT past the visibility gate. Each
+# visit costs a repo acquire — on a Tigris cache miss a full archive download,
+# so this is also the worst-case object-store fetch count per request — plus a
+# cat-file probe. On exhaustion the scan stops and sheds a retryable 503.
+# Default 1024.
+GITLAWB_IPFS_MAX_REPO_VISITS=1024
+# Absolute wall-clock budget for one admitted /ipfs request's acquire+walk
+# lifetime (all stages of the whole scan). Per-stage clamps bound the acquire
+# and walk stages to the remaining budget, and no stage starts once it is
+# exhausted (the scan then sheds a retryable 503). The object-type probe and
+# content-read cat-file subprocesses are budget-checked before starting AND each
+# run under their own deadline (the lesser of GITLAWB_GIT_SERVICE_TIMEOUT_SECS and
+# the remaining budget), reaped via process-group teardown, so a hung cat-file
+# cannot hold the request's walk slot past it. One hang path is still unbounded:
+# the probe's object-store readability check is a plain filesystem sweep with
+# nothing to reap, so a wedged filesystem can hold the slot past the deadline.
+# Must be 1..=3153600000 (100 years): the node derives an Instant deadline from
+# this value, and a larger one cannot be represented. Default 600.
+GITLAWB_IPFS_REQUEST_BUDGET_SECS=600
+# Max /ipfs/{cid} requests per client IP per hour (route flood brake, distinct
+# from the concurrency caps above). 0 disables. Default 600.
+GITLAWB_IPFS_RATE_LIMIT=600
+
 # ── Creation rate limiting (repo/agent/issue/PR flood brake) ──────────────
 # Max creation requests (POST /api/v1/repos, /api/register, fork, issues,
 # pulls) per client IP per hour, in addition to the per-DID limit. The per-DID

.github/workflows/pr-checks.yml

@@ -55,6 +55,19 @@ jobs:
       - name: cargo clippy
         run: cargo clippy --locked --workspace --all-targets -- -D warnings
 
+  release-tag-validation:
+    name: release tag validation
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
+
+      - name: Test release tag resolver
+        run: scripts/test-resolve-release-tag.sh
+
   test:
     name: test (${{ matrix.toolchain }})
     runs-on: ubuntu-latest
@@ -283,3 +296,35 @@ jobs:
 
       - name: Check gitlawb-core dependency allowlist
         run: bash scripts/check-gitlawb-core-deps.sh
+
+  # release-please only rewrites a crate's version when the line carries the
+  # `# x-release-please-version` annotation AND the manifest is listed under
+  # extra-files in release-please-config.json. Miss either half and the crate
+  # is skipped silently at release time, freezing at its creation version:
+  # icaptcha-client was added as a workspace member after the config was last
+  # written and sat at 0.4.0 through four releases before anyone noticed.
+  # Exhaustive-by-construction, like the allowlist gate above: the required set
+  # is derived from `cargo metadata`, so a newly added crate reds CI whether or
+  # not its author knew this gate existed.
+  release-versioning:
+    name: release versioning coverage
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
+
+      - name: Set up Rust toolchain
+        uses: dtolnay/rust-toolchain@b3b07ba8b418998c39fb20f53e8b695cdcc8de1b # stable
+        with:
+          toolchain: stable
+
+      - name: Cache cargo
+        uses: Swatinem/rust-cache@98c8021b550208e191a6a3145459bfc9fb29c4c0 # v2.8.0
+        with:
+          key: release-versioning
+
+      - name: Check every workspace crate is release-managed
+        run: bash scripts/check-release-versioning.sh

.github/workflows/pr-triage.yml

@@ -70,9 +70,15 @@ jobs:
             const changedRust = names.some(n => n.startsWith("crates/") && n.endsWith(".rs"));
             // A test can live in a tests/ dir, a *_test.rs file, or (the common Rust
             // pattern) an inline #[test] / #[cfg(test)] block added inside the source file.
+            // Async tests use a namespaced attribute (#[tokio::test], #[async_std::test],
+            // possibly with args like #[tokio::test(flavor = ...)]) rather than the bare
+            // #[test]. Match only on added lines, with the attribute at the start of the
+            // line after horizontal whitespace, covering bare, cfg(test), namespaced,
+            // optional leading ::, and raw-identifier (r#test) forms. No head-file fetch
+            // or lexer: needs-tests is advisory, not a merge gate.
             const addsInlineTest = files.some(f =>
               f.filename.endsWith(".rs") && f.patch &&
-              /^\+.*#\[(test\]|cfg\(test\))/m.test(f.patch));
+              /^\+[ \t]*#\[[ \t]*(?:cfg[ \t]*\([ \t]*test[ \t]*\)|(?:::[ \t]*)?(?:[\w-]+[ \t]*::[ \t]*)*(?:r#)?test\b)/m.test(f.patch));
             const touchedTests =
               names.some(n => n.includes("/tests/") || n.endsWith("_test.rs")) || addsInlineTest;
             if (changedRust && !touchedTests) want.add("needs-tests");

.github/workflows/release.yml

@@ -216,6 +216,11 @@ jobs:
       contents: read
       packages: write
     steps:
+      - name: Check out workflow scripts
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
+
       - name: Resolve release tag
         id: rel
         env:
@@ -223,13 +228,7 @@ jobs:
           RELEASE_TAG: ${{ needs.release-please.outputs.tag_name }}
         run: |
           set -euo pipefail
-          TAG="${DISPATCH_TAG:-$RELEASE_TAG}"
-          case "$TAG" in
-            v[0-9]*) ;;
-            *) echo "::error::'$TAG' does not look like a release tag (vX.Y.Z)"; exit 1 ;;
-          esac
-          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
-          echo "version=${TAG#v}" >> "$GITHUB_OUTPUT"
+          scripts/resolve-release-tag.sh "${DISPATCH_TAG:-$RELEASE_TAG}"
           # ghcr requires a lowercase repository path, and unlike metadata-action,
           # buildx's `--output name=` does no lowercasing — a mixed-case owner
           # makes the digest push fail with "invalid reference format".
@@ -311,8 +310,14 @@ jobs:
     if: ${{ !cancelled() && needs.docker.result == 'success' }}
     runs-on: ubuntu-latest
     permissions:
+      contents: read
       packages: write
     steps:
+      - name: Check out workflow scripts
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
+
       - name: Resolve release tag
         id: rel
         env:
@@ -320,13 +325,7 @@ jobs:
           RELEASE_TAG: ${{ needs.release-please.outputs.tag_name }}
         run: |
           set -euo pipefail
-          TAG="${DISPATCH_TAG:-$RELEASE_TAG}"
-          case "$TAG" in
-            v[0-9]*) ;;
-            *) echo "::error::'$TAG' does not look like a release tag (vX.Y.Z)"; exit 1 ;;
-          esac
-          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
-          echo "version=${TAG#v}" >> "$GITHUB_OUTPUT"
+          scripts/resolve-release-tag.sh "${DISPATCH_TAG:-$RELEASE_TAG}"
 
       - name: Download digests
         uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
@@ -542,6 +541,11 @@ jobs:
       contents: read
       id-token: write # npm trusted publishing (OIDC) + provenance
     steps:
+      - name: Check out workflow scripts
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
+
       - name: Resolve release tag
         id: rel
         env:
@@ -549,13 +553,7 @@ jobs:
           RELEASE_TAG: ${{ needs.release-please.outputs.tag_name }}
         run: |
           set -euo pipefail
-          TAG="${DISPATCH_TAG:-$RELEASE_TAG}"
-          case "$TAG" in
-            v[0-9]*) ;;
-            *) echo "::error::'$TAG' does not look like a release tag (vX.Y.Z)"; exit 1 ;;
-          esac
-          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
-          echo "version=${TAG#v}" >> "$GITHUB_OUTPUT"
+          scripts/resolve-release-tag.sh "${DISPATCH_TAG:-$RELEASE_TAG}"
 
       - name: Checkout release tag
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

AGENTS.md

@@ -0,0 +1,44 @@
+# Contributor guide for coding agents
+
+This file carries the rules a patch author cannot recover from the code alone, for humans and coding agents alike. For build, test, and PR basics, read `CONTRIBUTING.md` first.
+
+## Authorization invariants (the rules PRs most often break)
+
+Every repo-scoped endpoint must bind the caller to an authorization decision before serving or mutating anything. The `known_ungated` allowlist in `authz_guard::every_repo_scoped_handler_is_gated` is empty on main: `list_webhooks`, `list_replicas`, and `list_protected_branches` are gated (`list_webhooks` with read-visibility then owner; the other two with `authorize_repo_read`). Do not re-open those surfaces as exceptions.
+
+- Owner-only mutations (visibility, webhooks, protected branches, merges) are gated against the repo owner. Three gate forms are in use and all are recognized: webhooks and merges call `require_repo_owner` (`crates/gitlawb-node/src/api/mod.rs`), visibility uses its module-local `require_owner`, and protected branches compare inline with `did_matches`. Use the form the surrounding module already uses.
+- Not every write is owner-only, and that is by design: `star_repo`/`unstar_repo` bind to the signer (they still require repo read access), `register_replica`/`unregister_replica` bind to the replica's own DID, the bounty actions (claim, submit, approve, cancel, dispute) have their own multi-party rules, and closing a PR or issue is owner-or-author. Do not add owner gates to these.
+- Content-serving reads (blobs, trees, raw files) gate through `authorize_repo_read` with the specific path being served, so a withheld subtree is denied even on an otherwise-public repo; repo-level reads (listings) pass `"/"` by the helper's own contract. The source scans below cannot check this argument's value, so review will.
+- A route that reaches repo data through a global id, with no repo in its path, or through an extractor shape the scans do not recognize still needs the same gate; the scans cannot see those.
+- Read-surface denials must not reveal existence: a caller who may not read a repo (or a withheld subtree) gets the same 404 as a missing repo, never a 403. (Owner-gated mutations currently return 403 after the repo lookup; do not widen that shape to read paths.)
+- Two tests in module `authz_guard` (`crates/gitlawb-node/src/api/mod.rs`) scan handler sources and fail on a repo-scoped handler without a recognized gate: `every_in_scope_mutation_has_its_gate` and `every_repo_scoped_handler_is_gated`. If they fail on your handler, add the gate. The second test's `known_ungated` allowlist is empty; never add an entry to it without an open issue and review.
+
+## Adding or changing routes
+
+- A new gated handler needs tests proving its route-specific gate fires: exercise an unauthorized authenticated caller and an anonymous caller where applicable, assert the exact denial status each way, and assert the body leaks nothing. The non-owner tests in `crates/gitlawb-node/src/test_support.rs` show the shape for owner-gated routes.
+- A new mutation handler also gets a row in `every_in_scope_mutation_has_its_gate` naming its gate type; the per-handler row is the point of that test.
+- A table-driven deny suite covering every deny-bearing route is in review (#194, #195). If it is present in your checkout, add a probe row there for any new deny-bearing route.
+
+## Verifying signatures and certificates
+
+- Derive the verifying key from something outside the artifact you are checking: the node's own DID, a pinned or configured value, a peers lookup. A key read from a field of the object being verified (`Did::from_str(&cert.node_did)`) only proves the artifact is self-consistent, and identities here are permissionless, so anyone can mint a keypair, name it in the artifact, self-sign, and be told it is valid. A mismatch against that anchor has to fail the result, not log a warning.
+- A handler whose correct answer is "valid" needs a positive case driven by a trusted, independently anchored artifact, and a rejection case for a well-formed, fully populated forged artifact. Invalid-only suites miss an implementation that rejects everything; a forged artifact that still returns valid is the regression that matters.
+- The fields a signature covers are a versioned format. Adding one invalidates every artifact already signed, so give the payload a version, keep a path that verifies the older form, and add a test that verifies an artifact signed before your change.
+
+## Removing a serving path
+
+When a fix removes a path that used to serve content, the same PR must add a test asserting the removed path now denies. The deletion is what turns that test green; without it the path can quietly come back.
+
+## Database migrations
+
+Schema changes are code-defined in `MIGRATIONS` (`crates/gitlawb-node/src/db/mod.rs`). Always append a new versioned entry; never edit an entry that has merged (operators deploy from main). Test runs build the schema from scratch, so editing an applied version stays green in CI while breaking every existing deployment.
+
+## Client behavior (`gl`, `git-remote-gitlawb`)
+
+When a node denies a request, surface the denial to the user. Never render a denial as an empty list or a silent success; that turns an authorization boundary into invisible data loss.
+
+## Toolchain and CI reality
+
+- MSRV is Rust 1.91 (`rust-version` in the workspace `Cargo.toml`). The MSRV CI job runs `cargo check --workspace --all-targets` on exactly 1.91, so check that an API you rely on is stable there; the full test suite runs on stable.
+- The PR workflow runs these jobs on every PR: `cargo fmt --check`, `cargo clippy --workspace --all-targets -- -D warnings`, `cargo test --workspace` (against Postgres), a release build, `cargo audit`, the MSRV check, and a Docker build. The `main` branch ruleset currently requires one approving review but does not require these checks to pass before merge; a failing job should block review approval in practice, but nothing enforces that mechanically today.
+- Conventional commit titles (`feat:`, `fix:`, `docs:`, ...) are required by convention and drive releases, but no CI job checks them; a bad title fails review, not the pipeline.

CONTRIBUTING.md

@@ -54,6 +54,7 @@ Smart contracts live in a separate repo: [github.com/Gitlawb/contracts](https://
 3. **No breaking changes without discussion.** Open an issue first for protocol-level changes.
 4. **Conventional commits.** Use `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`. Releases are automated by [release-please](https://github.com/googleapis/release-please) — your commit prefixes drive the next version bump.
 5. **Format and lint.** Run `cargo fmt --all` and `cargo clippy --workspace --all-targets -- -D warnings` before submitting. CI will reject anything that fails these.
+6. **Security-surface rules.** [`AGENTS.md`](AGENTS.md) carries the authorization invariants PRs most often break; it is written for coding agents and humans alike, so read it before touching endpoints, visibility, or migrations.
 
 ## What gets merged, what gets closed
 

Cargo.lock

@@ -3378,10 +3378,13 @@ version = "0.7.1"
 dependencies = [
  "anyhow",
  "gitlawb-core",
+ "libc",
  "mockito",
  "reqwest",
+ "tempfile",
  "tracing",
  "tracing-subscriber",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]

README.md

@@ -4,7 +4,7 @@
 
 Gitlawb Node is the open-source node software behind the Gitlawb network. It lets anyone run a self-hosted node, publish repositories under a DID, sign writes with Ed25519 HTTP signatures, replicate git activity across peers, and move toward a resilient app-delivery network where code and build assets can be served closer to users.
 
-Gitlawb is not trying to be only “another git host.” The long-term direction is:
+Gitlawb is not trying to be only "another git host." The long-term direction is:
 
 ```txt
 Decentralized GitHub
@@ -34,12 +34,12 @@ This is a Rust workspace with four crates:
 
 Most git hosting today depends on a small number of centralized platforms. Gitlawb Nodes are designed for a different model:
 
-- **Own your identity** — every user, agent, and node is an Ed25519 keypair represented as `did:key:z6Mk...`.
-- **Signed writes by default** — write requests use RFC 9421 HTTP Signatures instead of passwords.
-- **Git-native transport** — repositories are still real git repositories served over smart HTTP.
-- **Agent-native workflows** — the `gl` CLI and MCP server expose repo, issue, task, PR, and UCAN flows to AI agents.
-- **Peer-aware delivery** — nodes can announce, discover, gossip, and sync with each other.
-- **App CDN direction** — the network can evolve from decentralized code storage into code + asset + app delivery.
+- **Own your identity**: every user, agent, and node is an Ed25519 keypair represented as `did:key:z6Mk...`.
+- **Signed writes by default**: write requests use RFC 9421 HTTP Signatures instead of passwords.
+- **Git-native transport**: repositories are still real git repositories served over smart HTTP.
+- **Agent-native workflows**: the `gl` CLI and MCP server expose repo, issue, task, PR, and UCAN flows to AI agents.
+- **Peer-aware delivery**: nodes can announce, discover, gossip, and sync with each other.
+- **App CDN direction**: the network can evolve from decentralized code storage into code + asset + app delivery.
 
 ---
 
@@ -189,14 +189,14 @@ For public-network use, make sure `GITLAWB_NODE` points to the node you want. Th
 
 Public nodes (e.g. `node.gitlawb.com`) require two things on writes:
 
-1. **RFC 9421 HTTP Signatures** — every write is signed by your identity key. `gl`
+1. **RFC 9421 HTTP Signatures**: every write is signed by your identity key. `gl`
    and the `git-remote-gitlawb` helper do this automatically. An old/unsigned CLI
    fails with `401 not_an_agent`; `gl` will tell you to upgrade and register.
 2. **An iCaptcha proof** on the spam-gated writes (**repo create, fork, register**).
    `gl` solves this for you: on the node's `403 icaptcha_proof_required` it reads the
    `x-icaptcha-url` / `x-icaptcha-level` hints, requests a challenge, solves it
    locally (arithmetic / algebra / sequence), and **retries the same signed request**
-   with the `x-icaptcha-proof` header — no manual steps, no env vars.
+   with the `x-icaptcha-proof` header. No manual steps, no env vars.
 
 ```bash
 gl identity new                                   # create did:key identity
@@ -215,14 +215,14 @@ Notes:
 - **Proofs are short-lived (~5 min TTL) and single-use.** If one expires between
   solving and use, the client transparently solves a fresh one and retries.
 - **What needs what:** create / fork / register are signed **and** iCaptcha-gated;
-  `git push` is **signed-only** (owner signature is the gate — no per-push challenge);
+  `git push` is **signed-only** (owner signature is the gate, no per-push challenge);
   reads (clone / fetch / `repo info`) need no proof. A non-existent repo returns a
   clear `404`, never a placeholder.
 - **API-key iCaptcha deployments:** set `GITLAWB_ICAPTCHA_URL` to your iCaptcha
   origin and `GITLAWB_ICAPTCHA_API_KEY` to its key. The client only talks to an
   `https` origin whose host is allowlisted (that URL or the public default), and
-  sends the bearer token **only** to your configured origin — never to a URL a
-  node advertises — so a hostile node can't capture the key or redirect the solve.
+  sends the bearer token **only** to your configured origin, never to a URL a
+  node advertises, so a hostile node can't capture the key or redirect the solve.
 
 ---
 
@@ -309,7 +309,7 @@ POST /api/v1/peers/announce
 POST /api/v1/sync/notify
 ```
 
-When `GITLAWB_REQUIRE_SIGNED_PEER_WRITES=false`, unsigned legacy peers are accepted on those two routes, but signed requests are verified when signature headers are present. Once all live peers upgrade, operators can set:
+When `GITLAWB_REQUIRE_SIGNED_PEER_WRITES=false`, unsigned legacy peers are accepted on those two routes, but signed requests are verified when signature headers are present. Staged rollout relaxes who may announce, not who owns a peer row. An unsigned announce may register a previously unseen peer, and it may refresh an existing row whose `http_url` is unchanged, but changing an existing peer's `http_url` requires an RFC 9421 signature from that peer's own DID and is refused with 403 otherwise. An unsigned announce can only register a `did:key`, since that is the only method whose verifying key can be resolved and therefore the only kind of row anyone could ever correct through the signed path; any other DID is refused with 400. Once all live peers upgrade, operators can set:
 
 ```bash
 GITLAWB_REQUIRE_SIGNED_PEER_WRITES=true
@@ -343,13 +343,28 @@ Important node settings:
 | `GITLAWB_REQUIRE_SIGNED_PEER_WRITES` | Require signed peer announce/sync writes. |
 | `GITLAWB_AUTO_SYNC` | Enable automatic sync from known peers. |
 | `GITLAWB_MAX_PACK_BYTES` | Max git pack body size for smart-HTTP routes. |
-| `GITLAWB_GIT_SERVICE_TIMEOUT_SECS` | Max seconds a served git upload-pack/receive-pack may run before it is aborted (504). Default 600. Does not bound `info/refs` or the withheld-blob path. |
+| `GITLAWB_GIT_SERVICE_TIMEOUT_SECS` | Max seconds a served git upload-pack, receive-pack, or `info/refs` advertisement may run before it is aborted (504). Default 600. Also bounds the withheld-blob classification walk (on both the upload-pack serve and receive-pack replication paths) and the push-side pin-candidate discovery (`rev-list` / `cat-file`), each reaped via process-group teardown at the deadline. On the path-scoped upload-pack path the classification walk and the pack serve share ONE deadline, so this value bounds their combined duration rather than granting each stage a full budget: a walk that consumes it leaves the serve nothing and the clone gets a 504. Serving large path-scoped repos may therefore need a higher value than they did when each stage was budgeted separately. Accepted range is 1 to 3153600000 (100 years), since the node derives deadlines from this value and a larger one cannot be represented. |
+| `GITLAWB_GIT_ACQUIRE_TIMEOUT_SECS` | Max seconds the storage-acquisition phase (Tigris HEAD/GET, push advisory-lock) of a served git op may run before the request is shed with a 503, separate from the git-run timeout. The concurrency permit is released on expiry so a stalled backend cannot pin the pool. Default 30. |
+| `GITLAWB_MAX_CONCURRENT_GIT_OPS` | Max concurrent served git READ ops (upload-pack and its `info/refs` advertisement) across all callers; over-cap sheds a 503 + Retry-After. Anonymous reads draw from this pool, so pair it with `GITLAWB_MAX_CONCURRENT_READS_PER_CALLER`. Pushes and the receive-pack advertisement have their own pools, so a read flood cannot shed an authenticated push. Default 128. |
+| `GITLAWB_MAX_CONCURRENT_GIT_PUSHES` | Max concurrent `git-receive-pack` POST operations, in a pool separate from the read pool. The anon receive-pack `info/refs` advertisement runs in a third pool of the same size, disjoint from both, so an advertisement flood cannot shed a push either. Two per-source push caps are derived from this value (`/8`, floor 1) and have no env var of their own. Over-cap sheds a 503 + Retry-After. Default 32. |
+| `GITLAWB_MAX_CONCURRENT_READS_PER_CALLER` | Max concurrent read ops a single caller may hold, so one caller cannot monopolize the read pool. Keyed on the resolved source IP, never the DID, and only as granular as `GITLAWB_TRUSTED_PROXY`: left unset, a node behind an edge or NAT keys every caller on the edge IP and this collapses to one global cap. Default 16. |
+| `GITLAWB_MAX_CONCURRENT_PIN_TASKS` | Max post-push pin loops (IPFS + Pinata) running concurrently across all repos. This caps how many loops RUN at once, not how much object-id list memory the node retains: on the local IPFS path a loop parked waiting for a permit still holds its full list. Do not size memory from this knob alone. A loop over cap waits, never drops a pin. Default 8. |
+| `GITLAWB_REPO_LEASE_MAX_WAITERS` | Max pushes parked at once waiting for the same repo's write lease. Each waiter pins its buffered pack body, so this bounds that memory for a hot repo; past the cap the newest push sheds a 503 + Retry-After instead of queueing. Pushes to other repos are unaffected, and the lease holder is not counted. Default 8. |
+| `GITLAWB_MAX_CONCURRENT_IPFS_WALKS` | Max concurrent `GET /ipfs/{cid}` visibility walks across all callers (own pool, disjoint from the served-git pools); over-cap sheds 503. Default 32. |
+| `GITLAWB_IPFS_WALK_PER_SOURCE` | Max concurrent `/ipfs` walks a single source IP may hold. Default 4. |
+| `GITLAWB_IPFS_MAX_LEGACY_PROBES` | Max legacy (NULL-provenance) repos probed per `/ipfs/{cid}` request, bounding the scan-fallback fan-out. A truncated scan returns a retryable 503, not a false 404. Default 256. |
+| `GITLAWB_IPFS_MAX_REPOS_WALKED` | Max expensive path-scope visibility walks per `/ipfs/{cid}` request; over-cap repos are skipped and the scan continues, shedding a retryable 503 (not a false 404) if the object is then found nowhere. The effective cap is the tighter of this knob and the node's internal per-request history-walk ceiling of 17 (`MAX_PIN_SOURCES + 1`), so a value above 17 has no effect while a value below it does tighten the cap. Default 64. |
+| `GITLAWB_IPFS_MAX_REPO_VISITS` | Ceiling on repos one `/ipfs/{cid}` request may visit (acquire + probe) past the visibility gate. Also the worst-case per-request Tigris fetch count. On exhaustion the scan stops with a retryable 503. Default 1024. |
+| `GITLAWB_IPFS_REQUEST_BUDGET_SECS` | Absolute wall-clock budget for one admitted `/ipfs/{cid}` request's acquire+walk lifetime. Per-stage clamps bound the acquire and walk stages to the remaining budget, and no stage starts once it is exhausted; the scan then stops with a retryable 503. The object-type probe and content-read `cat-file` subprocesses are budget-checked before starting and each also run under their own deadline (the lesser of `GITLAWB_GIT_SERVICE_TIMEOUT_SECS` and the remaining budget), reaped via process-group teardown, so a hung `cat-file` cannot hold the request's walk slot past it. One hang path is still unbounded: the probe's object-store readability check is a plain filesystem sweep with nothing to reap, so a wedged filesystem can hold the slot past the deadline. Default 600. Accepted range is 1 to 3153600000 (100 years), since the node derives a deadline from this value and a larger one cannot be represented. |
+| `GITLAWB_IPFS_RATE_LIMIT` | Max `/ipfs/{cid}` requests per client IP per hour (route flood brake). 0 disables. Default 600. |
 | `GITLAWB_TIGRIS_BUCKET` | Optional S3/Tigris shared repo storage bucket. |
 | `GITLAWB_PINATA_JWT` | Optional Pinata/IPFS warm-storage pinning. |
 | `GITLAWB_IRYS_URL` | Optional Irys/Arweave permanent anchoring. |
 
 Production note: change the default Postgres password before exposing a node publicly.
 
+Legacy-pin window: releases before the CID-resolver work stored the provider CID (Kubo dag-pb / Pinata) as a pinned object's resolver key. The `/ipfs/{cid}` resolver now recomputes the raw-content CID from the object bytes and refuses to serve a key that does not match, so `GET /api/v1/ipfs/pins` can still advertise an unrepaired legacy CID that 404s. Such a row is repaired opportunistically the next time a push carries the object again (its key is rewritten to the raw CID, the old value kept in `legacy_provider_cid`), but git negotiation omits objects the node already has, so most legacy rows never re-enter a push delta. A deferred one-shot startup sweep, not this opportunistic path, is what fully retires the advertise-then-404 window. Rows whose object bytes are gone stay withheld.
+
 ---
 
 ## Optional node staking

crates/git-remote-gitlawb/Cargo.toml

@@ -19,3 +19,20 @@ tracing-subscriber = { workspace = true }
 
 [dev-dependencies]
 mockito = "1"
+tempfile = "3"
+
+[target.'cfg(unix)'.dev-dependencies]
+libc = "0.2"
+
+[target.'cfg(windows)'.dev-dependencies]
+# Job Object bindings for the real_git_fetch harness: the Windows analog of the
+# unix process-group teardown, so the whole `git fetch` tree can be killed
+# together on both the timeout and clean-exit paths (INV-22). Win32_Security is
+# required by CreateJobObjectW, and Win32_System_Threading by
+# JOBOBJECT_EXTENDED_LIMIT_INFORMATION (it embeds IO_COUNTERS).
+windows-sys = { version = "0.61", features = [
+    "Win32_Foundation",
+    "Win32_Security",
+    "Win32_System_JobObjects",
+    "Win32_System_Threading",
+] }

crates/git-remote-gitlawb/src/main.rs

@@ -276,27 +276,32 @@ fn handle_connect<R: Read>(
 
     // ── Phase 2: pack exchange (POST /<service>) ──────────────────────────────
     //
-    // The two services behave differently with their write pipe:
+    // The two services frame Phase 2 differently:
     //
     //  git-upload-pack (clone/fetch):
-    //    Client sends pkt-line want/have negotiation ending with "done\n",
-    //    but does NOT close its write pipe — it waits for the pack response.
-    //    We must detect the terminal "done\n" pkt-line to know when to POST.
+    //    Git speaks the stateful native protocol over `connect`: it sends its
+    //    wants, a flush, then have-batches each terminated by a flush, and blocks
+    //    for the server's ACK/NAK after every flush before it sends more haves or
+    //    the terminal "done\n". The node serves `git upload-pack --stateless-rpc`,
+    //    which keeps no state between POSTs, so we run a per-round loop: POST a
+    //    self-contained request once per flush-terminated batch and stream each
+    //    response back to git, until the "done" round returns the pack. Collapsing
+    //    this into one POST deadlocks a multi-round fetch (#117).
     //
     //  git-receive-pack (push):
-    //    Client sends ref-update commands + complete PACK blob, then closes
-    //    its write pipe.  read_to_end is safe and correct here.
+    //    Git sends ref-update commands + the complete PACK blob, then closes its
+    //    write pipe. read_to_end is safe and correct here, a single POST.
 
-    let request_body = if service == "git-upload-pack" {
-        read_upload_pack_request(stdin).context("reading upload-pack request")?
-    } else {
-        let mut buf = Vec::new();
-        stdin
-            .read_to_end(&mut buf)
-            .context("reading receive-pack request")?;
-        buf
-    };
+    let post_url = format!("{}/{}", repo_base, service);
 
+    if service == "git-upload-pack" {
+        return negotiate_upload_pack(&client, &post_url, service, signing_key, stdin, &mut stdout);
+    }
+
+    let mut request_body = Vec::new();
+    stdin
+        .read_to_end(&mut request_body)
+        .context("reading receive-pack request")?;
     tracing::debug!("pack request: {} bytes from git", request_body.len());
 
     if request_body.is_empty() {
@@ -305,32 +310,14 @@ fn handle_connect<R: Read>(
         return Ok(());
     }
 
-    let post_url = format!("{}/{}", repo_base, service);
-    tracing::debug!("POST {post_url} ({} bytes)", request_body.len());
-
-    let req = build_pack_post_request(&client, &post_url, service, &request_body, signing_key);
-
-    // Attach the body after signing so the pack bytes are moved, not cloned —
-    // packs can be large and the clone doubled peak memory on push.
-    let pack_resp = req
-        .body(request_body)
-        .send()
-        .with_context(|| format!("POST {post_url}"))?;
-
-    if !pack_resp.status().is_success() {
-        let status = pack_resp.status();
-        let body = read_error_body(pack_resp);
-        let path = format!("/{service}");
-        bail!("{}", http_error_message("POST", &path, status, &body, None));
-    }
-
-    let pack_bytes = pack_resp.bytes().context("reading pack response")?;
-    tracing::debug!("pack response: {} bytes from node", pack_bytes.len());
-
-    stdout.write_all(&pack_bytes)?;
-    stdout.flush()?;
-
-    Ok(())
+    post_pack_round(
+        &client,
+        &post_url,
+        service,
+        signing_key,
+        request_body,
+        &mut stdout,
+    )
 }
 
 // ── Smart-protocol request builders ───────────────────────────────────────────
@@ -424,33 +411,55 @@ fn parse_gitlawb_url(url: &str) -> Result<(String, String, String)> {
     Ok((did_string.to_string(), short_owner, repo_name))
 }
 
-/// Read a complete git-upload-pack request from the pkt-line stream.
+/// How a single upload-pack negotiation round ended.
+#[derive(Debug, PartialEq, Eq, Clone, Copy)]
+enum RoundEnd {
+    /// A flush pkt (`0000`) ended the round; more negotiation may follow.
+    Flush,
+    /// The terminal `done\n` pkt ended the round; the pack follows.
+    Done,
+    /// The stream ended (git closed its write pipe).
+    Eof,
+}
+
+/// Read ONE round of git's upload-pack request from the pkt-line stream.
 ///
-/// For upload-pack, git sends its want/have negotiation ending with the pkt-line
-/// `"done\n"` but does NOT close its write pipe afterwards — it waits for the
-/// server's pack response.  We detect the terminal "done\n" and stop reading.
-///
-/// We also handle the flush-only case (`"0000"`) that git sends when it already
-/// has everything it needs (up-to-date clone).
-fn read_upload_pack_request<R: Read>(stdin: &mut R) -> Result<Vec<u8>> {
-    let mut buf = Vec::new();
+/// Git speaks the stateful native protocol over the `connect` capability: it
+/// sends its `want` lines, a flush, then `have` batches each terminated by a
+/// flush, and blocks for the server's ACK/NAK after every flush before sending
+/// more haves or the terminal `done\n`. Each call returns one such round: the
+/// pkt-lines up to (but not including) the terminating flush or `done`, plus
+/// which terminator ended it. `negotiate_upload_pack` reassembles these into
+/// self-contained stateless-RPC POST bodies. Returning at the flush, instead of
+/// buffering past it waiting for `done`, is what lets a multi-round fetch make
+/// progress rather than deadlock (#117).
+fn read_upload_pack_round<R: Read>(stdin: &mut R) -> Result<(Vec<u8>, RoundEnd)> {
+    let mut content = Vec::new();
 
     loop {
-        // Read the 4-byte hex pkt-line length prefix
+        // Read the 4-byte hex pkt-line length prefix.
         let mut len_bytes = [0u8; 4];
         match stdin.read_exact(&mut len_bytes) {
             Ok(_) => {}
-            Err(e) if e.kind() == io::ErrorKind::UnexpectedEof => break,
+            Err(e) if e.kind() == io::ErrorKind::UnexpectedEof => {
+                return Ok((content, RoundEnd::Eof));
+            }
             Err(e) => return Err(e.into()),
         }
-        buf.extend_from_slice(&len_bytes);
 
-        let len_hex = std::str::from_utf8(&len_bytes).unwrap_or("0000");
-        let pkt_len = usize::from_str_radix(len_hex, 16).unwrap_or(0);
+        // A malformed 4-byte length header must NOT be silently collapsed to a
+        // 0000 flush (#192 F5): that masks corrupted/desynchronized protocol input
+        // and can emit accumulated have lines as a synthesized flush round.
+        let Ok(len_hex) = std::str::from_utf8(&len_bytes) else {
+            bail!("malformed pkt-line length prefix: non-UTF-8 bytes {len_bytes:02x?}");
+        };
+        let Ok(pkt_len) = usize::from_str_radix(len_hex, 16) else {
+            bail!("malformed pkt-line length prefix: non-hex {len_hex:?}");
+        };
 
         if pkt_len == 0 {
-            // Flush pkt "0000" — keep buffering (more pkt-lines may follow)
-            continue;
+            // Flush pkt "0000": this round is complete.
+            return Ok((content, RoundEnd::Flush));
         }
 
         if pkt_len < 4 {
@@ -462,16 +471,149 @@ fn read_upload_pack_request<R: Read>(stdin: &mut R) -> Result<Vec<u8>> {
         stdin
             .read_exact(&mut data)
             .context("reading pkt-line data")?;
-        buf.extend_from_slice(&data);
 
-        // "done\n" signals the end of the want/have negotiation
+        // "done\n" ends the negotiation; the pack follows. The terminator is
+        // reported out-of-band and re-emitted by the caller, so it is not
+        // appended to `content`.
         if data == b"done\n" {
-            tracing::debug!("upload-pack: got 'done', request complete");
-            break;
+            tracing::debug!("upload-pack: got 'done', round complete");
+            return Ok((content, RoundEnd::Done));
         }
+
+        content.extend_from_slice(&len_bytes);
+        content.extend_from_slice(&data);
+    }
+}
+
+/// POST one self-contained stateless-RPC request body and stream the response to
+/// `stdout`. Signs the request when `signing_key` is present, so every round of a
+/// private-repo fetch carries the caller's signature (the node visibility-gates
+/// each POST at "/"). A non-2xx status surfaces through the sanitized error path
+/// rather than being rendered as an empty or successful fetch (INV-6/INV-8).
+fn post_pack_round(
+    client: &reqwest::blocking::Client,
+    post_url: &str,
+    service: &str,
+    signing_key: Option<&Keypair>,
+    body: Vec<u8>,
+    stdout: &mut impl Write,
+) -> Result<()> {
+    tracing::debug!("POST {post_url} ({} bytes)", body.len());
+    let req = build_pack_post_request(client, post_url, service, &body, signing_key);
+    // Attach the body after signing so the bytes are moved, not cloned.
+    let resp = req
+        .body(body)
+        .send()
+        .with_context(|| format!("POST {post_url}"))?;
+
+    if !resp.status().is_success() {
+        let status = resp.status();
+        let err_body = read_error_body(resp);
+        let path = format!("/{service}");
+        bail!(
+            "{}",
+            http_error_message("POST", &path, status, &err_body, None)
+        );
     }
 
-    Ok(buf)
+    let bytes = resp.bytes().context("reading pack response")?;
+    tracing::debug!("pack response: {} bytes from node", bytes.len());
+    stdout.write_all(&bytes)?;
+    stdout.flush()?;
+    Ok(())
+}
+
+/// Drive a git-upload-pack fetch as a v0 smart-HTTP stateless-RPC client.
+///
+/// Git (over `connect`) speaks the stateful native protocol; the node serves
+/// `git upload-pack --stateless-rpc`, which keeps no state between POSTs. Bridge
+/// the two: capture the want block once, then for each flush-terminated have
+/// batch POST a self-contained request (the wants plus every have accumulated so
+/// far, then exactly one terminator) and stream the ACK/NAK back to git so it can
+/// continue. The `done` round returns the pack. Every POST re-sends the wants and
+/// all prior haves because the server is stateless; leaving an intermediate flush
+/// in the body would truncate the negotiation, so each body carries exactly one
+/// terminator.
+fn negotiate_upload_pack<R: Read>(
+    client: &reqwest::blocking::Client,
+    post_url: &str,
+    service: &str,
+    signing_key: Option<&Keypair>,
+    stdin: &mut R,
+    stdout: &mut impl Write,
+) -> Result<()> {
+    // Opening round: the want block, a bare `done`, or an empty/flush-only
+    // request from an up-to-date or aborted fetch.
+    let (wants, wend) = read_upload_pack_round(stdin)?;
+    match wend {
+        // Up-to-date with an empty request, truncated, or aborted before a
+        // terminator: nothing safe to POST.
+        RoundEnd::Eof => return Ok(()),
+        // A `done` with no preceding want-section flush: the bare-`done` request
+        // the single-round tests feed. Forward it verbatim as one POST.
+        RoundEnd::Done => {
+            let mut body = wants;
+            body.extend_from_slice(b"0009done\n");
+            return post_pack_round(client, post_url, service, signing_key, body, stdout);
+        }
+        // Normal: the want section ended with its flush; negotiate the haves.
+        // (An empty want block here is a flush-only opener and falls through to
+        // the loop, which POSTs nothing and returns at EOF.)
+        RoundEnd::Flush => {}
+    }
+
+    // The node is stateless between POSTs, so re-send the wants and every have so
+    // far in each round.
+    let mut acc_haves: Vec<u8> = Vec::new();
+    loop {
+        let (batch, bend) = read_upload_pack_round(stdin)?;
+
+        // Only POST when a round carries new haves or a terminator. A round with no
+        // new haves needs no request: an empty EOF ends the fetch, and a bare flush
+        // (git never sends a content-free flush mid-negotiation, but a malformed
+        // stream could) is skipped so a run of empty flushes cannot amplify into one
+        // signed POST each. A `done` round with no haves still POSTs (the fresh-clone
+        // case), handled by the terminator match below.
+        match (batch.is_empty(), bend) {
+            (true, RoundEnd::Eof) => return Ok(()),
+            (true, RoundEnd::Flush) => continue,
+            _ => {}
+        }
+
+        acc_haves.extend_from_slice(&batch);
+
+        // Compose a self-contained stateless-RPC request: wants + one flush + all
+        // accumulated haves + exactly one terminator. No intermediate flush
+        // survives into the body, or the stateless server treats the first flush
+        // after the haves as end-of-request and truncates the negotiation.
+        let mut body = wants.clone();
+        body.extend_from_slice(b"0000");
+        body.extend_from_slice(&acc_haves);
+
+        let final_round = match bend {
+            RoundEnd::Flush => {
+                body.extend_from_slice(b"0000");
+                false
+            }
+            // Only a real `done` pkt finalizes the stateless request.
+            RoundEnd::Done => {
+                body.extend_from_slice(b"0009done\n");
+                true
+            }
+            // A nonempty batch terminated by EOF (no flush, no done) means git
+            // ABORTED mid-negotiation (#192, F1). Terminate WITHOUT POSTing:
+            // synthesizing a `done` here would make the node generate and stream a
+            // full pack — signed, for a private fetch — to a client that has gone
+            // away. The accumulated haves are discarded; there is no one to serve.
+            RoundEnd::Eof => return Ok(()),
+        };
+
+        post_pack_round(client, post_url, service, signing_key, body, stdout)?;
+
+        if final_round {
+            return Ok(());
+        }
+    }
 }
 
 /// Strip the HTTP smart-protocol service announcement from a GET /info/refs response.
@@ -1100,6 +1242,35 @@ mod tests {
                 "a tampered @path must fail verification"
             );
         }
+
+        // #117: a multi-round POST body (wants + flush + accumulated haves + done)
+        // signs and verifies over its EXACT bytes. Each per-round POST a private
+        // fetch emits is a different accumulated body, and build_pack_post_request
+        // signs the same bytes it sends, so every round is independently accepted
+        // by the node verifier, not just the single-round `done` body.
+        let mut acc = Vec::new();
+        acc.extend_from_slice(&pkt(&format!(
+            "want {} multi_ack_detailed side-band-64k\n",
+            "a".repeat(40)
+        )));
+        acc.extend_from_slice(b"0000");
+        acc.extend_from_slice(&pkt(&format!("have {}\n", "1".repeat(40))));
+        acc.extend_from_slice(&pkt(&format!("have {}\n", "2".repeat(40))));
+        acc.extend_from_slice(&pkt("done\n"));
+        let post_url = "http://node.example/zOwner/myrepo/git-upload-pack";
+        let req = build_pack_post_request(&client, post_url, "git-upload-pack", &acc, Some(&kp))
+            .body(acc.clone())
+            .build()
+            .unwrap();
+        node_verifies(
+            "POST",
+            &path_and_query(&req),
+            &acc,
+            &header(&req, "signature-input"),
+            &header(&req, "signature"),
+            &header(&req, "content-digest"),
+        )
+        .expect("a multi-round accumulated POST body must verify under the node's verifier");
     }
 
     #[test]
@@ -1399,4 +1570,603 @@ mod tests {
         assert!(help.contains("GITLAWB_NODE"));
         assert!(help.ends_with('\n'));
     }
+
+    // ── #117 multi-round fetch negotiation ───────────────────────────────────
+
+    /// Encode a git pkt-line: 4-byte hex length (incl. the 4 bytes) + data.
+    fn pkt(data: &str) -> Vec<u8> {
+        format!("{:04x}{}", data.len() + 4, data).into_bytes()
+    }
+
+    /// A realistic capability-bearing opening want line (git puts its capability
+    /// list on the first want), so the multi-round tests exercise the want shape
+    /// real git actually sends, not a bare `want <sha>`.
+    fn want_line(sha: &str) -> Vec<u8> {
+        pkt(&format!(
+            "want {sha} multi_ack_detailed side-band-64k ofs-delta agent=git/2.43\n"
+        ))
+    }
+
+    /// A reader that yields `seed`, then BLOCKS until `gate` fires. Models git
+    /// holding the upload-pack pipe open after a have-batch flush, waiting for the
+    /// server's ACK/NAK before it sends more. A real pipe blocks here; an in-memory
+    /// Cursor would EOF and hide the bug, which is why the pre-#117 tests missed it.
+    struct BlockAfterSeed {
+        seed: io::Cursor<Vec<u8>>,
+        gate: std::sync::mpsc::Receiver<()>,
+    }
+    impl Read for BlockAfterSeed {
+        fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
+            let n = self.seed.read(buf)?;
+            if n > 0 {
+                return Ok(n);
+            }
+            let _ = self.gate.recv(); // block like a live pipe; unblock -> EOF
+            Ok(0)
+        }
+    }
+
+    /// #117 primitive contract (matrix item 1): `read_upload_pack_round` returns at
+    /// a flush-terminated batch instead of buffering past it waiting for `done`.
+    /// The pre-#117 `read_upload_pack_request` blocked here (the deadlock). A
+    /// blocking reader proves the return under live-pipe semantics: if the reader
+    /// buffered past the flush it would block on the gate and the test would time out.
+    #[test]
+    fn read_upload_pack_round_returns_on_flush_without_done() {
+        let mut seed = Vec::new();
+        seed.extend_from_slice(&want_line(&"a".repeat(40)));
+        seed.extend_from_slice(b"0000"); // end of wants
+        for i in 0..32u32 {
+            seed.extend_from_slice(&pkt(&format!("have {:040x}\n", i)));
+        }
+        seed.extend_from_slice(b"0000"); // have-batch flush; git awaits ACK, sends NO done
+
+        let (tx, rx) = std::sync::mpsc::channel::<()>();
+        let mut reader = BlockAfterSeed {
+            seed: io::Cursor::new(seed),
+            gate: rx,
+        };
+
+        let (done_tx, done_rx) = std::sync::mpsc::channel::<(Vec<u8>, RoundEnd)>();
+        let handle = std::thread::spawn(move || {
+            // Opening round (wants) returns at the first flush; the have batch
+            // returns at the second flush. Neither may block for a `done`.
+            let _wants = read_upload_pack_round(&mut reader).unwrap();
+            let haves = read_upload_pack_round(&mut reader).unwrap();
+            let _ = done_tx.send(haves);
+        });
+
+        let got = done_rx.recv_timeout(std::time::Duration::from_secs(2));
+        let _ = tx.send(()); // unblock the reader so the thread can exit
+        let _ = handle.join();
+
+        let (batch, end) = got.expect(
+            "read_upload_pack_round blocked past a flush-terminated have-batch \
+             waiting for `done` (multi-round fetch deadlock #117)",
+        );
+        assert_eq!(end, RoundEnd::Flush, "a flush terminates the round");
+        assert!(
+            batch.windows(4).any(|w| w == b"have"),
+            "the have batch content is returned to the caller"
+        );
+    }
+
+    /// #117 core (matrix item 2): a multi-round negotiation issues MORE THAN ONE
+    /// POST, and each POST body is a self-contained stateless-RPC request: wants +
+    /// one flush + every have accumulated so far + exactly one terminator. The
+    /// round-2 body is asserted byte-for-byte, which pins both accumulation (round
+    /// 1's have is present) and the one-terminator invariant (no intermediate flush
+    /// survives). Pre-#117 this was a single POST.
+    #[test]
+    fn multi_round_fetch_posts_each_round_with_accumulated_wants_and_haves() {
+        let want_sha = "a".repeat(40);
+        let have1 = "1".repeat(40);
+        let have2 = "2".repeat(40);
+        let (base_url, server) = serve_http(vec![
+            TestResponse {
+                request_line: "GET /zOwner/myrepo/info/refs?service=git-upload-pack",
+                status: "200 OK",
+                body: "0000",
+            },
+            // Round 1 (flush-terminated): an ACK/NAK continuation, no pack yet.
+            TestResponse {
+                request_line: "POST /zOwner/myrepo/git-upload-pack",
+                status: "200 OK",
+                body: "0008NAK\n",
+            },
+            // Round 2 (done): final response plus the (fake) pack.
+            TestResponse {
+                request_line: "POST /zOwner/myrepo/git-upload-pack",
+                status: "200 OK",
+                body: "0008NAK\nPACKfake",
+            },
+        ]);
+        let repo_base = format!("{base_url}/zOwner/myrepo");
+
+        let wants = want_line(&want_sha);
+        let mut stdin_bytes = Vec::new();
+        stdin_bytes.extend_from_slice(&wants);
+        stdin_bytes.extend_from_slice(b"0000"); // end of wants
+        stdin_bytes.extend_from_slice(&pkt(&format!("have {have1}\n")));
+        stdin_bytes.extend_from_slice(b"0000"); // round-1 flush: git awaits ACK
+        stdin_bytes.extend_from_slice(&pkt(&format!("have {have2}\n")));
+        stdin_bytes.extend_from_slice(&pkt("done\n")); // round-2 terminator
+
+        let mut stdin = io::Cursor::new(stdin_bytes);
+        handle_connect(&repo_base, "git-upload-pack", None, &mut stdin)
+            .expect("multi-round fetch should complete");
+
+        let requests = server.join().unwrap();
+        assert_eq!(
+            requests.len(),
+            3,
+            "GET + two POSTs, one per negotiation round"
+        );
+        assert!(
+            request_body(&requests[1])
+                .windows(want_sha.len())
+                .any(|w| w == want_sha.as_bytes()),
+            "round-1 POST must carry the wants"
+        );
+
+        // Round-2 body: wants + one flush + BOTH haves + done, with no flush
+        // between the haves (the accumulation + one-terminator invariant).
+        let mut expected = Vec::new();
+        expected.extend_from_slice(&wants);
+        expected.extend_from_slice(b"0000");
+        expected.extend_from_slice(&pkt(&format!("have {have1}\n")));
+        expected.extend_from_slice(&pkt(&format!("have {have2}\n")));
+        expected.extend_from_slice(&pkt("done\n"));
+        assert_eq!(
+            request_body(&requests[2]),
+            expected,
+            "round-2 POST body must be wants + flush + all accumulated haves + one done terminator"
+        );
+    }
+
+    /// Extract the HTTP request body (bytes after the header/body separator) from a
+    /// captured request string. pkt-lines are ASCII, so the lossy round-trip is exact.
+    fn request_body(request: &str) -> Vec<u8> {
+        match request.split_once("\r\n\r\n") {
+            Some((_, body)) => body.as_bytes().to_vec(),
+            None => Vec::new(),
+        }
+    }
+
+    /// U4 / INV-8 / INV-12: a private-repo multi-round fetch escalates on the 404
+    /// exactly once, then EVERY per-round POST carries the signature. Must-not: no
+    /// round goes out unsigned (an unsigned round 2 would 404 the owner's own fetch).
+    #[test]
+    fn private_multi_round_signs_every_post() {
+        let kp = Keypair::generate();
+        let (base_url, server) = serve_http(vec![
+            TestResponse {
+                request_line: "GET /zOwner/myrepo/info/refs?service=git-upload-pack",
+                status: "404 Not Found",
+                body: r#"{"message":"not found"}"#,
+            },
+            TestResponse {
+                request_line: "GET /zOwner/myrepo/info/refs?service=git-upload-pack",
+                status: "200 OK",
+                body: "0000",
+            },
+            TestResponse {
+                request_line: "POST /zOwner/myrepo/git-upload-pack",
+                status: "200 OK",
+                body: "0008NAK\n",
+            },
+            TestResponse {
+                request_line: "POST /zOwner/myrepo/git-upload-pack",
+                status: "200 OK",
+                body: "0008NAK\nPACKfake",
+            },
+        ]);
+        let repo_base = format!("{base_url}/zOwner/myrepo");
+        let mut stdin = io::Cursor::new(two_round_stdin());
+        handle_connect(&repo_base, "git-upload-pack", Some(&kp), &mut stdin)
+            .expect("private multi-round fetch should complete");
+
+        let requests = server.join().unwrap();
+        assert_eq!(
+            requests.len(),
+            4,
+            "anon GET, signed GET retry, then two signed POSTs"
+        );
+        assert!(
+            !requests[0].to_lowercase().contains("signature-input"),
+            "first GET is anonymous"
+        );
+        assert!(
+            requests[1].to_lowercase().contains("signature-input"),
+            "GET retry is signed"
+        );
+        assert!(
+            requests[2].to_lowercase().contains("signature-input"),
+            "round-1 POST is signed"
+        );
+        assert!(
+            requests[3].to_lowercase().contains("signature-input"),
+            "round-2 POST is signed: no per-round POST may go out unsigned for a private repo"
+        );
+    }
+
+    /// U4: a public multi-round fetch stays anonymous on EVERY round even with a
+    /// keypair present. Must-not: no round signs (no DID disclosure on a public fetch).
+    #[test]
+    fn public_multi_round_stays_anonymous_every_post() {
+        let kp = Keypair::generate();
+        let (base_url, server) = serve_http(vec![
+            TestResponse {
+                request_line: "GET /zOwner/myrepo/info/refs?service=git-upload-pack",
+                status: "200 OK",
+                body: "0000",
+            },
+            TestResponse {
+                request_line: "POST /zOwner/myrepo/git-upload-pack",
+                status: "200 OK",
+                body: "0008NAK\n",
+            },
+            TestResponse {
+                request_line: "POST /zOwner/myrepo/git-upload-pack",
+                status: "200 OK",
+                body: "0008NAK\nPACKfake",
+            },
+        ]);
+        let repo_base = format!("{base_url}/zOwner/myrepo");
+        let mut stdin = io::Cursor::new(two_round_stdin());
+        handle_connect(&repo_base, "git-upload-pack", Some(&kp), &mut stdin)
+            .expect("public multi-round fetch should complete");
+
+        let requests = server.join().unwrap();
+        assert_eq!(requests.len(), 3, "GET + two POSTs, no retry");
+        for (i, r) in requests.iter().enumerate() {
+            assert!(
+                !r.to_lowercase().contains("signature-input"),
+                "request {i} must stay anonymous on a public fetch"
+            );
+        }
+    }
+
+    /// U4 / INV-8 / INV-12: a denial mid-negotiation (round-2 POST 404) surfaces as
+    /// an error, not a silent empty/successful fetch, and does NOT re-trigger the
+    /// Phase-1 signed-retry escalation (that is a GET-only, Phase-1-only behavior).
+    #[test]
+    fn mid_negotiation_post_denial_surfaces_without_reescalation() {
+        let (base_url, server) = serve_http(vec![
+            TestResponse {
+                request_line: "GET /zOwner/myrepo/info/refs?service=git-upload-pack",
+                status: "200 OK",
+                body: "0000",
+            },
+            TestResponse {
+                request_line: "POST /zOwner/myrepo/git-upload-pack",
+                status: "200 OK",
+                body: "0008NAK\n",
+            },
+            TestResponse {
+                request_line: "POST /zOwner/myrepo/git-upload-pack",
+                status: "404 Not Found",
+                body: r#"{"message":"repository is no longer readable"}"#,
+            },
+        ]);
+        let repo_base = format!("{base_url}/zOwner/myrepo");
+        let mut stdin = io::Cursor::new(two_round_stdin());
+        let err = handle_connect(&repo_base, "git-upload-pack", None, &mut stdin).unwrap_err();
+        let message = err.to_string();
+        assert!(
+            message.contains("POST /git-upload-pack returned 404 Not Found"),
+            "the mid-negotiation denial must surface, not read as an empty/successful fetch"
+        );
+        assert!(message.contains("repository is no longer readable"));
+        let requests = server.join().unwrap();
+        assert_eq!(
+            requests.len(),
+            3,
+            "GET + two POSTs, then bail: a POST denial must not re-run the Phase-1 escalation"
+        );
+    }
+
+    /// Two-round upload-pack request: wants, flush, have1, flush (round 1), have2,
+    /// done (round 2). Shared by the U4 signing/denial tests.
+    fn two_round_stdin() -> Vec<u8> {
+        let mut v = Vec::new();
+        v.extend_from_slice(&want_line(&"a".repeat(40)));
+        v.extend_from_slice(b"0000");
+        v.extend_from_slice(&pkt(&format!("have {}\n", "1".repeat(40))));
+        v.extend_from_slice(b"0000");
+        v.extend_from_slice(&pkt(&format!("have {}\n", "2".repeat(40))));
+        v.extend_from_slice(&pkt("done\n"));
+        v
+    }
+
+    /// U5 (matrix item 5, plumbing only): the node's withheld-blob path
+    /// (`upload_pack_excluding`) ignores negotiation and answers the first POST
+    /// with NAK plus a full self-contained pack. The helper must forward that
+    /// response and terminate without hanging. Whether REAL git accepts a pack
+    /// where it expected an ACK continuation is U7's real-git scenario, not this
+    /// mock (a Cursor never reacts to the response).
+    #[test]
+    fn withheld_shaped_response_is_forwarded_without_hanging() {
+        let (base_url, server) = serve_http(vec![
+            TestResponse {
+                request_line: "GET /zOwner/myrepo/info/refs?service=git-upload-pack",
+                status: "200 OK",
+                body: "0000",
+            },
+            // Withheld shape: NAK + full pack on the FIRST POST, negotiation ignored.
+            TestResponse {
+                request_line: "POST /zOwner/myrepo/git-upload-pack",
+                status: "200 OK",
+                body: "0008NAK\nPACKfullselfcontainedpack",
+            },
+        ]);
+        let repo_base = format!("{base_url}/zOwner/myrepo");
+        // A single flush-terminated round then EOF: the helper POSTs once, forwards
+        // the NAK+pack, and terminates at EOF rather than looping forever.
+        let mut stdin_bytes = Vec::new();
+        stdin_bytes.extend_from_slice(&want_line(&"a".repeat(40)));
+        stdin_bytes.extend_from_slice(b"0000");
+        stdin_bytes.extend_from_slice(&pkt(&format!("have {}\n", "1".repeat(40))));
+        stdin_bytes.extend_from_slice(b"0000");
+        let mut stdin = io::Cursor::new(stdin_bytes);
+        handle_connect(&repo_base, "git-upload-pack", None, &mut stdin)
+            .expect("withheld-shaped fetch should forward the pack and terminate");
+        let requests = server.join().unwrap();
+        assert_eq!(
+            requests.len(),
+            2,
+            "GET + one POST; the forwarded pack does not hang the helper"
+        );
+    }
+
+    /// U6 (matrix item 6): a fresh clone (wants, flush, done) issues exactly ONE POST.
+    #[test]
+    fn fresh_clone_issues_single_post() {
+        let want_sha = "a".repeat(40);
+        let (base_url, server) = serve_http(vec![
+            TestResponse {
+                request_line: "GET /zOwner/myrepo/info/refs?service=git-upload-pack",
+                status: "200 OK",
+                body: "0000",
+            },
+            TestResponse {
+                request_line: "POST /zOwner/myrepo/git-upload-pack",
+                status: "200 OK",
+                body: "0008NAK\nPACKfake",
+            },
+        ]);
+        let repo_base = format!("{base_url}/zOwner/myrepo");
+        let mut stdin_bytes = Vec::new();
+        stdin_bytes.extend_from_slice(&want_line(&want_sha));
+        stdin_bytes.extend_from_slice(b"0000");
+        stdin_bytes.extend_from_slice(&pkt("done\n"));
+        let mut stdin = io::Cursor::new(stdin_bytes);
+        handle_connect(&repo_base, "git-upload-pack", None, &mut stdin)
+            .expect("clone should complete");
+        let requests = server.join().unwrap();
+        assert_eq!(requests.len(), 2, "fresh clone is exactly one POST");
+        assert!(request_body(&requests[1])
+            .windows(want_sha.len())
+            .any(|w| w == want_sha.as_bytes()));
+    }
+
+    /// U6 (matrix item 6): an up-to-date / flush-only opener issues ZERO POSTs and
+    /// completes without entering an ACK wait.
+    #[test]
+    fn flush_only_opener_skips_post() {
+        let (base_url, server) = serve_http(vec![TestResponse {
+            request_line: "GET /zOwner/myrepo/info/refs?service=git-upload-pack",
+            status: "200 OK",
+            body: "0000",
+        }]);
+        let repo_base = format!("{base_url}/zOwner/myrepo");
+        let mut stdin = io::Cursor::new(b"0000".to_vec()); // flush only, nothing to fetch
+        handle_connect(&repo_base, "git-upload-pack", None, &mut stdin)
+            .expect("up-to-date fetch should complete");
+        let requests = server.join().unwrap();
+        assert_eq!(requests.len(), 1, "flush-only opener issues no POST");
+    }
+
+    /// U6 (matrix item 6): a single-shot fetch git resolved in one round (wants,
+    /// flush, haves, done, no intermediate flush) issues exactly ONE POST. Must-not:
+    /// the fix must not split a single-shot negotiation into multiple POSTs.
+    #[test]
+    fn single_shot_fetch_is_one_post() {
+        let (base_url, server) = serve_http(vec![
+            TestResponse {
+                request_line: "GET /zOwner/myrepo/info/refs?service=git-upload-pack",
+                status: "200 OK",
+                body: "0000",
+            },
+            TestResponse {
+                request_line: "POST /zOwner/myrepo/git-upload-pack",
+                status: "200 OK",
+                body: "0008NAK\nPACKfake",
+            },
+        ]);
+        let repo_base = format!("{base_url}/zOwner/myrepo");
+        let mut stdin_bytes = Vec::new();
+        stdin_bytes.extend_from_slice(&want_line(&"a".repeat(40)));
+        stdin_bytes.extend_from_slice(b"0000");
+        stdin_bytes.extend_from_slice(&pkt(&format!("have {}\n", "1".repeat(40))));
+        stdin_bytes.extend_from_slice(&pkt(&format!("have {}\n", "2".repeat(40))));
+        stdin_bytes.extend_from_slice(&pkt("done\n")); // done with no intermediate flush
+        let mut stdin = io::Cursor::new(stdin_bytes);
+        handle_connect(&repo_base, "git-upload-pack", None, &mut stdin)
+            .expect("fetch should complete");
+        let requests = server.join().unwrap();
+        assert_eq!(
+            requests.len(),
+            2,
+            "a single-shot negotiation must be exactly one POST, not split"
+        );
+    }
+
+    /// Hardening: content-free flush pkts between the wants and the first haves do
+    /// not each fire a POST. Real git never sends a bare mid-negotiation flush, but
+    /// a malformed stream must not amplify into one signed POST per empty flush; the
+    /// loop skips them and POSTs only the round that carries haves + done.
+    #[test]
+    fn repeated_bare_flushes_do_not_amplify_posts() {
+        let (base_url, server) = serve_http(vec![
+            TestResponse {
+                request_line: "GET /zOwner/myrepo/info/refs?service=git-upload-pack",
+                status: "200 OK",
+                body: "0000",
+            },
+            TestResponse {
+                request_line: "POST /zOwner/myrepo/git-upload-pack",
+                status: "200 OK",
+                body: "0008NAK\nPACKfake",
+            },
+        ]);
+        let repo_base = format!("{base_url}/zOwner/myrepo");
+        let mut stdin_bytes = Vec::new();
+        stdin_bytes.extend_from_slice(&want_line(&"a".repeat(40)));
+        stdin_bytes.extend_from_slice(b"0000");
+        stdin_bytes.extend_from_slice(b"0000"); // bare flush, no haves
+        stdin_bytes.extend_from_slice(b"0000"); // bare flush, no haves
+        stdin_bytes.extend_from_slice(&pkt(&format!("have {}\n", "1".repeat(40))));
+        stdin_bytes.extend_from_slice(&pkt("done\n"));
+        let mut stdin = io::Cursor::new(stdin_bytes);
+        handle_connect(&repo_base, "git-upload-pack", None, &mut stdin)
+            .expect("fetch with stray flushes should complete");
+        let requests = server.join().unwrap();
+        assert_eq!(
+            requests.len(),
+            2,
+            "content-free flushes must not each produce a POST"
+        );
+    }
+
+    // ── Branch-coverage closure: exercise the remaining changed arms ─────────
+
+    /// A reader that fails with a non-EOF io error, to exercise the error
+    /// propagation arm of `read_upload_pack_round` (distinct from a clean EOF).
+    struct FailingReader;
+    impl Read for FailingReader {
+        fn read(&mut self, _buf: &mut [u8]) -> io::Result<usize> {
+            Err(io::Error::other("simulated read failure"))
+        }
+    }
+
+    /// G4: a non-EOF read error propagates; it is not swallowed as end-of-stream.
+    #[test]
+    fn read_upload_pack_round_propagates_read_error() {
+        let mut r = FailingReader;
+        assert!(read_upload_pack_round(&mut r).is_err());
+    }
+
+    /// G1: an invalid pkt-line length (1..=3) is rejected rather than underflowing
+    /// `pkt_len - 4`.
+    #[test]
+    fn read_upload_pack_round_rejects_invalid_pkt_length() {
+        let mut r = io::Cursor::new(b"0001".to_vec()); // pkt_len 1, < 4
+        let err = read_upload_pack_round(&mut r).unwrap_err();
+        assert!(
+            err.to_string().contains("invalid pkt-line length"),
+            "unexpected error: {err}"
+        );
+    }
+
+    /// #192 F5: a non-hex length header (e.g. "zzzz") is a malformed frame and must
+    /// be rejected, not silently collapsed to a 0000 flush.
+    #[test]
+    fn read_upload_pack_round_rejects_non_hex_length() {
+        let mut r = io::Cursor::new(b"zzzzdone\n".to_vec());
+        let err = read_upload_pack_round(&mut r).unwrap_err();
+        assert!(
+            err.to_string().to_lowercase().contains("pkt-line"),
+            "unexpected error: {err}"
+        );
+    }
+
+    /// #192 F5: a non-UTF-8 length header must be rejected, not treated as a flush.
+    #[test]
+    fn read_upload_pack_round_rejects_non_utf8_length() {
+        let mut r = io::Cursor::new(vec![0xffu8, 0xff, 0xff, 0xff]);
+        let err = read_upload_pack_round(&mut r).unwrap_err();
+        assert!(
+            err.to_string().to_lowercase().contains("pkt-line"),
+            "unexpected error: {err}"
+        );
+    }
+
+    /// G2: an immediately-empty upload-pack request (EOF at the opening round, with
+    /// a 200 advertisement) skips the POST entirely.
+    #[test]
+    fn upload_pack_empty_request_skips_post() {
+        let (base_url, server) = serve_http(vec![TestResponse {
+            request_line: "GET /zOwner/myrepo/info/refs?service=git-upload-pack",
+            status: "200 OK",
+            body: "0000",
+        }]);
+        let repo_base = format!("{base_url}/zOwner/myrepo");
+        let mut stdin = io::Cursor::new(Vec::<u8>::new()); // immediate EOF
+        handle_connect(&repo_base, "git-upload-pack", None, &mut stdin)
+            .expect("empty upload-pack request should skip the POST");
+        let requests = server.join().unwrap();
+        assert_eq!(
+            requests.len(),
+            1,
+            "empty request must issue the GET only, no POST"
+        );
+    }
+
+    /// G3 (#192, F1): a nonempty have-batch terminated by EOF (no flush, no done)
+    /// means git ABORTED mid-negotiation. The helper must terminate WITHOUT POSTing
+    /// — synthesizing a `done` and sending it would make the node generate and
+    /// stream a full pack (signed, for a private fetch) to a client that has gone
+    /// away. Only a real `done` pkt finalizes the stateless request. RED before the
+    /// fix (the folded `Done | Eof` arm POSTs a synthetic done → 2 requests), GREEN
+    /// after (only the info/refs GET, no upload-pack POST).
+    #[test]
+    fn nonempty_eof_batch_aborts_without_posting() {
+        // Only the info/refs GET is served (serve_http accepts exactly N conns). The
+        // fixed helper makes exactly that one request and stops. The pre-fix code
+        // additionally POSTs the synthetic done; that POST hits the now-closed
+        // listener and errors, so handle_connect returns Err and the `.expect` below
+        // fires — the RED. The fixed code returns Ok with one recorded request.
+        let (base_url, server) = serve_http(vec![TestResponse {
+            request_line: "GET /zOwner/myrepo/info/refs?service=git-upload-pack",
+            status: "200 OK",
+            body: "0000",
+        }]);
+        let repo_base = format!("{base_url}/zOwner/myrepo");
+        let mut stdin_bytes = Vec::new();
+        stdin_bytes.extend_from_slice(&want_line(&"a".repeat(40)));
+        stdin_bytes.extend_from_slice(b"0000");
+        stdin_bytes.extend_from_slice(&pkt(&format!("have {}\n", "1".repeat(40))));
+        // No trailing flush or done: the stream just ends (EOF) after the have —
+        // git aborted the negotiation.
+        let mut stdin = io::Cursor::new(stdin_bytes);
+        handle_connect(&repo_base, "git-upload-pack", None, &mut stdin)
+            .expect("an aborted (EOF) negotiation is a clean no-op, not an error");
+        let requests = server.join().unwrap();
+        assert_eq!(
+            requests.len(),
+            1,
+            "an aborted EOF must NOT trigger an upload-pack POST (only the info/refs GET)"
+        );
+    }
+
+    /// G5: an empty receive-pack (push) body skips the POST, unchanged from before.
+    #[test]
+    fn receive_pack_empty_body_skips_post() {
+        let (base_url, server) = serve_http(vec![TestResponse {
+            request_line: "GET /zOwner/myrepo/info/refs?service=git-receive-pack",
+            status: "200 OK",
+            body: "0000",
+        }]);
+        let repo_base = format!("{base_url}/zOwner/myrepo");
+        let mut stdin = io::Cursor::new(Vec::<u8>::new()); // empty push
+        handle_connect(&repo_base, "git-receive-pack", None, &mut stdin)
+            .expect("empty receive-pack should skip the POST");
+        let requests = server.join().unwrap();
+        assert_eq!(
+            requests.len(),
+            1,
+            "empty push must issue the GET only, no POST"
+        );
+    }
 }

crates/gitlawb-attest/src/attestation.rs

@@ -16,7 +16,7 @@
 //! by exact match.
 
 use base64::{engine::general_purpose::URL_SAFE_NO_PAD as B64U, Engine};
-use ed25519_dalek::{Signature, Signer, SigningKey, Verifier, VerifyingKey};
+use ed25519_dalek::{Signature, Signer, SigningKey, VerifyingKey};
 use serde::{de::DeserializeOwned, Deserialize, Serialize};
 
 use crate::error::{Error, Result};
@@ -111,7 +111,7 @@ impl Attestation {
             .try_into()
             .map_err(|_| Error::Signature("signature must be 64 bytes".to_string()))?;
         let sig = Signature::from_bytes(&sig_bytes);
-        vk.verify(&bytes, &sig)
+        vk.verify_strict(&bytes, &sig)
             .map_err(|e| Error::Signature(format!("ed25519: {e}")))?;
 
         Ok(vk)
@@ -554,4 +554,39 @@ mod tests {
         let err = tampered.verify_signature(cert_hash).unwrap_err();
         assert!(matches!(err, Error::Signature(_)));
     }
+
+    /// Regression guard for strict verification: a signature forged under a
+    /// weak (small-order) public key satisfies the verification equation
+    /// but must be rejected. The identity point is such a key: with R the
+    /// identity and S = 0, [S]B - [k]A is the identity for any message.
+    #[test]
+    fn verify_rejects_weak_key_signature() {
+        let mut weak_key_bytes = [0u8; 32];
+        weak_key_bytes[0] = 1; // compressed identity point (y = 1, x = 0)
+        let weak_vk = VerifyingKey::from_bytes(&weak_key_bytes).unwrap();
+        assert!(weak_vk.is_weak(), "identity point must be a weak key");
+
+        let cert_hash = sample_cert_hash();
+        let mut forged = [0u8; 64];
+        forged[0] = 1; // R = identity point, S = 0
+        let forged_sig = B64U.encode(forged);
+
+        // Build an attestation with the weak key as signer and the forged
+        // signature. The weak-key check happens at verify time.
+        let mut att = dummy_attestation(&SigningKey::generate(&mut OsRng), cert_hash);
+        let mut buf = Vec::with_capacity(ED25519_MULTICODEC.len() + 32);
+        buf.extend_from_slice(&ED25519_MULTICODEC);
+        buf.extend_from_slice(&weak_key_bytes);
+        att.signer = format!(
+            "did:key:{}",
+            multibase::encode(multibase::Base::Base58Btc, &buf)
+        );
+        att.sig = forged_sig;
+
+        let err = att.verify_signature(cert_hash).unwrap_err();
+        assert!(
+            matches!(err, Error::Signature(_)),
+            "signature under a weak (small-order) public key must be rejected"
+        );
+    }
 }

crates/gitlawb-core/src/cid.rs

@@ -64,6 +64,19 @@ impl Cid {
     }
 }
 
+/// True when `s` parses as a CIDv1 with the raw codec — the exact shape
+/// [`Cid::from_git_object_bytes`] produces and the `/ipfs` resolver looks up.
+/// A legacy provider CID (Kubo dag-pb, Pinata CIDv0) parses to a different
+/// version or codec and returns `false`, marking it an opportunistic-repair
+/// candidate. Decidable from the string alone (no object bytes), so the pin path
+/// can gate the byte-read/recompute cost on it and leave non-legacy rows at the
+/// existing DB-only skip cost. An unparseable string is non-canonical (`false`).
+pub fn is_raw_cidv1(s: &str) -> bool {
+    s.parse::<CidGeneric<64>>()
+        .map(|c| c.version() == cid::Version::V1 && c.codec() == RAW)
+        .unwrap_or(false)
+}
+
 impl fmt::Display for Cid {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         write!(f, "{}", self.0)
@@ -177,6 +190,38 @@ mod tests {
         assert!(result.is_err());
     }
 
+    #[test]
+    fn is_raw_cidv1_classifies_codec_from_string() {
+        // The canonical resolver key: CIDv1 + raw codec → not a repair candidate.
+        let raw = Cid::from_git_object_bytes(b"blob 5\0hello");
+        assert!(
+            is_raw_cidv1(raw.as_str()),
+            "from_git_object_bytes output is CIDv1/raw"
+        );
+
+        // A CIDv0 (Pinata dag-pb legacy shape) → repair candidate.
+        assert!(
+            !is_raw_cidv1("QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG"),
+            "a CIDv0 dag-pb value is a legacy-repair candidate"
+        );
+
+        // A CIDv1 with the dag-pb codec (the Kubo above-block-size root) over the
+        // same multihash → still a repair candidate (codec, not just version).
+        let parsed = raw.as_str().parse::<CidGeneric<64>>().unwrap();
+        const DAG_PB: u64 = 0x70;
+        let dagpb = CidGeneric::<64>::new_v1(DAG_PB, *parsed.hash()).to_string();
+        assert!(
+            !is_raw_cidv1(&dagpb),
+            "a CIDv1 dag-pb value is a legacy-repair candidate"
+        );
+
+        // Garbage is non-canonical.
+        assert!(
+            !is_raw_cidv1("not-a-cid"),
+            "an unparseable string is non-canonical"
+        );
+    }
+
     #[test]
     fn sha256_hex_of_empty_input_is_well_known() {
         // SHA-256("") is a fixed constant; verifies the hasher is wired correctly.

crates/gitlawb-core/src/did.rs

@@ -80,6 +80,19 @@ impl Did {
             )));
         }
 
+        // Refuse an oversized id before decoding. base58 decoding is quadratic
+        // in its input, and both callers of this function take the string from
+        // an untrusted request: the unauthenticated peer-announce gate, and the
+        // HTTP-signature keyid. An ed25519 did:key method-id is a fixed 48
+        // characters, so this bound is slack rather than a behavior change, and
+        // it has to sit ahead of the decode to be worth anything.
+        const MAX_METHOD_ID_LEN: usize = 64;
+        if self.method_id().len() > MAX_METHOD_ID_LEN {
+            return Err(Error::InvalidDid(
+                "did:key method-specific id too long".to_string(),
+            ));
+        }
+
         let (_, bytes) =
             multibase::decode(self.method_id()).map_err(|e| Error::InvalidDid(e.to_string()))?;
 
@@ -308,4 +321,52 @@ mod tests {
         assert_eq!(Did::web("example.com").method_id(), "example.com");
         assert_eq!(Did::gitlawb("z6MkSomeKey").method_id(), "z6MkSomeKey");
     }
+
+    /// An oversized method-specific id is refused on its length, before the
+    /// base58 decode runs.
+    ///
+    /// base58 decoding is quadratic in the input, and `to_verifying_key` is
+    /// reached from two places that take an attacker-supplied string: the
+    /// unauthenticated peer-announce gate, and the HTTP-signature keyid. A
+    /// 64k-character DID measured 8s through the router without this guard
+    /// against 4.6ms with it, on a tokio worker with no spawn_blocking, so a
+    /// single caller could buy CPU-seconds by the thousand.
+    ///
+    /// Asserting the MESSAGE is what makes this load-bearing: an oversized id
+    /// errors either way, so a test that only checked `is_err()` would pass
+    /// with the guard removed, having merely paid the cost it exists to avoid.
+    #[test]
+    fn to_verifying_key_rejects_an_oversized_method_id_before_decoding() {
+        let oversized = format!("did:key:z{}", "z".repeat(64_000));
+        let did: Did = oversized.parse().expect("method is still `key`");
+
+        let start = std::time::Instant::now();
+        let err = did.to_verifying_key().expect_err("must be refused");
+        let elapsed = start.elapsed();
+
+        assert!(
+            err.to_string().contains("too long"),
+            "must be refused on length, not after the decode: {err}"
+        );
+        assert!(
+            elapsed < std::time::Duration::from_secs(1),
+            "refusal must not pay the quadratic decode: took {elapsed:?}"
+        );
+    }
+
+    /// The bound must not reject a real key. Every `did:key` this project
+    /// mints is a fixed 48 characters, so the limit is slack, not a behavior
+    /// change.
+    #[test]
+    fn to_verifying_key_still_accepts_a_real_did_key() {
+        use ed25519_dalek::SigningKey;
+        let signing = SigningKey::from_bytes(&[7u8; 32]);
+        let did = Did::from_verifying_key(&signing.verifying_key());
+        assert_eq!(
+            did.method_id().len(),
+            48,
+            "did:key method-id is fixed-width"
+        );
+        did.to_verifying_key().expect("a real did:key must resolve");
+    }
 }

crates/gitlawb-core/src/identity.rs

@@ -78,10 +78,9 @@ impl Keypair {
 
 /// Verify an Ed25519 signature.
 pub fn verify(verifying_key: &VerifyingKey, msg: &[u8], sig_bytes: &[u8; 64]) -> Result<()> {
-    use ed25519_dalek::Verifier;
     let sig = Signature::from_bytes(sig_bytes);
     verifying_key
-        .verify(msg, &sig)
+        .verify_strict(msg, &sig)
         .map_err(|_| Error::SignatureInvalid)
 }
 
@@ -209,6 +208,28 @@ mod tests {
         );
     }
 
+    #[test]
+    fn verify_rejects_weak_key_signature() {
+        // Regression guard for strict verification: a signature forged under a
+        // weak (small-order) public key satisfies the verification equation
+        // but must be rejected. The identity point is such a key: with R the
+        // identity and S = 0, [S]B - [k]A is the identity for any message.
+        let mut weak_key_bytes = [0u8; 32];
+        weak_key_bytes[0] = 1; // compressed identity point (y = 1, x = 0)
+        let weak_vk = VerifyingKey::from_bytes(&weak_key_bytes).unwrap();
+        assert!(weak_vk.is_weak(), "identity point must be a weak key");
+
+        let msg = b"forged message";
+        let mut forged = [0u8; 64];
+        forged[0] = 1; // R = identity point, S = 0
+
+        let result = verify(&weak_vk, msg, &forged);
+        assert!(
+            result.is_err(),
+            "signature under a weak (small-order) public key must be rejected"
+        );
+    }
+
     #[test]
     fn signed_payload_round_trip() {
         let kp = Keypair::generate();

crates/gitlawb-node/Cargo.toml

@@ -77,3 +77,6 @@ libp2p-dns = { version = "0.44.0", features = ["tokio"] }
 [dev-dependencies]
 mockito = "1"
 tempfile = "3"
+# `test-util` for `#[tokio::test(start_paused = true)]`: lets the deadline tests assert
+# on which timer fired instead of on wall clock.
+tokio = { workspace = true, features = ["test-util"] }

crates/gitlawb-node/src/api/arweave.rs

@@ -26,14 +26,61 @@ pub async fn list_anchors(
     Query(q): Query<ListAnchorsQuery>,
 ) -> Result<Json<serde_json::Value>> {
     let limit = q.limit.min(200);
+    // Bare `?` so connection-class sqlx failures downcast to `AppError::Db` and
+    // map to 503 `db_unavailable` (not 500 via `.map_err(AppError::Internal)`) (#251).
     let anchors = state
         .db
         .list_arweave_anchors(q.repo.as_deref(), limit)
-        .await
-        .map_err(crate::error::AppError::Internal)?;
+        .await?;
 
     Ok(Json(serde_json::json!({
         "anchors": anchors,
         "count": anchors.len(),
     })))
 }
+
+#[cfg(test)]
+mod closed_pool_tests {
+    use super::*;
+    use axum::http::{Request, StatusCode};
+    use axum::Router;
+    use serde_json::Value;
+    use sqlx::PgPool;
+    use tower::ServiceExt;
+
+    /// #251: a closed pool on /api/v1/arweave/anchors must be 503 db_unavailable.
+    #[sqlx::test]
+    async fn list_anchors_closed_pool_returns_503_db_unavailable(pool: PgPool) {
+        let state = crate::test_support::test_state(pool.clone()).await;
+        pool.close().await;
+
+        let resp = Router::new()
+            .route("/api/v1/arweave/anchors", axum::routing::get(list_anchors))
+            .with_state(state)
+            .oneshot(
+                Request::builder()
+                    .uri("/api/v1/arweave/anchors")
+                    .body(axum::body::Body::empty())
+                    .unwrap(),
+            )
+            .await
+            .unwrap();
+
+        assert_eq!(
+            resp.status(),
+            StatusCode::SERVICE_UNAVAILABLE,
+            "closed-pool outage must be retryable 503, not 500"
+        );
+        let bytes = axum::body::to_bytes(resp.into_body(), usize::MAX)
+            .await
+            .expect("read body");
+        let v: Value = serde_json::from_slice(&bytes).expect("json body");
+        assert_eq!(
+            v,
+            serde_json::json!({
+                "error": crate::error::DB_UNAVAILABLE_CODE,
+                "message": crate::error::DB_UNAVAILABLE_MESSAGE,
+            })
+        );
+    }
+}

crates/gitlawb-node/src/api/issues.rs

@@ -61,11 +61,14 @@ pub async fn create_issue(
     let json_str = serde_json::to_string(&issue)
         .map_err(|e| AppError::BadRequest(format!("serialization error: {e}")))?;
 
+    // Shed 503 + Retry-After on an exhausted write-lock POOL instead of a generic
+    // git 500 (#173 F1). This path holds no admission permit, so it reaches the pool
+    // unthrottled; reuse the push handler's mapping so the two cannot drift.
     let guard = state
         .repo_store
         .acquire_write(&record.owner_did, &record.name)
         .await
-        .map_err(|e| AppError::Git(e.to_string()))?;
+        .map_err(|e| crate::api::repos::acquire_write_app_error(&e, &repo))?;
     let disk_path = guard.path().to_path_buf();
 
     let create_result = git_issues::create_issue(&disk_path, &issue_id, &json_str);
@@ -229,11 +232,13 @@ pub async fn close_issue(
         .await?
         .ok_or_else(|| AppError::RepoNotFound(format!("{owner}/{repo}")))?;
 
+    // Same capacity shed as create_issue above (#173 F1): an exhausted write-lock
+    // pool is a 503 + Retry-After, not a 500 git error.
     let guard = state
         .repo_store
         .acquire_write(&record.owner_did, &record.name)
         .await
-        .map_err(|e| AppError::Git(e.to_string()))?;
+        .map_err(|e| crate::api::repos::acquire_write_app_error(&e, &repo))?;
     let disk_path = guard.path().to_path_buf();
 
     // Owner OR issue author may close. The author lives in the issue's git-JSON
@@ -279,3 +284,168 @@ pub async fn close_issue(
 
     Ok(Json(issue))
 }
+
+/// #173 F1 follow-up: the two issue write paths reach `acquire_write` holding NO
+/// admission permit (unlike the push handler, which is capped by the git-push
+/// semaphore), so they are the callers most likely to meet an exhausted write-lock
+/// POOL under load. An exhausted pool is a capacity signal, so both must shed
+/// 503 + Retry-After (`AppError::Overloaded`) the way the push handler does, not
+/// report the generic 500 git error that says nothing about retrying.
+#[cfg(test)]
+mod lock_pool_shed_tests {
+    use super::*;
+    use axum::response::IntoResponse;
+    use sqlx::PgPool;
+
+    fn seed_repo(owner_did: &str, name: &str) -> crate::db::RepoRecord {
+        let now = Utc::now();
+        crate::db::RepoRecord {
+            id: Uuid::new_v4().to_string(),
+            name: name.to_string(),
+            owner_did: owner_did.to_string(),
+            description: None,
+            is_public: true,
+            default_branch: "main".to_string(),
+            created_at: now,
+            updated_at: now,
+            disk_path: format!("/tmp/{name}"),
+            forked_from: None,
+            machine_id: None,
+        }
+    }
+
+    /// State whose repo store draws write locks from a ONE-connection pool with a
+    /// short checkout timeout, so a single held guard exhausts it promptly rather
+    /// than at the pool default.
+    async fn one_connection_lock_pool_state(pool: &PgPool) -> AppState {
+        let mut state = crate::test_support::test_state(pool.clone()).await;
+        state.repo_store = crate::git::repo_store::RepoStore::new(
+            std::path::PathBuf::from("/tmp/gitlawb-issues-lockpool"),
+            None,
+            crate::git::repo_store::build_lock_pool(pool, 1, std::time::Duration::from_secs(1)),
+        );
+        state
+    }
+
+    /// The shed must be a real 503 carrying Retry-After, not just an internal enum
+    /// variant: assert on the rendered response so a remapping of `Overloaded` is
+    /// caught here too.
+    fn assert_sheds_503_with_retry_after(err: AppError, what: &str) {
+        let resp = err.into_response();
+        assert_eq!(
+            resp.status(),
+            StatusCode::SERVICE_UNAVAILABLE,
+            "{what}: an exhausted write-lock pool must shed 503, not a 500 git error"
+        );
+        assert_eq!(
+            resp.headers()
+                .get("retry-after")
+                .map(|v| v.to_str().unwrap()),
+            Some("1"),
+            "{what}: a capacity shed must tell the client when to retry"
+        );
+    }
+
+    /// RED-before/GREEN-after for `create_issue`. Both directions: the shed while the
+    /// only lock-pool connection is held by a guard on a DIFFERENT repo (so this is
+    /// pool capacity, not advisory-lock contention on this repo), and the must-not
+    /// case once that connection is back.
+    #[sqlx::test]
+    async fn create_issue_lock_pool_exhaustion_sheds_503_not_500(pool: PgPool) {
+        let owner = "did:key:zISSUECREATELOCKPOOLAAAAAAAAAAAAAAAAAAAA";
+        let state = one_connection_lock_pool_state(&pool).await;
+        state
+            .db
+            .create_repo(&seed_repo(owner, "lp-create"))
+            .await
+            .expect("seed repo");
+
+        let held = state
+            .repo_store
+            .acquire_write(owner, "other-repo")
+            .await
+            .expect("the first write takes the only lock-pool connection");
+
+        let shed = create_issue(
+            State(state.clone()),
+            Extension(AuthenticatedDid(owner.to_string())),
+            Path((owner.to_string(), "lp-create".to_string())),
+            Json(CreateIssueRequest {
+                title: "t".to_string(),
+                body: None,
+                signed_payload: None,
+            }),
+        )
+        .await;
+        let err = shed.expect_err("an exhausted lock pool must fail the call");
+        assert_sheds_503_with_retry_after(err, "create_issue");
+
+        // MUST-NOT: with the pool free again the call is not shed as capacity (it
+        // fails later on the nonexistent on-disk repo, which is a git 500).
+        held.release(false).await;
+        let admitted = create_issue(
+            State(state.clone()),
+            Extension(AuthenticatedDid(owner.to_string())),
+            Path((owner.to_string(), "lp-create".to_string())),
+            Json(CreateIssueRequest {
+                title: "t".to_string(),
+                body: None,
+                signed_payload: None,
+            }),
+        )
+        .await;
+        assert!(
+            !matches!(admitted, Err(AppError::Overloaded(_))),
+            "with the lock pool free, create_issue must not be shed as capacity; got {:?}",
+            admitted.err()
+        );
+    }
+
+    /// RED-before/GREEN-after for `close_issue`, same two directions.
+    #[sqlx::test]
+    async fn close_issue_lock_pool_exhaustion_sheds_503_not_500(pool: PgPool) {
+        let owner = "did:key:zISSUECLOSELOCKPOOLBBBBBBBBBBBBBBBBBBBBB";
+        let state = one_connection_lock_pool_state(&pool).await;
+        state
+            .db
+            .create_repo(&seed_repo(owner, "lp-close"))
+            .await
+            .expect("seed repo");
+
+        let held = state
+            .repo_store
+            .acquire_write(owner, "other-repo")
+            .await
+            .expect("the first write takes the only lock-pool connection");
+
+        let shed = close_issue(
+            State(state.clone()),
+            Extension(AuthenticatedDid(owner.to_string())),
+            Path((
+                owner.to_string(),
+                "lp-close".to_string(),
+                "deadbeef".to_string(),
+            )),
+        )
+        .await;
+        let err = shed.expect_err("an exhausted lock pool must fail the call");
+        assert_sheds_503_with_retry_after(err, "close_issue");
+
+        held.release(false).await;
+        let admitted = close_issue(
+            State(state.clone()),
+            Extension(AuthenticatedDid(owner.to_string())),
+            Path((
+                owner.to_string(),
+                "lp-close".to_string(),
+                "deadbeef".to_string(),
+            )),
+        )
+        .await;
+        assert!(
+            !matches!(admitted, Err(AppError::Overloaded(_))),
+            "with the lock pool free, close_issue must not be shed as capacity; got {:?}",
+            admitted.err()
+        );
+    }
+}

crates/gitlawb-node/src/api/mod.rs

@@ -22,7 +22,6 @@ pub mod replicas;
 pub mod repos;
 pub mod resolve;
 pub mod stars;
-pub mod status;
 pub mod tasks;
 pub mod visibility;
 pub mod webhooks;
@@ -68,14 +67,17 @@ pub(crate) async fn authorize_repo_read(
 /// representation only within `did:key`; never let a bare id match across methods —
 /// `did:web` / `did:gitlawb` share the base58 space with `did:key`, so a
 /// trailing-segment compare would treat `did:key:X` and `did:gitlawb:X` as equal.
-///
-/// The collapse itself lives in exactly one place, [`crate::db::normalize_owner_key`],
-/// which is also the function the stored `owner_did` / `authorizing_did` columns
-/// are normalized through and which `OWNER_KEY_CASE_SQL` mirrors byte for byte.
-/// Two identities match when they normalize to the same key; a second copy of the
-/// rule here is how the Rust gate and the SQL filters would drift apart.
 pub(crate) fn did_matches(a: &str, b: &str) -> bool {
-    crate::db::normalize_owner_key(a) == crate::db::normalize_owner_key(b)
+    if a == b {
+        return true;
+    }
+    fn key_id(d: &str) -> &str {
+        d.strip_prefix("did:key:").unwrap_or(d)
+    }
+    let (ka, kb) = (key_id(a), key_id(b));
+    // After stripping `did:key:`, a value still containing ':' is a non-key full
+    // DID — do not let it match a bare `did:key` id.
+    !ka.contains(':') && !kb.contains(':') && ka == kb
 }
 
 /// 403 unless `caller` is the repo owner. Uses [`did_matches`] so the owner check
@@ -173,7 +175,6 @@ mod authz_guard {
         let events = include_str!("events.rs");
         let tasks = include_str!("tasks.rs");
         let stars = include_str!("stars.rs");
-        let status = include_str!("status/mod.rs");
         let protect = include_str!("protect.rs");
         let visibility = include_str!("visibility.rs");
         let profiles = include_str!("profiles.rs");
@@ -194,13 +195,6 @@ mod authz_guard {
             // (existence hiding) and require_repo_owner guards the owner half.
             (webhooks, "list_webhooks", "authorize_repo_read("),
             (webhooks, "list_webhooks", "require_repo_owner("),
-            // Same two-half shape as list_webhooks: authorize_repo_read runs
-            // first (a quarantined or unreadable repo gets the missing-repo
-            // not-found, never a 403 that would confirm existence), then
-            // require_repo_owner 403s a non-owner of a readable repo. Both halves
-            // are pinned, because dropping either changes what a stranger learns.
-            (status, "create_status", "authorize_repo_read("),
-            (status, "create_status", "require_repo_owner("),
             (labels, "add_label", "require_repo_owner("),
             (labels, "remove_label", "require_repo_owner("),
             // Bucket A' — owner OR author (did_matches against the author)
@@ -214,28 +208,19 @@ mod authz_guard {
             (issues, "create_issue", "authorize_repo_read("),
             (bounties, "create_bounty", "authorize_repo_read("),
             (repos, "fork_repo", "authorize_repo_read("),
-            // get_by_cid gates each iterated repo row directly via visibility_check
-            // (KTD2a: it must NOT route through authorize_repo_read's fuzzy re-resolve).
-            (ipfs, "get_by_cid", "visibility_check("),
-            // #94 sibling read surfaces: gate private-repo metadata on read
-            // visibility (public repos stay anonymous; private repos 404).
+            // get_by_cid resolves each candidate (provenance path + legacy scan) through
+            // the shared `gate_and_serve`; the gate markers themselves are asserted
+            // below. This row proves the delegation is real, so the gate is actually
+            // reached rather than dead code. The delegated gate still calls
+            // `visibility_check` directly and never `authorize_repo_read`, so it keeps
+            // the property the pre-merge marker enforced: no fuzzy re-resolve.
+            (ipfs, "get_by_cid", "gate_and_serve("),
+            // Sibling read surfaces: gate private-repo metadata on read visibility
+            // (public repos stay anonymous; private repos 404).
             (replicas, "list_replicas", "authorize_repo_read("),
             (protect, "list_protected_branches", "authorize_repo_read("),
             (labels, "list_labels", "authorize_repo_read("),
             (events, "list_repo_events", "authorize_repo_read("),
-            // The catch-up poll surface gates before any push-event row is read,
-            // so a stranger cannot use it to learn that a private repo exists or
-            // is being pushed to.
-            (events, "list_repo_push_events", "authorize_repo_read("),
-            // The status read gates before any claim data is loaded, so its deny
-            // is the repo's own not-found rather than an existence oracle over
-            // which commits were reported on.
-            (status, "commit_status", "authorize_repo_read("),
-            // The rollup gates on the same helper before the pull request row is
-            // loaded, so a caller who cannot read the repo cannot learn which
-            // pull request numbers exist on it — and the fallback's branch
-            // resolve and head persist sit behind that same gate.
-            (status, "pull_request_status", "authorize_repo_read("),
             // Bucket C — signer-self: the acting DID is matched/bound to auth.0
             (tasks, "create_task", "did_matches("),
             (tasks, "claim_task", "did_matches("),
@@ -269,6 +254,22 @@ mod authz_guard {
             "visibility::require_owner must use did_matches for DID-safe owner matching"
         );
 
+        // The CID read surface (#173) enforces its gate inside the shared
+        // `gate_and_serve`, which BOTH the provenance path and the legacy scan call, so
+        // the markers must live there (the get_by_cid row above only proves delegation).
+        // The repo's own "/" visibility check (KTD2a — never authorize_repo_read's fuzzy
+        // re-resolve) and the quarantine hard-drop BEFORE visibility (INV-11) are both
+        // load-bearing: removing either re-opens a leak on the provenance path.
+        let gate_body = fn_body(ipfs, "gate_and_serve");
+        assert!(
+            gate_body.contains("visibility_check("),
+            "gate_and_serve must gate the CID read surface via visibility_check (KTD2a)"
+        );
+        assert!(
+            gate_body.contains("if quarantined"),
+            "gate_and_serve must hard-drop a quarantined repo before the visibility gate (INV-11)"
+        );
+
         for (src, func, marker) in rows {
             let body = fn_body(src, func);
             assert!(
@@ -509,7 +510,6 @@ mod authz_guard {
             (include_str!("replicas.rs"), "replicas.rs"),
             (include_str!("repos.rs"), "repos.rs"),
             (include_str!("stars.rs"), "stars.rs"),
-            (include_str!("status/mod.rs"), "status/mod.rs"),
             (include_str!("visibility.rs"), "visibility.rs"),
             (include_str!("webhooks.rs"), "webhooks.rs"),
         ];

crates/gitlawb-node/src/api/peers.rs

@@ -17,9 +17,39 @@ use gitlawb_core::did::Did;
 use serde::{Deserialize, Serialize};
 
 use crate::auth::AuthenticatedDid;
+use crate::db::{PeerWriteAuthority, PeerWriteDenied};
 use crate::error::{AppError, Result};
 use crate::state::AppState;
 
+/// Map an `upsert_peer` failure onto its response class.
+///
+/// The boundary's denials arrive inside an anyhow chain, so they are downcast
+/// back out the way `From<anyhow::Error> for AppError` already recovers sqlx
+/// errors. Without this a refusal renders as a 500, which is the mis-rendered
+/// denial this gate exists to avoid. An authority refusal is 403; naming a DID
+/// method that can never authenticate, or a DID whose verifying key cannot be
+/// resolved, is a fact about the input's form, so both are the 400 validation
+/// class, and the unresolvable one carries its own code so it reads the same to
+/// a client as the auth middleware's answer for an unresolvable keyid. The match
+/// stays exhaustive with no wildcard: the compile error a new denial causes here
+/// is what finds every mapping site.
+fn peer_write_error(err: anyhow::Error) -> AppError {
+    match err.downcast::<PeerWriteDenied>() {
+        Ok(denied) => match &denied {
+            PeerWriteDenied::UnsupportedDidMethod { .. } => {
+                AppError::BadRequest(denied.to_string())
+            }
+            PeerWriteDenied::UnresolvableDid { .. } => {
+                AppError::UnresolvableDid(denied.to_string())
+            }
+            PeerWriteDenied::UnprovenRepoint { .. } | PeerWriteDenied::ProofDidMismatch { .. } => {
+                AppError::Forbidden(denied.to_string())
+            }
+        },
+        Err(other) => AppError::from(other),
+    }
+}
+
 #[derive(Debug, Deserialize)]
 pub struct AnnounceRequest {
     /// The DID of the announcing node
@@ -187,18 +217,30 @@ pub async fn announce(
         .did
         .parse()
         .map_err(|e: gitlawb_core::Error| AppError::BadRequest(e.to_string()))?;
-    if let Some(Extension(auth)) = auth {
+    // The extension's DID is cryptographically derived, never body-supplied:
+    // auth/mod.rs resolves the verifying key FROM the keyid DID itself, so what
+    // is carried through to the upsert boundary below is a proof, not a claim.
+    let proven_did: Option<String> = if let Some(Extension(auth)) = auth {
+        // 403, not 400: this caller proved control of some DID and spent that
+        // proof on a different DID's row, which is a refusal of authority over
+        // the targeted row: the same denial as an unsigned repoint, and two
+        // callers denied for the same reason must not get different response
+        // classes. The 400 class stays for input-form failures: a malformed
+        // DID, a non-public URL, a self-announce, and a DID method that can
+        // never authenticate.
         if auth.0 != announced_did.to_string() {
-            return Err(AppError::BadRequest(
+            return Err(AppError::Forbidden(
                 "Signature keyid must match announced DID".into(),
             ));
         }
+        Some(auth.0)
     } else {
         tracing::warn!(
             did = %announced_did,
             "accepted unsigned peer announce; set GITLAWB_REQUIRE_SIGNED_PEER_WRITES=true after all peers upgrade"
         );
-    }
+        None
+    };
 
     // Validate the URL is a public http(s) endpoint. The announce route is
     // reachable unauthenticated (until all peers sign), so without this an
@@ -228,7 +270,20 @@ pub async fn announce(
         ));
     }
 
-    state.db.upsert_peer(&req.did, &req.http_url).await?;
+    // The authority declaration, not a re-statement of the check above: the
+    // boundary carries the proven DID and re-checks it against the row itself,
+    // so the keyid comparison above is an early rejection rather than the only
+    // gate. The other writer (the bootstrap announce-back in main.rs) never
+    // reaches this handler at all.
+    let authority = match proven_did.as_deref() {
+        Some(did) => PeerWriteAuthority::Proven(did),
+        None => PeerWriteAuthority::Unproven,
+    };
+    state
+        .db
+        .upsert_peer(&req.did, &req.http_url, authority)
+        .await
+        .map_err(peer_write_error)?;
 
     tracing::info!(did = %req.did, url = %req.http_url, "peer announced");
 
@@ -443,21 +498,15 @@ pub async fn ping_peer(
         .find(|p| p.did == did)
         .ok_or_else(|| AppError::RepoNotFound(format!("peer {did} not found")))?;
 
-    // Async ping
-    let url = format!("{}/health", peer.http_url.trim_end_matches('/'));
-    // Use the shared no-redirect client: bare `reqwest::get` follows redirects,
-    // so a peer could answer with `302 -> http://127.0.0.1/` and turn the ping
-    // into an SSRF probe.
-    let ok = state
-        .http_client
-        .get(&url)
-        .send()
-        .await
-        .map(|r| r.status().is_success())
-        .unwrap_or(false);
-
-    let _ = state.db.mark_peer_ping(&did, ok).await;
+    // Use DB-aware readiness rather than process liveness: `/health` stays 200
+    // during a mid-life database outage, while `/ready` reports 503. A 404-only
+    // fallback keeps pre-readiness peers compatible. The shared helper also
+    // preserves the no-redirect SSRF guard on peer-controlled URLs.
+    let ok = crate::ping_peer_readiness(&state.http_client, &peer.http_url).await;
 
+    // This anonymous diagnostic endpoint is intentionally read-only. The
+    // periodic gossip loop owns the persisted federation-reachability gate and
+    // requires consecutive failures before marking a peer unreachable.
     Ok(Json(serde_json::json!({
         "did": did,
         "http_url": peer.http_url,
@@ -564,7 +613,7 @@ mod tests {
     use axum::body::Body;
     use axum::extract::ConnectInfo;
     use axum::http::{header, Method, Request, StatusCode};
-    use axum::routing::post;
+    use axum::routing::{get, post};
     use axum::{middleware, Extension, Router};
     use gitlawb_core::http_sig::sign_request;
     use gitlawb_core::identity::Keypair;
@@ -770,12 +819,84 @@ mod tests {
         let did = Keypair::generate().did().to_string();
         state
             .db
-            .upsert_peer(&did, "https://peer.example.com")
+            .upsert_peer(
+                &did,
+                "https://peer.example.com",
+                crate::db::PeerWriteAuthority::Unproven,
+            )
             .await
             .unwrap();
         did
     }
 
+    #[sqlx::test]
+    async fn manual_ping_uses_readiness_without_mutating_federation_gate(pool: PgPool) {
+        let mut server = mockito::Server::new_async().await;
+        let ready = server
+            .mock("GET", "/ready")
+            .with_status(503)
+            .expect(1)
+            .create_async()
+            .await;
+        let health = server
+            .mock("GET", "/health")
+            .with_status(200)
+            .expect(0)
+            .create_async()
+            .await;
+
+        let mut state = test_state(pool.clone()).await;
+        state.http_client =
+            Arc::new(crate::build_http_client().expect("production HTTP client should build"));
+        let did = Keypair::generate().did().to_string();
+        let now = chrono::Utc::now().to_rfc3339();
+        sqlx::query(
+            "INSERT INTO peers (did, http_url, last_seen, last_ping_ok, announced_at)
+             VALUES ($1, $2, $3, TRUE, $3)",
+        )
+        .bind(&did)
+        .bind(server.url())
+        .bind(now)
+        .execute(&pool)
+        .await
+        .unwrap();
+
+        let response = Router::new()
+            .route("/api/v1/peers/{did}/ping", get(super::ping_peer))
+            .with_state(state.clone())
+            .oneshot(
+                Request::builder()
+                    .method(Method::GET)
+                    .uri(format!("/api/v1/peers/{did}/ping"))
+                    .body(Body::empty())
+                    .unwrap(),
+            )
+            .await
+            .unwrap();
+
+        assert_eq!(response.status(), StatusCode::OK);
+        let body = axum::body::to_bytes(response.into_body(), usize::MAX)
+            .await
+            .unwrap();
+        let json: serde_json::Value = serde_json::from_slice(&body).unwrap();
+        assert_eq!(json["reachable"], false);
+        ready.assert_async().await;
+        health.assert_async().await;
+
+        let peer = state
+            .db
+            .list_peers()
+            .await
+            .unwrap()
+            .into_iter()
+            .find(|peer| peer.did == did)
+            .unwrap();
+        assert!(
+            peer.last_ping_ok,
+            "an anonymous manual sample must not rewrite the federation gate"
+        );
+    }
+
     #[sqlx::test]
     async fn sync_notify_unsigned_flood_is_throttled(pool: PgPool) {
         // notify still accepts an unsigned known-peer notification (rolling-upgrade
@@ -1155,6 +1276,57 @@ mod tests {
         assert_eq!(resp.status(), StatusCode::OK);
     }
 
+    /// U1 (#273). An unsigned announce must not repoint an existing peer's row.
+    ///
+    /// Kills the unconditional `ON CONFLICT(did) DO UPDATE SET http_url = $2` in
+    /// `Db::upsert_peer`. The failure message carries BOTH observed values,
+    /// because the gate is the observed rewrite (2xx AND the attacker URL
+    /// stored), not merely a failing assertion: a 429 from the peer-write brake,
+    /// a fixture URL `is_public_http_url` rejects, or a DB error would all read
+    /// as "assertion failed" while proving nothing about this defect.
+    #[sqlx::test]
+    async fn unsigned_announce_cannot_repoint_an_existing_peer(pool: PgPool) {
+        const HONEST: &str = "https://honest-peer.example.com";
+        const ATTACKER: &str = "https://attacker.example.com";
+
+        let state = test_state(pool).await;
+        let did = Keypair::generate().did().to_string();
+        state
+            .db
+            .upsert_peer(&did, HONEST, crate::db::PeerWriteAuthority::Unproven)
+            .await
+            .unwrap();
+
+        let stored_url = |peers: Vec<crate::db::PeerRecord>| {
+            peers.into_iter().find(|p| p.did == did).map(|p| p.http_url)
+        };
+        assert_eq!(
+            stored_url(state.db.list_peers().await.unwrap()).as_deref(),
+            Some(HONEST),
+            "seed did not take; the case below would pass vacuously"
+        );
+
+        // Clone before build_router consumes state, so the row can be read back.
+        let db = state.db.clone();
+        let body = format!(r#"{{"did":"{did}","http_url":"{ATTACKER}"}}"#);
+        let resp = crate::server::build_router(state)
+            .oneshot(unsigned_post(
+                "/api/v1/peers/announce",
+                &body,
+                "203.0.113.77:5000",
+            ))
+            .await
+            .unwrap();
+        let status = resp.status();
+        let stored = stored_url(db.list_peers().await.unwrap())
+            .expect("peer row vanished; neither the allowed nor the denied outcome");
+
+        assert_eq!(
+            stored, HONEST,
+            "unsigned announce repointed an existing peer (observed status {status}, stored http_url {stored})"
+        );
+    }
+
     // Build a request carrying a REAL RFC 9421 signature (not just an injected
     // extension), so it passes require_signature on the full production router.
     fn real_signed_trigger(peer: &str) -> Request<Body> {
@@ -1265,4 +1437,607 @@ mod tests {
             "a 429 on a sync route must not say 'push': {s:?}"
         );
     }
+
+    // ── #273: the announce authority contract ─────────────────────────────────
+    //
+    // U4 drives the handler mounted alone, because signed_request_as injects an
+    // AuthenticatedDid extension without a real signature and require_signature
+    // would reject that on the full router. U5 then proves the same properties
+    // through build_router with REAL RFC 9421 signatures, where a signature can
+    // be pointed at a row it does not own.
+
+    const OWNER_URL: &str = "https://owner-peer.example.com";
+    const MOVED_URL: &str = "https://moved-peer.example.com";
+    const HIJACK_URL: &str = "https://hijacker.example.com";
+    const WEB_DID: &str = "did:web:squatter.example.com";
+    const KEYID_MISMATCH: &str = "Signature keyid must match announced DID";
+
+    /// Every column a consumer sees, so a case that claims "unchanged" compares
+    /// the whole row rather than the one field it happened to think of.
+    type PeerSnapshot = (String, String, Option<String>, bool, String);
+
+    async fn snapshot(db: &crate::db::Db, did: &str) -> Option<PeerSnapshot> {
+        db.list_peers()
+            .await
+            .unwrap()
+            .into_iter()
+            .find(|p| p.did == did)
+            .map(|p| {
+                (
+                    p.did,
+                    p.http_url,
+                    p.last_seen,
+                    p.last_ping_ok,
+                    p.announced_at,
+                )
+            })
+    }
+
+    /// Seed a peer row that has EARNED reachability, asserting the seed took,
+    /// so no case below can pass vacuously against a row that was never written
+    /// or against a flag that was already false. Without the granted ping a
+    /// "must be unreachable after this" assertion compares false to false and
+    /// stays green with the production code that clears the flag removed.
+    async fn seed_peer_row(state: &AppState, did: &str, url: &str) -> PeerSnapshot {
+        state
+            .db
+            .upsert_peer(did, url, crate::db::PeerWriteAuthority::Unproven)
+            .await
+            .expect("seed");
+        state.db.mark_peer_ping(did, true).await.expect("seed ping");
+        let seeded = snapshot(&state.db, did).await.expect("seed did not take");
+        assert_eq!(seeded.1, url, "seed did not take");
+        assert!(
+            seeded.3,
+            "the seeded row must start reachable, or a later unreachable assertion is vacuous"
+        );
+        seeded
+    }
+
+    /// Status, error code, and message together, so a denial is asserted by its
+    /// exact class and stated reason rather than by "not 2xx".
+    async fn status_and_error(resp: axum::response::Response) -> (StatusCode, String, String) {
+        let status = resp.status();
+        let bytes = axum::body::to_bytes(resp.into_body(), usize::MAX)
+            .await
+            .unwrap();
+        let v: serde_json::Value = serde_json::from_slice(&bytes).unwrap_or_else(|_| {
+            panic!(
+                "error body must be JSON: {}",
+                String::from_utf8_lossy(&bytes)
+            )
+        });
+        let field = |k: &str| v[k].as_str().unwrap_or_default().to_string();
+        (status, field("error"), field("message"))
+    }
+
+    fn announce_body(did: &str, url: &str) -> String {
+        format!(r#"{{"did":"{did}","http_url":"{url}"}}"#)
+    }
+
+    fn announce_only(state: AppState) -> Router {
+        Router::new()
+            .route("/api/v1/peers/announce", post(super::announce))
+            .with_state(state)
+    }
+
+    fn announce_as(did: &str, body: &str) -> Request<Body> {
+        signed_request_as(
+            did,
+            Method::POST,
+            "/api/v1/peers/announce",
+            Body::from(body.to_string()),
+        )
+    }
+
+    /// U4 scenario 1, and the first test the keyid branch has ever had: a caller
+    /// who proved control of one DID must not announce another's. Kills
+    /// neutralizing the handler's keyid comparison, and kills demoting this
+    /// denial back to the 400 validation class where the unsigned repoint below
+    /// is a 403 for the same reason.
+    #[sqlx::test]
+    async fn announce_keyid_mismatch_is_a_403_denial(pool: PgPool) {
+        let state = test_state(pool).await;
+        let victim = Keypair::generate().did().to_string();
+        let hijacker = Keypair::generate().did().to_string();
+        let before = seed_peer_row(&state, &victim, OWNER_URL).await;
+
+        let resp = announce_only(state.clone())
+            .oneshot(announce_as(&hijacker, &announce_body(&victim, HIJACK_URL)))
+            .await
+            .unwrap();
+
+        let (status, code, message) = status_and_error(resp).await;
+        assert_eq!(
+            status,
+            StatusCode::FORBIDDEN,
+            "a proof spent on another DID's row is an authority refusal: {message}"
+        );
+        assert_eq!(code, "forbidden", "denial body must name the 403 class");
+        assert!(
+            message.contains(KEYID_MISMATCH),
+            "the denial must name the keyid mismatch, got {message:?}"
+        );
+        assert_eq!(
+            snapshot(&state.db, &victim).await.expect("row vanished"),
+            before,
+            "the stored row must be byte-identical after a refused announce"
+        );
+    }
+
+    /// U4 scenario 2: the allowed signed case. A caller whose keyid IS the row
+    /// repoints it. Kills a gate that refuses proven writes too.
+    #[sqlx::test]
+    async fn announce_with_matching_keyid_repoints_its_own_row(pool: PgPool) {
+        let state = test_state(pool).await;
+        let owner = Keypair::generate().did().to_string();
+        seed_peer_row(&state, &owner, OWNER_URL).await;
+
+        let resp = announce_only(state.clone())
+            .oneshot(announce_as(&owner, &announce_body(&owner, MOVED_URL)))
+            .await
+            .unwrap();
+
+        assert_eq!(resp.status(), StatusCode::OK);
+        let after = snapshot(&state.db, &owner).await.expect("row vanished");
+        assert_eq!(after.1, MOVED_URL, "a proven repoint must land");
+    }
+
+    /// U4 scenario 3: an unsigned caller cannot move an existing row, and the
+    /// refusal renders as a 403 with its reason, never as a 500 or as success.
+    #[sqlx::test]
+    async fn announce_unsigned_repoint_is_a_403_denial(pool: PgPool) {
+        let state = test_state(pool).await;
+        let victim = Keypair::generate().did().to_string();
+        let before = seed_peer_row(&state, &victim, OWNER_URL).await;
+
+        let resp = announce_only(state.clone())
+            .oneshot(unsigned_post(
+                "/api/v1/peers/announce",
+                &announce_body(&victim, HIJACK_URL),
+                "203.0.113.90:5000",
+            ))
+            .await
+            .unwrap();
+
+        let (status, code, message) = status_and_error(resp).await;
+        assert_eq!(
+            status,
+            StatusCode::FORBIDDEN,
+            "an unproven repoint is an authority refusal: {message}"
+        );
+        assert_eq!(code, "forbidden", "denial body must name the 403 class");
+        assert!(
+            message.contains("unproven announce cannot change an existing peer"),
+            "the denial must name the repoint refusal, got {message:?}"
+        );
+        assert_eq!(
+            snapshot(&state.db, &victim).await.expect("row vanished"),
+            before,
+            "the stored row must be byte-identical after a refused repoint"
+        );
+    }
+
+    /// U4 scenarios 4 and 5, the allowed unsigned class: discovery of an unseen
+    /// did:key still inserts, and an honest peer re-announcing the IDENTICAL URL
+    /// still refreshes liveness. The URL is reused byte for byte because the
+    /// comparison is exact, so a trailing slash would make this pass as a
+    /// repoint rejection instead. Kills a gate widened until it breaks
+    /// discovery or honest re-announces.
+    #[sqlx::test]
+    async fn announce_unsigned_insert_and_identical_url_reannounce_are_accepted(pool: PgPool) {
+        let state = test_state(pool).await;
+        let did = Keypair::generate().did().to_string();
+        let body = announce_body(&did, OWNER_URL);
+
+        let resp = announce_only(state.clone())
+            .oneshot(unsigned_post(
+                "/api/v1/peers/announce",
+                &body,
+                "203.0.113.91:5000",
+            ))
+            .await
+            .unwrap();
+        assert_eq!(resp.status(), StatusCode::OK, "discovery must stay open");
+        let before = snapshot(&state.db, &did).await.expect("row not inserted");
+        assert_eq!(before.1, OWNER_URL);
+        assert!(!before.3, "a never-probed peer inserts unreachable");
+
+        let resp = announce_only(state.clone())
+            .oneshot(unsigned_post(
+                "/api/v1/peers/announce",
+                &body,
+                "203.0.113.92:5000",
+            ))
+            .await
+            .unwrap();
+        assert_eq!(
+            resp.status(),
+            StatusCode::OK,
+            "an identical-URL re-announce is a liveness signal, not a repoint"
+        );
+        let after = snapshot(&state.db, &did).await.expect("row vanished");
+        assert_eq!(after.1, OWNER_URL, "URL untouched");
+        assert_eq!(after.3, before.3, "reachability untouched");
+        assert_eq!(after.4, before.4, "announced_at untouched");
+        let parse = |s: &Option<String>| {
+            chrono::DateTime::parse_from_rfc3339(s.as_deref().expect("last_seen is set")).unwrap()
+        };
+        assert!(
+            parse(&after.2) > parse(&before.2),
+            "a same-URL re-announce must advance last_seen"
+        );
+    }
+
+    /// U4 scenario 6 (R8): a DID method that can never authenticate is refused
+    /// in the 400 validation class, with nothing written. This one IS about the
+    /// input's form, not the caller's authority, which is why it is not a 403.
+    #[sqlx::test]
+    async fn announce_of_a_did_web_is_a_400_validation_failure(pool: PgPool) {
+        let state = test_state(pool).await;
+
+        let resp = announce_only(state.clone())
+            .oneshot(unsigned_post(
+                "/api/v1/peers/announce",
+                &announce_body(WEB_DID, OWNER_URL),
+                "203.0.113.93:5000",
+            ))
+            .await
+            .unwrap();
+
+        let (status, code, message) = status_and_error(resp).await;
+        assert_eq!(
+            status,
+            StatusCode::BAD_REQUEST,
+            "an unsupported DID method is a validation failure: {message}"
+        );
+        assert_eq!(code, "bad_request");
+        assert!(
+            message.contains("methodNotSupported"),
+            "the rejection must carry the methodNotSupported shape, got {message:?}"
+        );
+        assert!(
+            snapshot(&state.db, WEB_DID).await.is_none(),
+            "a rejected announce must leave no row behind"
+        );
+    }
+
+    /// The sibling of the case above, and the one it must not swallow: the
+    /// method IS did:key, so methodNotSupported would be a false statement
+    /// about the input. The value is the W3C secp256k1 did:key test vector,
+    /// which decodes cleanly and is simply not an ed25519 key. Still the 400
+    /// validation class, still nothing written.
+    #[sqlx::test]
+    async fn announce_of_an_unresolvable_did_key_is_a_400_with_the_cause(pool: PgPool) {
+        let state = test_state(pool).await;
+        let did = "did:key:zQ3shokFTS3brHcDQrn82RUDfCZESWL1ZdCEJwekUDPQiYBme";
+
+        let resp = announce_only(state.clone())
+            .oneshot(unsigned_post(
+                "/api/v1/peers/announce",
+                &announce_body(did, OWNER_URL),
+                "203.0.113.99:5000",
+            ))
+            .await
+            .unwrap();
+
+        let (status, code, message) = status_and_error(resp).await;
+        assert_eq!(
+            status,
+            StatusCode::BAD_REQUEST,
+            "an unresolvable did:key is a validation failure: {message}"
+        );
+        assert_eq!(
+            code, "unresolvable_did",
+            "the code must name the cause, the same way the signed path does for a keyid it \
+             cannot resolve; a client distinguishing this from the other 400s on this route \
+             must not have to substring-match the message: {message:?}"
+        );
+        assert!(
+            message.contains("cannot resolve DID"),
+            "the rejection must report resolution, not method support, got {message:?}"
+        );
+        assert!(
+            snapshot(&state.db, did).await.is_none(),
+            "a rejected announce must leave no row behind"
+        );
+    }
+
+    // ── U5: the same matrix through the production router, real signatures ────
+
+    /// An announce carrying a REAL RFC 9421 signature, signed AS `kp` while the
+    /// body names whatever DID the caller chooses. That split is the point: it
+    /// is what lets a valid signature be pointed at a row it does not own,
+    /// which is the RUSTSEC-2022-0009 shape.
+    fn real_signed_announce(kp: &Keypair, body: &str, peer: &str) -> Request<Body> {
+        let path = "/api/v1/peers/announce";
+        let s = sign_request(kp, "POST", path, body.as_bytes());
+        let mut req = Request::builder()
+            .method(Method::POST)
+            .uri(path)
+            .header(header::CONTENT_TYPE, "application/json")
+            .header("content-digest", s.content_digest)
+            .header("signature-input", s.signature_input)
+            .header("signature", s.signature)
+            .body(Body::from(body.to_string()))
+            .unwrap();
+        req.extensions_mut()
+            .insert(ConnectInfo(peer.parse::<SocketAddr>().unwrap()));
+        req
+    }
+
+    /// U5 scenario 1: the lowest-privilege caller there is, fully
+    /// unauthenticated, still seeds an unseen did:key row through the whole
+    /// production stack.
+    #[sqlx::test]
+    async fn router_unsigned_announce_inserts_an_unseen_did(pool: PgPool) {
+        let state = test_state(pool).await;
+        let did = Keypair::generate().did().to_string();
+        let db = state.db.clone();
+
+        let resp = crate::server::build_router(state)
+            .oneshot(unsigned_post(
+                "/api/v1/peers/announce",
+                &announce_body(&did, OWNER_URL),
+                "203.0.113.94:5000",
+            ))
+            .await
+            .unwrap();
+
+        assert_eq!(resp.status(), StatusCode::OK);
+        let row = snapshot(&db, &did).await.expect("row not inserted");
+        assert_eq!(row.1, OWNER_URL);
+    }
+
+    /// U5 scenario 2: the defect this change closes, driven end to end. An
+    /// unsigned repoint is refused with its reason and the row does not move.
+    /// Kills reverting the unproven arm to an unconditional DO UPDATE.
+    #[sqlx::test]
+    async fn router_unsigned_announce_cannot_repoint_an_existing_row(pool: PgPool) {
+        let state = test_state(pool).await;
+        let victim = Keypair::generate().did().to_string();
+        let before = seed_peer_row(&state, &victim, OWNER_URL).await;
+        let db = state.db.clone();
+
+        let resp = crate::server::build_router(state)
+            .oneshot(unsigned_post(
+                "/api/v1/peers/announce",
+                &announce_body(&victim, HIJACK_URL),
+                "203.0.113.95:5000",
+            ))
+            .await
+            .unwrap();
+
+        // The row assertion leads: the property is that the row does not move.
+        // A response-class regression is a second, separate failure below.
+        let (status, code, message) = status_and_error(resp).await;
+        assert_eq!(
+            snapshot(&db, &victim).await.expect("row vanished"),
+            before,
+            "the stored row must be byte-identical after a refused unsigned repoint \
+             (observed status {status})"
+        );
+        assert_eq!(status, StatusCode::FORBIDDEN, "observed body: {message}");
+        assert_eq!(code, "forbidden");
+    }
+
+    /// U5 scenario 3: the allowed signed case through the real verification
+    /// middleware. The row was seeded under this keypair's own did:key, so the
+    /// signature names the row it moves.
+    #[sqlx::test]
+    async fn router_signature_from_the_rows_own_did_repoints_it(pool: PgPool) {
+        let state = test_state(pool).await;
+        let owner = Keypair::generate();
+        let owner_did = owner.did().to_string();
+        seed_peer_row(&state, &owner_did, OWNER_URL).await;
+        let db = state.db.clone();
+
+        let resp = crate::server::build_router(state)
+            .oneshot(real_signed_announce(
+                &owner,
+                &announce_body(&owner_did, MOVED_URL),
+                "203.0.113.96:5000",
+            ))
+            .await
+            .unwrap();
+
+        assert_eq!(
+            resp.status(),
+            StatusCode::OK,
+            "a real signature from the row's own DID must be admitted"
+        );
+        let row = snapshot(&db, &owner_did).await.expect("row vanished");
+        assert_eq!(row.1, MOVED_URL, "a proven repoint must land");
+        assert!(
+            !row.3,
+            "a repointed peer must re-earn reachability even when the repoint is signed"
+        );
+    }
+
+    /// U5 scenario 4, the RUSTSEC-2022-0009 shape: a signature that verifies
+    /// perfectly, spent on a row it does not own. The key must be bound to the
+    /// ROW, not to anything the request carries. The assertion names the keyid
+    /// denial specifically, because the boundary's own DID comparison would
+    /// also refuse this write, so a status-only assertion would stay green with
+    /// the handler branch neutralized.
+    #[sqlx::test]
+    async fn router_signature_from_another_did_cannot_repoint_this_row(pool: PgPool) {
+        let state = test_state(pool).await;
+        let victim = Keypair::generate().did().to_string();
+        let hijacker = Keypair::generate();
+        let before = seed_peer_row(&state, &victim, OWNER_URL).await;
+        let db = state.db.clone();
+
+        let resp = crate::server::build_router(state)
+            .oneshot(real_signed_announce(
+                &hijacker,
+                &announce_body(&victim, HIJACK_URL),
+                "203.0.113.97:5000",
+            ))
+            .await
+            .unwrap();
+
+        let (status, code, message) = status_and_error(resp).await;
+        assert_eq!(
+            status,
+            StatusCode::FORBIDDEN,
+            "a valid signature over another DID's row must be refused: {message}"
+        );
+        assert_eq!(code, "forbidden");
+        assert!(
+            message.contains(KEYID_MISMATCH),
+            "the denial must name the keyid mismatch, got {message:?}"
+        );
+        assert_eq!(
+            snapshot(&db, &victim).await.expect("row vanished"),
+            before,
+            "the stored row must be byte-identical after a mismatched signature"
+        );
+    }
+
+    /// U5 scenario 5: an honest unsigned peer re-announcing the identical URL
+    /// through the full stack refreshes last_seen and moves nothing else. The
+    /// seeded string is reused byte for byte, since the comparison is exact.
+    #[sqlx::test]
+    async fn router_unsigned_identical_url_reannounce_refreshes_last_seen(pool: PgPool) {
+        let state = test_state(pool).await;
+        let did = Keypair::generate().did().to_string();
+        let before = seed_peer_row(&state, &did, OWNER_URL).await;
+        let db = state.db.clone();
+
+        let resp = crate::server::build_router(state)
+            .oneshot(unsigned_post(
+                "/api/v1/peers/announce",
+                &announce_body(&did, OWNER_URL),
+                "203.0.113.98:5000",
+            ))
+            .await
+            .unwrap();
+
+        assert_eq!(resp.status(), StatusCode::OK);
+        let after = snapshot(&db, &did).await.expect("row vanished");
+        assert_eq!(after.1, OWNER_URL, "URL untouched");
+        assert_eq!(after.3, before.3, "reachability untouched");
+        assert_eq!(after.4, before.4, "announced_at untouched");
+        let parse = |s: &Option<String>| {
+            chrono::DateTime::parse_from_rfc3339(s.as_deref().expect("last_seen is set")).unwrap()
+        };
+        assert!(
+            parse(&after.2) > parse(&before.2),
+            "a same-URL re-announce must advance last_seen"
+        );
+    }
+
+    /// U5 scenario 6 (R8) through the full stack: a did:web announce is refused
+    /// in the validation class and writes nothing. Such a row could never be
+    /// corrected by anyone, since only a did:key can ever satisfy the proven
+    /// path. Kills neutralizing the method gate on the unproven arm.
+    #[sqlx::test]
+    async fn router_unsigned_announce_of_a_did_web_is_refused(pool: PgPool) {
+        let state = test_state(pool).await;
+        let db = state.db.clone();
+
+        let resp = crate::server::build_router(state)
+            .oneshot(unsigned_post(
+                "/api/v1/peers/announce",
+                &announce_body(WEB_DID, OWNER_URL),
+                "203.0.113.99:5000",
+            ))
+            .await
+            .unwrap();
+
+        let (status, code, message) = status_and_error(resp).await;
+        assert_eq!(
+            status,
+            StatusCode::BAD_REQUEST,
+            "an unsupported DID method must be refused: {message}"
+        );
+        assert_eq!(code, "bad_request");
+        assert!(
+            message.contains("methodNotSupported"),
+            "the rejection must carry the methodNotSupported shape, got {message:?}"
+        );
+        assert!(
+            snapshot(&db, WEB_DID).await.is_none(),
+            "a rejected announce must leave no row behind"
+        );
+    }
+
+    /// U5, flag-on mode: with require_signed_peer_writes the write group moves
+    /// under add_auth_layers, so the unsigned caller dies at the auth layer with
+    /// a 401 instead of reaching the handler's 403. The authority rules
+    /// themselves do not change: a signature over another DID's row is still
+    /// refused, and the row's own key still moves it. The flag is applied BEFORE
+    /// build_router, which reads it at build time.
+    #[sqlx::test]
+    async fn announce_authority_matrix_in_signed_writes_mode(pool: PgPool) {
+        let mut state = test_state(pool).await;
+        require_signed_peer_writes(&mut state);
+        let owner = Keypair::generate();
+        let owner_did = owner.did().to_string();
+        let hijacker = Keypair::generate();
+        let before = seed_peer_row(&state, &owner_did, OWNER_URL).await;
+        let db = state.db.clone();
+        let router = crate::server::build_router(state);
+
+        let resp = router
+            .clone()
+            .oneshot(unsigned_post(
+                "/api/v1/peers/announce",
+                &announce_body(&owner_did, HIJACK_URL),
+                "203.0.113.100:5000",
+            ))
+            .await
+            .unwrap();
+        assert_eq!(
+            resp.status(),
+            StatusCode::UNAUTHORIZED,
+            "with the flag on, an unsigned announce dies at the auth layer"
+        );
+        assert_eq!(
+            snapshot(&db, &owner_did).await.expect("row vanished"),
+            before,
+            "the row must be byte-identical after the 401"
+        );
+
+        let resp = router
+            .clone()
+            .oneshot(real_signed_announce(
+                &hijacker,
+                &announce_body(&owner_did, HIJACK_URL),
+                "203.0.113.101:5000",
+            ))
+            .await
+            .unwrap();
+        let (status, _, message) = status_and_error(resp).await;
+        assert_eq!(
+            status,
+            StatusCode::FORBIDDEN,
+            "a signature over another DID's row is still refused: {message}"
+        );
+        assert!(message.contains(KEYID_MISMATCH), "got {message:?}");
+        assert_eq!(
+            snapshot(&db, &owner_did).await.expect("row vanished"),
+            before,
+            "the row must be byte-identical after the mismatched signature"
+        );
+
+        let resp = router
+            .oneshot(real_signed_announce(
+                &owner,
+                &announce_body(&owner_did, MOVED_URL),
+                "203.0.113.102:5000",
+            ))
+            .await
+            .unwrap();
+        assert_eq!(
+            resp.status(),
+            StatusCode::OK,
+            "the row's own key still moves it with the flag on"
+        );
+        assert_eq!(
+            snapshot(&db, &owner_did).await.expect("row vanished").1,
+            MOVED_URL
+        );
+    }
 }

crates/gitlawb-node/src/api/pulls.rs

@@ -65,7 +65,6 @@ pub async fn create_pr(
         status: "open".to_string(),
         merged_by_did: None,
         merged_at: None,
-        head_commit: None,
         created_at: now.clone(),
         updated_at: now,
     };
@@ -210,26 +209,16 @@ pub async fn merge_pr(
         return Err(AppError::BadRequest(format!("PR is already {}", pr.status)));
     }
 
+    // Shed 503 + Retry-After on an exhausted write-lock POOL instead of a generic
+    // git 500 (#173 F1). Merging holds no admission permit, so it reaches the pool
+    // unthrottled; reuse the push handler's mapping so the two cannot drift.
     let guard = state
         .repo_store
         .acquire_write(&record.owner_did, &record.name)
         .await
-        .map_err(|e| AppError::Git(e.to_string()))?;
+        .map_err(|e| crate::api::repos::acquire_write_app_error(&e, &name))?;
     let disk_path = guard.path().to_path_buf();
     let merger_did = auth.0;
-
-    // The source head this merge is about to consume, read under the write lock.
-    // The PR row above was loaded before the lock, so a push landing in between
-    // already moved the branch and the row's own `head_commit` is stale; the
-    // value frozen on the merged PR has to be what was merged. `None` when the
-    // ref cannot be resolved, which leaves whatever the push path last stored.
-    let merged_source_head = store::list_refs(&disk_path).ok().and_then(|refs| {
-        let want = format!("refs/heads/{}", pr.source_branch);
-        refs.into_iter()
-            .find(|(name, _)| *name == want)
-            .map(|(_, sha)| sha)
-    });
-
     let merge_result = store::merge_branch(
         &disk_path,
         &pr.target_branch,
@@ -243,10 +232,7 @@ pub async fn merge_pr(
 
     let merge_sha = merge_result.map_err(|e| AppError::Git(e.to_string()))?;
 
-    state
-        .db
-        .merge_pr(&pr.id, &merger_did, merged_source_head.as_deref())
-        .await?;
+    state.db.merge_pr(&pr.id, &merger_did).await?;
     let _ = state.db.touch_repo(&record.id).await;
 
     webhooks::fire_event(
@@ -442,158 +428,115 @@ pub async fn list_comments(
     Ok(Json(serde_json::json!({ "comments": comments })))
 }
 
+/// #173 F1 follow-up: `merge_pr` reaches `acquire_write` holding NO admission permit
+/// (unlike the push handler, which is capped by the git-push semaphore), so it is one
+/// of the callers most likely to meet an exhausted write-lock POOL under load. An
+/// exhausted pool is a capacity signal, so the merge must shed 503 + Retry-After
+/// (`AppError::Overloaded`) the way the push handler does, not report the generic
+/// 500 git error that says nothing about retrying.
 #[cfg(test)]
-mod tests {
+mod lock_pool_shed_tests {
     use super::*;
-    use axum::body::Body;
-    use axum::http::{Method, StatusCode};
-    use axum::routing::post;
-    use axum::Router;
-    use std::process::Command;
-    use tower::ServiceExt;
-
-    const OWNER_DID: &str = "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH";
-    const STALE_SHA: &str = "9999999999999999999999999999999999999999";
-
-    fn git(dir: &std::path::Path, args: &[&str]) {
-        let out = Command::new("git")
-            .args(args)
-            .current_dir(dir)
-            .env("GIT_AUTHOR_NAME", "t")
-            .env("GIT_AUTHOR_EMAIL", "[email protected]")
-            .env("GIT_COMMITTER_NAME", "t")
-            .env("GIT_COMMITTER_EMAIL", "[email protected]")
-            .output()
-            .expect("git runs");
-        assert!(
-            out.status.success(),
-            "git {args:?} failed: {}",
-            String::from_utf8_lossy(&out.stderr)
-        );
-    }
-
-    /// A bare repo with `main` and a `feature` branch one commit ahead.
-    /// Returns the bare path and the real `feature` tip.
-    fn bare_repo_with_feature(
-        root: &std::path::Path,
-        owner_slug: &str,
-    ) -> (std::path::PathBuf, String) {
-        let work = root.join("work");
-        std::fs::create_dir_all(&work).unwrap();
-        git(&work, &["init", "-q", "-b", "main", "."]);
-        std::fs::write(work.join("a.txt"), "one").unwrap();
-        git(&work, &["add", "."]);
-        git(&work, &["commit", "-qm", "one"]);
-        git(&work, &["checkout", "-qb", "feature"]);
-        std::fs::write(work.join("b.txt"), "two").unwrap();
-        git(&work, &["add", "."]);
-        git(&work, &["commit", "-qm", "two"]);
-        git(&work, &["checkout", "-q", "main"]);
-
-        let bare_dir = root.join(owner_slug);
-        std::fs::create_dir_all(&bare_dir).unwrap();
-        let bare = bare_dir.join("demo.git");
-        git(
-            root,
-            &[
-                "clone",
-                "-q",
-                "--bare",
-                work.to_str().unwrap(),
-                bare.to_str().unwrap(),
-            ],
-        );
-
-        let tip = Command::new("git")
-            .args(["rev-parse", "refs/heads/feature"])
-            .current_dir(&bare)
-            .output()
-            .unwrap();
-        let tip = String::from_utf8_lossy(&tip.stdout).trim().to_string();
-        assert_eq!(tip.len(), 40, "feature tip must resolve");
-        (bare, tip)
-    }
-
-    /// Merging freezes the stored head at the source commit the merge actually
-    /// consumed. The PR row is loaded before the write lock is taken, so a push
-    /// that lands in between leaves the row's own `head_commit` stale; seeding a
-    /// value that matches nothing on disk stands in for that race, and the
-    /// merged PR must still come out pointing at the real `feature` tip.
-    #[sqlx::test]
-    async fn merge_stamps_the_source_head_it_merged_over_a_racing_value(pool: sqlx::PgPool) {
-        let tmp = tempfile::tempdir().unwrap();
-        let owner_slug = OWNER_DID.replace([':', '/'], "_");
-        let (bare, feature_tip) = bare_repo_with_feature(tmp.path(), &owner_slug);
-
-        let mut state = crate::test_support::test_state(pool.clone()).await;
-        state.repo_store =
-            crate::git::repo_store::RepoStore::for_testing(tmp.path().to_path_buf(), pool);
+    use axum::response::IntoResponse;
+    use sqlx::PgPool;
 
+    fn seed_repo(owner_did: &str, name: &str) -> crate::db::RepoRecord {
         let now = Utc::now();
-        let repo = crate::db::RepoRecord {
-            id: uuid::Uuid::new_v4().to_string(),
-            name: "demo".into(),
-            owner_did: OWNER_DID.into(),
+        crate::db::RepoRecord {
+            id: Uuid::new_v4().to_string(),
+            name: name.to_string(),
+            owner_did: owner_did.to_string(),
             description: None,
             is_public: true,
-            default_branch: "main".into(),
+            default_branch: "main".to_string(),
             created_at: now,
             updated_at: now,
-            disk_path: bare.to_string_lossy().into_owned(),
+            disk_path: format!("/tmp/{name}"),
             forked_from: None,
             machine_id: None,
-        };
-        state.db.create_repo(&repo).await.unwrap();
+        }
+    }
 
-        let pr = PullRequest {
-            id: Uuid::new_v4().to_string(),
-            repo_id: repo.id.clone(),
-            number: 1,
-            title: "add b".into(),
-            body: None,
-            author_did: OWNER_DID.into(),
-            source_branch: "feature".into(),
-            target_branch: "main".into(),
-            status: "open".into(),
-            merged_by_did: None,
-            merged_at: None,
-            head_commit: None,
-            created_at: now.to_rfc3339(),
-            updated_at: now.to_rfc3339(),
-        };
-        state.db.create_pr(&pr).await.unwrap();
-        // The stale value the racing push scenario leaves on the row.
+    /// RED-before/GREEN-after for `merge_pr`. Both directions: the shed while the only
+    /// lock-pool connection is held by a guard on a DIFFERENT repo (so this is pool
+    /// capacity, not advisory-lock contention on this repo), and the must-not case
+    /// once that connection is back.
+    #[sqlx::test]
+    async fn merge_pr_lock_pool_exhaustion_sheds_503_not_500(pool: PgPool) {
+        let owner = "did:key:zMERGELOCKPOOLOWNERAAAAAAAAAAAAAAAAAAAAA";
+        let mut state = crate::test_support::test_state(pool.clone()).await;
+        // One lock-pool connection with a short checkout timeout, so a single held
+        // guard exhausts it promptly rather than at the pool default.
+        state.repo_store = crate::git::repo_store::RepoStore::new(
+            std::path::PathBuf::from("/tmp/gitlawb-pulls-lockpool"),
+            None,
+            crate::git::repo_store::build_lock_pool(&pool, 1, std::time::Duration::from_secs(1)),
+        );
+
+        let repo = seed_repo(owner, "lp-merge");
+        let repo_id = repo.id.clone();
+        state.db.create_repo(&repo).await.expect("seed repo");
+        let now = Utc::now().to_rfc3339();
         state
             .db
-            .set_open_pr_heads(&repo.id, "feature", STALE_SHA)
+            .create_pr(&PullRequest {
+                id: Uuid::new_v4().to_string(),
+                repo_id: repo_id.clone(),
+                number: 1,
+                title: "lp".to_string(),
+                body: None,
+                author_did: owner.to_string(),
+                source_branch: "feature".to_string(),
+                target_branch: "main".to_string(),
+                status: "open".to_string(),
+                merged_by_did: None,
+                merged_at: None,
+                created_at: now.clone(),
+                updated_at: now,
+            })
             .await
-            .unwrap();
+            .expect("seed open PR");
 
-        let db = state.db.clone();
-        let app = Router::new()
-            .route(
-                "/api/v1/repos/{owner}/{repo}/pulls/{number}/merge",
-                post(merge_pr),
-            )
-            .with_state(state);
-
-        let response = app
-            .oneshot(crate::test_support::signed_request_as(
-                OWNER_DID,
-                Method::POST,
-                "/api/v1/repos/z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH/demo/pulls/1/merge",
-                Body::empty(),
-            ))
+        let held = state
+            .repo_store
+            .acquire_write(owner, "other-repo")
             .await
-            .unwrap();
-        assert_eq!(response.status(), StatusCode::OK);
+            .expect("the first write takes the only lock-pool connection");
 
-        let merged = db.get_pr(&repo.id, 1).await.unwrap().unwrap();
-        assert_eq!(merged.status, "merged");
+        let shed = merge_pr(
+            State(state.clone()),
+            Extension(AuthenticatedDid(owner.to_string())),
+            Path((owner.to_string(), "lp-merge".to_string(), 1)),
+        )
+        .await;
+        let err = shed.expect_err("an exhausted lock pool must fail the call");
+        let resp = err.into_response();
         assert_eq!(
-            merged.head_commit,
-            Some(feature_tip),
-            "the merge must stamp the source head it consumed, not the racing value"
+            resp.status(),
+            StatusCode::SERVICE_UNAVAILABLE,
+            "merge_pr: an exhausted write-lock pool must shed 503, not a 500 git error"
+        );
+        assert_eq!(
+            resp.headers()
+                .get("retry-after")
+                .map(|v| v.to_str().unwrap()),
+            Some("1"),
+            "merge_pr: a capacity shed must tell the client when to retry"
+        );
+
+        // MUST-NOT: with the pool free again the merge is not shed as capacity (it
+        // fails later on the nonexistent on-disk repo, which is a git 500).
+        held.release(false).await;
+        let admitted = merge_pr(
+            State(state.clone()),
+            Extension(AuthenticatedDid(owner.to_string())),
+            Path((owner.to_string(), "lp-merge".to_string(), 1)),
+        )
+        .await;
+        assert!(
+            !matches!(admitted, Err(AppError::Overloaded(_))),
+            "with the lock pool free, merge_pr must not be shed as capacity; got {:?}",
+            admitted.err()
         );
     }
 }

crates/gitlawb-node/src/api/status/mod.rs

@@ -1,657 +0,0 @@
-//! Commit status claims: the write path and the combined read.
-//!
-//! POST /api/v1/repos/:owner/:repo/statuses/:sha — append one claim (owner only)
-//! GET  /api/v1/repos/:owner/:repo/commits/:sha/status — the combined projection
-//!
-//! Claims are append-only: a producer reporting twice for the same context
-//! leaves both rows and the visible status is a projection over the history.
-//! Reporting twice means two REQUESTS, though. An exact repeat of one already
-//! accepted is answered with 200 and the row it wrote, not a second row: the
-//! projection elects the highest `seq`, so a replayed claim would not duplicate
-//! a verdict but overturn the one that superseded it.
-
-use axum::extract::{Extension, Path, State};
-use axum::http::StatusCode;
-use axum::Json;
-use chrono::Utc;
-use serde::{Deserialize, Serialize};
-use uuid::Uuid;
-
-use crate::auth::AuthenticatedDid;
-use crate::db::StatusClaim;
-use crate::error::{AppError, Result};
-use crate::state::AppState;
-
-/// Claims for one (repo, commit, producer, context). Generous for a real
-/// producer; a producer past it is misbehaving.
-const MAX_CLAIMS_PER_TUPLE: i64 = 100;
-/// Distinct contexts for one (repo, commit). The context string is caller-chosen
-/// and free-form, so the tuple cap alone bounds nothing.
-const MAX_CONTEXTS_PER_COMMIT: i64 = 50;
-/// Claim rows for one repo within the trailing window the db layer counts over.
-/// The commit SHA is caller-chosen and never existence-checked, so a writer at
-/// the two caps above can still fan out over fresh 40-hex strings without this
-/// one. It bounds the RATE of that fan-out rather than a lifetime total, because
-/// nothing prunes the table: a lifetime bound would close the surface on a repo
-/// permanently while answering with a status every client retries.
-const MAX_CLAIMS_PER_REPO_PER_WINDOW: i64 = 10_000;
-
-#[derive(Deserialize)]
-pub struct CreateStatusRequest {
-    pub state: String,
-    pub context: String,
-    pub target_url: Option<String>,
-    pub description: Option<String>,
-}
-
-/// The wire state set (KTD-1): GitHub's four commit-status states, so absence
-/// stays distinguishable without a fifth value no client understands.
-const CLAIM_STATES: [&str; 4] = ["error", "failure", "pending", "success"];
-
-/// Bounds on the signature material this write path persists verbatim. Every one
-/// of the four is caller-influenced: the headers come off the request, the
-/// signing string grows with the component list the caller's Signature-Input
-/// chose, and the body is the caller's. Without a bound the claim log's row size
-/// is set by whoever writes to it, so these are explicit and generous rather than
-/// implicit and absent. A conforming `sign_request` produces roughly 100, 200 and
-/// 400 bytes for the first three.
-const MAX_SIGNATURE_CHARS: usize = 512;
-const MAX_SIGNATURE_INPUT_CHARS: usize = 1024;
-const MAX_SIGNING_STRING_CHARS: usize = 4096;
-/// The body is a `CreateStatusRequest`, whose own fields are already capped at
-/// roughly 3.3 KB in total by the three limits below; this leaves room for JSON
-/// framing and nothing more.
-///
-/// Enforced twice, at two different moments, because the handler's check alone
-/// is not the bound it advertises: `require_signature` buffers the whole body
-/// before any handler runs, so by the time [`create_status`] measures it the
-/// allocation has already happened. `build_router` applies the same number as a
-/// `RequestBodyLimitLayer` at the transport, outside the auth layers, which is
-/// what makes it a bound on what is ALLOCATED and not only on what is STORED.
-/// The handler keeps its own check regardless — it is the one that holds for a
-/// handler reached by any other route table, and it is what the material size
-/// tests drive.
-pub(crate) const MAX_REQUEST_BODY_BYTES: usize = 8192;
-
-const MAX_CONTEXT_CHARS: usize = 255;
-const MAX_TARGET_URL_CHARS: usize = 2048;
-const MAX_DESCRIPTION_CHARS: usize = 1024;
-
-/// The 201 body for an accepted claim: what the client needs to identify the row
-/// it just wrote, and nothing else.
-///
-/// Deliberately not the stored [`StatusClaim`]. That struct carries the signature
-/// material, and serializing it echoed the signature, the signing string and the
-/// whole request body back on every write — the body as a JSON array of integers.
-/// Write-time provenance belongs in the row, not on the wire, which is the same
-/// line [`StatusEntry`] draws on the read side.
-#[derive(Serialize)]
-pub struct CreatedStatus {
-    pub id: String,
-    /// The database-assigned ordering key, so the client can name its own row.
-    pub seq: i64,
-    pub repo_id: String,
-    pub commit_sha: String,
-    pub state: String,
-    pub context: String,
-    pub target_url: Option<String>,
-    pub description: Option<String>,
-    pub producer_did: String,
-    pub created_at: String,
-}
-
-impl CreatedStatus {
-    fn from_claim(claim: StatusClaim, seq: i64) -> Self {
-        Self {
-            id: claim.id,
-            seq,
-            repo_id: claim.repo_id,
-            commit_sha: claim.commit_sha,
-            state: claim.state,
-            context: claim.context,
-            target_url: claim.target_url,
-            description: claim.description,
-            producer_did: claim.producer_did,
-            created_at: claim.created_at,
-        }
-    }
-}
-
-/// POST /api/v1/repos/:owner/:repo/statuses/:sha
-pub async fn create_status(
-    State(state): State<AppState>,
-    Extension(auth): Extension<AuthenticatedDid>,
-    Path((owner, name, sha)): Path<(String, String, String)>,
-    material: Option<Extension<crate::auth::SignatureMaterial>>,
-    Json(req): Json<CreateStatusRequest>,
-) -> Result<(StatusCode, Json<CreatedStatus>)> {
-    // Read-visibility first, then owner, and the order is the security property.
-    // authorize_repo_read denies a quarantined repo before the visibility gate and
-    // answers with the repo's own not-found, byte-identical to a missing repo, so
-    // a caller who cannot read the repo cannot learn it exists. Loading the repo
-    // and comparing the owner would answer 403 there, turning this endpoint into
-    // an existence oracle. require_repo_owner then 403s a non-owner of a repo the
-    // caller can read, where existence is not secret.
-    let (record, _rules) =
-        crate::api::authorize_repo_read(&state, &owner, &name, Some(&auth.0), "/").await?;
-    crate::api::require_repo_owner(&record, &auth.0)?;
-
-    let commit_sha = normalize_sha(&sha)?;
-    let claim_state = validate_state(&req.state)?;
-    let context = validate_context(&req.context)?;
-    let target_url = validate_target_url(req.target_url.as_deref())?;
-    let description = validate_description(req.description.as_deref())?;
-
-    // KTD-5: the signature material is captured here because the request carries
-    // the only copy, and `signing_string` is the exact byte sequence the
-    // middleware verified. Its absence means this handler was reached without
-    // `require_signature` — a server misconfiguration (a route group that lost
-    // its auth layer, a handler mounted somewhere new), not anything the client
-    // did, so it is a 500 and no row is written. Storing an empty payload instead
-    // would leave every claim from that moment on unverifiable with nothing going
-    // red, which is exactly the absence-renders-as-success shape.
-    let Some(Extension(material)) = material else {
-        return Err(AppError::Internal(anyhow::anyhow!(
-            "status claim write reached without verified signature material — \
-             the route is not behind require_signature"
-        )));
-    };
-    // The body is carried only behind the `PersistsSignedBody` marker, which
-    // this route's group applies outside the auth layers. Its absence means the
-    // marker did not reach the middleware, because the layer was dropped or
-    // reordered. That is the same class of misconfiguration as the branch above
-    // and gets the same answer. Storing an empty body instead would write claims
-    // that carry a signature over a digest of bytes nobody kept, which is
-    // exactly the case `stored_claim_re_verifies_and_a_tampered_row_does_not`
-    // exists to make impossible.
-    let Some(body) = material.body.clone() else {
-        return Err(AppError::Internal(anyhow::anyhow!(
-            "status claim write reached with signature material carrying no request body: \
-             the route lost its persist-body marker or applied it inside the auth layers"
-        )));
-    };
-    // Bounded before anything is written. The material is verified, which says
-    // the caller holds the key, not that what they signed is a reasonable size.
-    bound("signature", material.signature.len(), MAX_SIGNATURE_CHARS)?;
-    bound(
-        "signature_input",
-        material.signature_input.len(),
-        MAX_SIGNATURE_INPUT_CHARS,
-    )?;
-    bound(
-        "signing_string",
-        material.signing_string.len(),
-        MAX_SIGNING_STRING_CHARS,
-    )?;
-    bound("request body", body.len(), MAX_REQUEST_BODY_BYTES)?;
-    // After the bounds, so the scan below walks a signing string of known size.
-    require_body_bound_signature(&material, &body)?;
-
-    let digest = request_digest(&material, &body);
-    let (signature, signature_input, signing_string, request_body) = (
-        material.signature,
-        material.signature_input,
-        material.signing_string,
-        body.to_vec(),
-    );
-
-    let claim = StatusClaim {
-        id: Uuid::new_v4().to_string(),
-        // Ignored on insert: the database assigns the ordering key (KTD-3).
-        seq: 0,
-        repo_id: record.id.clone(),
-        commit_sha,
-        state: claim_state,
-        context,
-        target_url,
-        description,
-        // Both are the owner identity today (KTD-5); they split when delegated
-        // capabilities land.
-        producer_did: auth.0.clone(),
-        authorizing_did: auth.0,
-        signature,
-        signature_input,
-        signing_string,
-        request_body,
-        request_digest: digest,
-        created_at: Utc::now().to_rfc3339(),
-    };
-
-    let caps = crate::db::ClaimCaps {
-        per_tuple: MAX_CLAIMS_PER_TUPLE,
-        contexts_per_commit: MAX_CONTEXTS_PER_COMMIT,
-        per_repo_window: MAX_CLAIMS_PER_REPO_PER_WINDOW,
-    };
-    match state.db.insert_status_claim_capped(&claim, &caps).await? {
-        crate::db::ClaimInsert::Inserted(seq) => Ok((
-            StatusCode::CREATED,
-            Json(CreatedStatus::from_claim(claim, seq)),
-        )),
-        // Already recorded, so 200 and the original row rather than 201 and a
-        // second one. The claim the caller gets back is the stored one, id and
-        // seq included, which is what makes a retry safe to treat as success.
-        crate::db::ClaimInsert::AlreadyRecorded(existing) => {
-            let seq = existing.seq;
-            Ok((
-                StatusCode::OK,
-                Json(CreatedStatus::from_claim(*existing, seq)),
-            ))
-        }
-        crate::db::ClaimInsert::CapExceeded(which) => Err(AppError::TooManyRequests(format!(
-            "claim limit reached for {which}"
-        ))),
-    }
-}
-
-/// Refuse a claim whose signature does not cover the body about to be stored.
-///
-/// A claim IS provenance, so the signature stored beside it has to bind the
-/// bytes stored beside it. It does not do that directly: `signing_string`
-/// reaches the body only through a `content-digest` line. And a caller can sign
-/// a content-digest the request then never carries. `require_signature` rebuilds
-/// the covered values from the request, so an ABSENT `Content-Digest` header
-/// makes the covered digest the empty string on the signing side and the
-/// verifying side alike; the Ed25519 check passes over method, path and an empty
-/// digest, and any body at all rides along. The row that write produces asserts
-/// a provenance that cannot be re-verified: the signing string covers a digest
-/// of bytes that are not the ones in `request_body`.
-///
-/// The predicate here is the write-time form of the one `re_verify` runs against
-/// a stored row in the tests — recompute the digest of the bytes about to be
-/// persisted and require the signing string to carry exactly that line — so what
-/// this route accepts and what a third party can later re-verify are the same
-/// question, asked at both ends.
-///
-/// This is a route property, checked where the claim becomes history, and it is
-/// deliberately not the only line of defence: requiring the header in
-/// `require_signature` closes the same hole one layer earlier and for every
-/// signed route, and that change belongs there rather than here because no other
-/// route's correctness should depend on the status handler. The two agree and
-/// neither substitutes for the other — without the middleware's requirement the
-/// empty digest is still accepted everywhere else, and without this one a later
-/// relaxation of the middleware would silently resume writing unverifiable
-/// history.
-///
-/// A 400, not a 500: the material is exactly what the client signed, and what
-/// they signed does not cover what they sent.
-fn require_body_bound_signature(
-    material: &crate::auth::SignatureMaterial,
-    body: &[u8],
-) -> Result<()> {
-    let covered = format!(
-        "\"content-digest\": {}",
-        gitlawb_core::http_sig::compute_content_digest(body)
-    );
-    // Line-exact rather than a substring search: `build_signing_string` emits one
-    // component per line, and a `contains` would also be satisfied by the digest
-    // appearing INSIDE some other covered component's value, which proves
-    // nothing about what the signature covered.
-    if material.signing_string.lines().any(|line| line == covered) {
-        return Ok(());
-    }
-    Err(AppError::BadRequest(
-        "the signature does not cover this request body: send a Content-Digest header \
-         computed over the body and name \"content-digest\" among the signature's covered \
-         components"
-            .into(),
-    ))
-}
-
-/// The identity of one signed write, as a hex sha-256.
-///
-/// All four inputs together, because a replay is the same bytes arriving twice:
-/// the signature, the input that names what it covers, the canonical string it
-/// was verified over, and the body that string covers through a content-digest.
-/// The signature alone would nearly do (it covers the other three transitively),
-/// but hashing what is actually stored means the digest describes the row rather
-/// than a claim about it.
-///
-/// Each field is length-prefixed so no two different requests can concatenate to
-/// the same bytes: without it, a signature ending in some prefix of the next
-/// field would collide with the shorter signature that absorbed it.
-///
-/// This is not a nonce, and deliberately so. A nonce table needs pruning and a
-/// pruning window is a second replay window; the claim row IS the record of what
-/// was accepted, so uniqueness on it is self-maintaining.
-fn request_digest(material: &crate::auth::SignatureMaterial, body: &[u8]) -> String {
-    use sha2::{Digest, Sha256};
-    let mut h = Sha256::new();
-    for part in [
-        material.signature.as_bytes(),
-        material.signature_input.as_bytes(),
-        material.signing_string.as_bytes(),
-        body,
-    ] {
-        h.update((part.len() as u64).to_be_bytes());
-        h.update(part);
-    }
-    format!("{:x}", h.finalize())
-}
-
-/// One reported context in the combined response. Signature material is
-/// deliberately absent: it is write-time provenance, not read-surface data.
-#[derive(Serialize)]
-pub struct StatusEntry {
-    pub state: String,
-    pub context: String,
-    pub target_url: Option<String>,
-    pub description: Option<String>,
-    pub producer_did: String,
-    pub created_at: String,
-}
-
-/// The combined commit status. `state` never leaves the four-value set (KTD-1),
-/// so absence is carried by `total_count` 0 with the pending state rather than a
-/// fifth value, and `reported_only` (R19) says out loud that the state covers the
-/// contexts that reported, not every check a caller expected.
-#[derive(Serialize)]
-pub struct CombinedStatus {
-    pub state: String,
-    pub sha: String,
-    pub total_count: usize,
-    pub statuses: Vec<StatusEntry>,
-    pub reported_only: bool,
-}
-
-/// GET /api/v1/repos/:owner/:repo/commits/:sha/status
-///
-/// The auth extension is optional and MUST be last in the extractor list: the
-/// route group carries `optional_signature`, so an unsigned caller reaches here
-/// with no `AuthenticatedDid` at all and a public repo still answers.
-pub async fn commit_status(
-    State(state): State<AppState>,
-    Path((owner, name, sha)): Path<(String, String, String)>,
-    auth: Option<Extension<AuthenticatedDid>>,
-) -> Result<Json<CombinedStatus>> {
-    let caller = auth.as_ref().map(|Extension(a)| a.0.as_str());
-    // The gate runs first and on the requested path, before any claim data is
-    // touched. Its deny is the repo's own not-found, byte-identical to a missing
-    // repo, so the status surface cannot answer "does this repo exist".
-    let (record, _rules) =
-        crate::api::authorize_repo_read(&state, &owner, &name, caller, "/").await?;
-
-    let commit_sha = normalize_sha(&sha)?;
-    let statuses = project_claims(&state, &record, &commit_sha).await?;
-
-    Ok(Json(CombinedStatus {
-        state: combined_state(&statuses).to_string(),
-        sha: commit_sha,
-        total_count: statuses.len(),
-        statuses,
-        reported_only: true,
-    }))
-}
-
-/// The projection, in one place. Both read surfaces call it, so R3's "the rollup
-/// is derived by the same projection as the commit read" holds by construction
-/// rather than by two implementations happening to agree.
-///
-/// KTD-5: current authorization, not write-time authorization. An ownership
-/// transfer drops the prior owner's claims from the projection while the
-/// append-only history keeps them.
-async fn project_claims(
-    state: &AppState,
-    record: &crate::db::RepoRecord,
-    commit_sha: &str,
-) -> Result<Vec<StatusEntry>> {
-    let claims = state
-        .db
-        .latest_status_claims(&record.id, commit_sha, &record.owner_did)
-        .await?;
-    Ok(claims
-        .into_iter()
-        .map(|c| StatusEntry {
-            state: c.state,
-            context: c.context,
-            target_url: c.target_url,
-            description: c.description,
-            producer_did: c.producer_did,
-            created_at: c.created_at,
-        })
-        .collect())
-}
-
-/// The pull request head rollup (R11). `state` stays inside the four wire values
-/// whatever happened to the head (KTD-1): an unresolvable head is carried by
-/// `head_resolved`, alongside the pull request's own state, so a client can tell
-/// "the head could not be resolved" from "the head resolved and nothing reported"
-/// without a fifth state value no client understands.
-#[derive(Serialize)]
-pub struct PullRequestStatus {
-    pub number: i64,
-    /// The pull request's own state: open, closed, or merged.
-    pub pull_request_state: String,
-    pub head_resolved: bool,
-    /// The target commit, absent exactly when `head_resolved` is false.
-    pub sha: Option<String>,
-    pub state: String,
-    pub total_count: usize,
-    pub statuses: Vec<StatusEntry>,
-    pub reported_only: bool,
-}
-
-/// GET /api/v1/repos/:owner/:repo/pulls/:number/status
-///
-/// Same optional-auth shape as the commit read, and the auth extension MUST stay
-/// last in the extractor list.
-pub async fn pull_request_status(
-    State(state): State<AppState>,
-    Path((owner, name, number)): Path<(String, String, i64)>,
-    auth: Option<Extension<AuthenticatedDid>>,
-) -> Result<Json<PullRequestStatus>> {
-    let caller = auth.as_ref().map(|Extension(a)| a.0.as_str());
-    // The gate runs first, on the requested path, before the pull request row is
-    // loaded. Its deny is the repo's own not-found, byte-identical to a missing
-    // repo. Once it passes, a missing pull request number is the plain not-found:
-    // existence is no longer secret.
-    let (record, _rules) =
-        crate::api::authorize_repo_read(&state, &owner, &name, caller, "/").await?;
-
-    let pr = state
-        .db
-        .get_pr(&record.id, number)
-        .await?
-        .ok_or_else(|| AppError::NotFound(format!("PR #{number} not found")))?;
-
-    let head = rollup_head(&state, &record, &pr).await?;
-
-    let statuses = match &head {
-        Some(sha) => project_claims(&state, &record, sha).await?,
-        None => Vec::new(),
-    };
-
-    Ok(Json(PullRequestStatus {
-        number: pr.number,
-        pull_request_state: pr.status,
-        head_resolved: head.is_some(),
-        sha: head,
-        state: combined_state(&statuses).to_string(),
-        total_count: statuses.len(),
-        statuses,
-        reported_only: true,
-    }))
-}
-
-/// Branch-head lookups performed by the rollup fallback, counted so a test can
-/// assert WORK DONE rather than only the answer returned. A fallback that
-/// re-resolved on every read and then discarded the answer would be invisible in
-/// the response and visible here.
-#[cfg(test)]
-pub(crate) static BRANCH_RESOLVES: std::sync::atomic::AtomicUsize =
-    std::sync::atomic::AtomicUsize::new(0);
-
-/// The rollup's target commit (KTD-4).
-///
-/// The stored head wins whenever it is set. It is frozen at close or merge, so a
-/// closed or merged pull request keeps the commit the decision was made against,
-/// and only an OPEN pull request with no stored head falls back to the branch.
-///
-/// The fallback is one database read: the latest push this node recorded for the
-/// pull request's source branch, from `repo_push_events`. It deliberately does
-/// NOT go through `git::store` ref listing, which needs an acquired repository
-/// path — on a cold node that downloads the whole repository from object storage,
-/// and this read group carries no rate limiter, so an anonymous caller could
-/// drive repeated downloads with a URL.
-///
-/// `repo_push_events` is the source rather than `branch_cids` because
-/// `record_push_events` writes it for every ref update unconditionally, whereas
-/// the sole writer of `branch_cids` sits behind a pin CID. A node with no object
-/// pinning configured never writes that table, so a resolve keyed on it could
-/// never answer there and every open pull request without a stored head reported
-/// `head_resolved: false` forever. The residual limit is that only pushes taken
-/// after this shipped have rows, so a branch last pushed before then still does
-/// not resolve.
-///
-/// The resolved head is persisted, which makes an unauthenticated GET write. That
-/// is only acceptable because the write is self-limiting: it fires exactly when
-/// `head_commit` is absent and it fills it, and the fill is conditioned on that
-/// same absence in SQL, so the PERSIST happens at most once per pull request.
-/// The resolve attempt itself is not once-only — a pull request whose branch does
-/// not resolve stores nothing, so there is nothing to short-circuit on and the
-/// lookup runs again on every read until it succeeds.
-async fn rollup_head(
-    state: &AppState,
-    record: &crate::db::RepoRecord,
-    pr: &crate::db::PullRequest,
-) -> Result<Option<String>> {
-    if let Some(stored) = pr.head_commit.clone() {
-        return Ok(Some(stored));
-    }
-    if pr.status != "open" {
-        return Ok(None);
-    }
-
-    // The push path records the full ref while a pull request stores the bare
-    // branch name, the same mismatch `crate::api::repos::branch_from_ref`
-    // reconciles on the write side; this is that mapping run backwards. The empty
-    // branch is excluded for the same reason it is there: `refs/heads/` is not a
-    // branch and nothing can have written it.
-    if pr.source_branch.is_empty() {
-        return Ok(None);
-    }
-    let ref_name = format!("refs/heads/{}", pr.source_branch);
-    #[cfg(test)]
-    BRANCH_RESOLVES.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
-    let resolved = state
-        .db
-        .latest_push_sha_for_ref(&record.id, &ref_name)
-        .await?
-        // A recorded head that is not a commit SHA is no target at all, and
-        // storing it would leave the rollup pointing at nothing forever.
-        .and_then(|sha| normalize_sha(&sha).ok());
-
-    let Some(sha) = resolved else {
-        return Ok(None);
-    };
-    // Best effort, and deliberately not `?`. The head is already resolved and the
-    // response does not depend on this write landing, so a transient database
-    // failure here must not turn a served read into a 500; the next read resolves
-    // again and re-attempts the fill. Same catch-and-log the sibling writes on the
-    // push path use (`update_open_pr_heads`, `record_push_events`).
-    if let Err(e) = state.db.set_pr_head_if_absent(&pr.id, &sha).await {
-        tracing::warn!(
-            err = %e,
-            pr_id = %pr.id,
-            "failed to persist a resolved pull request head; serving the resolved head anyway"
-        );
-    }
-    Ok(Some(sha))
-}
-
-/// KTD-1's fold: any error or failure yields failure, else any pending yields
-/// pending, else success. An empty set is pending, never success — total absence
-/// of a verdict is its own state and must not read as a pass (R10).
-fn combined_state(statuses: &[StatusEntry]) -> &'static str {
-    if statuses.is_empty() {
-        return "pending";
-    }
-    if statuses
-        .iter()
-        .any(|s| s.state == "error" || s.state == "failure")
-    {
-        "failure"
-    } else if statuses.iter().any(|s| s.state == "pending") {
-        "pending"
-    } else {
-        "success"
-    }
-}
-
-/// 40 hex characters, lowercased. The SHA is never existence-checked (KTD-7):
-/// a claim describes a commit object, and the object may not have arrived yet.
-fn normalize_sha(sha: &str) -> Result<String> {
-    if sha.len() == 40 && sha.bytes().all(|b| b.is_ascii_hexdigit()) {
-        Ok(sha.to_ascii_lowercase())
-    } else {
-        Err(AppError::BadRequest(
-            "commit sha must be exactly 40 hexadecimal characters".into(),
-        ))
-    }
-}
-
-/// One size bound on persisted signature material, measured in bytes.
-fn bound(what: &str, len: usize, max: usize) -> Result<()> {
-    if len > max {
-        return Err(AppError::BadRequest(format!(
-            "{what} must be at most {max} bytes"
-        )));
-    }
-    Ok(())
-}
-
-fn validate_state(state: &str) -> Result<String> {
-    if CLAIM_STATES.contains(&state) {
-        Ok(state.to_string())
-    } else {
-        Err(AppError::BadRequest(format!(
-            "state must be one of {}",
-            CLAIM_STATES.join(", ")
-        )))
-    }
-}
-
-/// The context is the projection key, so it is trimmed, bounded, and required to
-/// be free of control characters.
-fn validate_context(context: &str) -> Result<String> {
-    let trimmed = context.trim();
-    if trimmed.is_empty() || trimmed.chars().count() > MAX_CONTEXT_CHARS {
-        return Err(AppError::BadRequest(format!(
-            "context must be 1 to {MAX_CONTEXT_CHARS} characters"
-        )));
-    }
-    if trimmed.chars().any(char::is_control) {
-        return Err(AppError::BadRequest(
-            "context must not contain control characters".into(),
-        ));
-    }
-    Ok(trimmed.to_string())
-}
-
-fn validate_target_url(url: Option<&str>) -> Result<Option<String>> {
-    let Some(url) = url else { return Ok(None) };
-    if url.chars().count() > MAX_TARGET_URL_CHARS {
-        return Err(AppError::BadRequest(format!(
-            "target_url must be at most {MAX_TARGET_URL_CHARS} characters"
-        )));
-    }
-    let lower = url.to_ascii_lowercase();
-    if lower.starts_with("http://") || lower.starts_with("https://") {
-        Ok(Some(url.to_string()))
-    } else {
-        Err(AppError::BadRequest(
-            "target_url must be an http or https URL".into(),
-        ))
-    }
-}
-
-fn validate_description(description: Option<&str>) -> Result<Option<String>> {
-    match description {
-        Some(d) if d.chars().count() > MAX_DESCRIPTION_CHARS => Err(AppError::BadRequest(format!(
-            "description must be at most {MAX_DESCRIPTION_CHARS} characters"
-        ))),
-        other => Ok(other.map(str::to_string)),
-    }
-}
-
-#[cfg(test)]
-mod tests;

crates/gitlawb-node/src/auth/mod.rs

@@ -17,53 +17,6 @@ use crate::state::AppState;
 #[derive(Clone, Debug)]
 pub struct AuthenticatedDid(pub String);
 
-/// The RFC 9421 material this request was actually verified against, injected
-/// alongside [`AuthenticatedDid`] by `require_signature`.
-///
-/// A handler that records a signed claim as history has to store it: the header
-/// values and the canonical signing string are gone once the request ends, and a
-/// stored claim nobody can re-verify is not history. `signing_string` is the exact
-/// byte sequence the Ed25519 verification succeeded over, not a rebuild — a
-/// handler reconstructing it from headers would be verifying a different string
-/// than the middleware did.
-#[derive(Clone, Debug)]
-pub struct SignatureMaterial {
-    /// The `Signature` header value.
-    pub signature: String,
-    /// The `Signature-Input` header value.
-    pub signature_input: String,
-    /// The canonical bytes the signature covered.
-    pub signing_string: String,
-    /// The buffered request body, on the routes that persist it. The signing
-    /// string covers it only through the content-digest, so without these bytes
-    /// a stored claim can be shown to carry *a* valid signature over *some*
-    /// digest and nothing more. Carried here because the body is consumed
-    /// downstream by the extractor and cannot be recovered afterwards.
-    ///
-    /// `Option`, and populated only behind [`PersistsSignedBody`], because a
-    /// route that never stores the body has no use for a second handle to it.
-    /// The unlike-sized field is this one: the three above are header-derived
-    /// and bounded by the server's header limit, while a receive-pack POST
-    /// carries up to GITLAWB_MAX_PACK_BYTES (2 GB by default). `Bytes`, not
-    /// `Vec<u8>`, so the handle the marked routes do take is a refcount bump
-    /// over the buffer the middleware already holds rather than a copy.
-    pub body: Option<axum::body::Bytes>,
-}
-
-/// Marks a route group whose handler persists the signed request body.
-///
-/// Applied as an extension layer OUTSIDE the auth layers, so it is on the
-/// request before [`require_signature`] decides whether to carry the body. A
-/// marker applied inside them is never seen, and the failure is silent: the
-/// handler still compiles, tests that inject material by hand still pass, and
-/// production stores nothing. The status write handler refuses an absent body
-/// for that reason.
-///
-/// A marker rather than a path check because `require_signature` must not learn
-/// which URL persists claims; that knowledge belongs at the route table.
-#[derive(Clone, Copy, Debug)]
-pub struct PersistsSignedBody;
-
 /// Whether `caller` is authorized to push to `record`.
 ///
 /// Phase 1 (`GITLAWB_ENFORCE_OWNER_PUSH`): owner-only, via the canonical
@@ -285,28 +238,10 @@ pub async fn require_signature(request: Request, next: Next) -> Response {
 
     tracing::info!(did = %sig.key_id, "✓ authenticated request");
 
-    // The body travels only where it is stored. On every other signed route the
-    // middleware's handle would keep the buffer alive for the rest of the layer
-    // chain, until the handler's own extractor consumes the request.
-    let body = parts
-        .extensions
-        .get::<PersistsSignedBody>()
-        .map(|_| body_bytes.clone());
-
-    let material = SignatureMaterial {
-        signature: sig_header,
-        signature_input: sig_input,
-        signing_string,
-        body,
-    };
-
     let mut request = Request::from_parts(parts, Body::from(body_bytes));
     request
         .extensions_mut()
         .insert(AuthenticatedDid(sig.key_id.to_string()));
-    // Carry the verified material forward for handlers that persist a signed
-    // claim; none of it can be recovered once the request is gone.
-    request.extensions_mut().insert(material);
     next.run(request).await
 }
 
@@ -581,107 +516,33 @@ mod tests {
             rate_limiter: RateLimiter::new(100, Duration::from_secs(60)),
             create_ip_rate_limiter: RateLimiter::new(1000, Duration::from_secs(3600)),
             push_rate_limiter: RateLimiter::new(600, Duration::from_secs(3600)),
+            ipfs_rate_limiter: RateLimiter::new(600, Duration::from_secs(3600)),
+            ipfs_work_rate_limiter: RateLimiter::new(600, Duration::from_secs(3600)),
+            ipfs_max_history_walks: crate::api::ipfs::MAX_HISTORY_WALKS_PER_REQUEST,
+            ipfs_max_legacy_probes: crate::api::ipfs::MAX_LEGACY_PROBES_PER_REQUEST,
+            ipfs_max_served_object_bytes: crate::api::ipfs::MAX_SERVED_OBJECT_BYTES,
             push_limiter_trust: crate::rate_limit::TrustedProxy::None,
             sync_trigger_rate_limiter: RateLimiter::new(60, Duration::from_secs(3600)),
             peer_write_rate_limiter: RateLimiter::new(600, Duration::from_secs(3600)),
             shutdown_tx: tokio::sync::watch::channel(false).0,
+            git_read_semaphore: Arc::new(tokio::sync::Semaphore::new(64)),
+            git_write_semaphore: Arc::new(tokio::sync::Semaphore::new(64)),
+            git_push_advert_semaphore: Arc::new(tokio::sync::Semaphore::new(64)),
+            git_encrypt_semaphore: Arc::new(tokio::sync::Semaphore::new(64)),
+            pin_semaphore: Arc::new(tokio::sync::Semaphore::new(64)),
+            encrypt_inflight: crate::state::EncryptInflight::new(),
+            repo_write_leases: crate::state::RepoWriteLeases::new(8),
+            git_read_per_caller: crate::rate_limit::PerCallerConcurrency::with_default_max_keys(16),
+            git_push_advert_per_caller:
+                crate::rate_limit::PerCallerConcurrency::with_default_max_keys(8),
+            git_write_per_caller: crate::rate_limit::PerCallerConcurrency::with_default_max_keys(8),
+            git_ipfs_walk_semaphore: Arc::new(tokio::sync::Semaphore::new(64)),
+            git_ipfs_walk_per_caller:
+                crate::rate_limit::PerCallerConcurrency::with_default_max_keys(16),
+            git_bin: "git".to_string(),
         }
     }
 
-    /// Reports what the signature middleware put in `SignatureMaterial.body`,
-    /// so a test can tell "captured" from "deliberately not captured" apart
-    /// from "the middleware never ran".
-    async fn report_body(material: Option<axum::Extension<SignatureMaterial>>) -> String {
-        match material {
-            Some(axum::Extension(m)) => match m.body {
-                Some(bytes) => format!("captured:{}", bytes.len()),
-                None => "absent".to_string(),
-            },
-            None => "no-material".to_string(),
-        }
-    }
-
-    fn signed_post(path: &str, body: &[u8]) -> Request {
-        let kp = Keypair::generate();
-        let signed = gitlawb_core::http_sig::sign_request(&kp, "POST", path, body);
-        Request::builder()
-            .method("POST")
-            .uri(path)
-            .header("content-digest", signed.content_digest)
-            .header("signature-input", signed.signature_input)
-            .header("signature", signed.signature)
-            .body(axum::body::Body::from(body.to_vec()))
-            .unwrap()
-    }
-
-    /// The body handle travels only on a route that asked for it.
-    ///
-    /// Both arms drive a genuinely signed request through `require_signature`;
-    /// the only difference is the [`PersistsSignedBody`] marker layer. A
-    /// middleware that captured unconditionally would make both arms read
-    /// `captured`, and one that never read the marker would make both read
-    /// `absent`, so the pair pins the decision rather than the mechanism.
-    #[tokio::test]
-    async fn the_body_is_carried_only_when_the_route_marks_itself_as_persisting_it() {
-        let body = br#"{"state":"success"}"#;
-
-        // The marker layer is added AFTER the middleware layer, which is what
-        // makes it the outer of the two and therefore the one that runs first.
-        // This is the same relative position `build_router` uses on the status
-        // write group, where the marker sits outside `add_auth_layers`.
-        let marked = Router::new()
-            .route("/", axum::routing::post(report_body))
-            .layer(middleware::from_fn(require_signature))
-            .layer(axum::Extension(PersistsSignedBody));
-        let resp = marked.oneshot(signed_post("/", body)).await.unwrap();
-        assert_eq!(resp.status(), StatusCode::OK);
-        let seen = axum::body::to_bytes(resp.into_body(), 2048).await.unwrap();
-        assert_eq!(
-            String::from_utf8(seen.to_vec()).unwrap(),
-            format!("captured:{}", body.len()),
-            "a route carrying the persist marker must receive the buffered body"
-        );
-
-        let unmarked = Router::new()
-            .route("/", axum::routing::post(report_body))
-            .layer(middleware::from_fn(require_signature));
-        let resp = unmarked.oneshot(signed_post("/", body)).await.unwrap();
-        assert_eq!(resp.status(), StatusCode::OK);
-        let seen = axum::body::to_bytes(resp.into_body(), 2048).await.unwrap();
-        assert_eq!(
-            String::from_utf8(seen.to_vec()).unwrap(),
-            "absent",
-            "a signed route that never persists the body must not be handed a handle to it"
-        );
-    }
-
-    /// The marker is read from the request the middleware was given, and the
-    /// request it hands downstream still carries it. Both halves matter: the
-    /// first is the capture decision, the second is that rebuilding the request
-    /// from its parts does not drop extensions a later layer may want.
-    #[tokio::test]
-    async fn the_marker_survives_the_request_rebuild() {
-        async fn report_marker(marker: Option<axum::Extension<PersistsSignedBody>>) -> String {
-            match marker {
-                Some(_) => "marked".to_string(),
-                None => "unmarked".to_string(),
-            }
-        }
-
-        let app = Router::new()
-            .route("/", axum::routing::post(report_marker))
-            .layer(middleware::from_fn(require_signature))
-            .layer(axum::Extension(PersistsSignedBody));
-        let resp = app.oneshot(signed_post("/", b"{}")).await.unwrap();
-        assert_eq!(resp.status(), StatusCode::OK);
-        let seen = axum::body::to_bytes(resp.into_body(), 2048).await.unwrap();
-        assert_eq!(
-            String::from_utf8(seen.to_vec()).unwrap(),
-            "marked",
-            "the marker must reach the handler, so the middleware saw it too"
-        );
-    }
-
     #[tokio::test]
     async fn require_ucan_chain_no_header_passes_through() {
         let state = make_test_state(Keypair::generate().did());

crates/gitlawb-node/src/encrypted_pin.rs

@@ -170,7 +170,7 @@ pub async fn encrypt_and_pin(
                 continue;
             }
         };
-        let cid = match crate::ipfs_pin::pin_git_object(ipfs_api, oid, &envelope).await {
+        let cid = match crate::ipfs_pin::pin_git_object(ipfs_api, oid, &envelope, None).await {
             Ok(c) if !c.is_empty() => c,
             Ok(_) => {
                 tracing::warn!(oid = %oid, "pin_git_object returned no cid; skipping");

crates/gitlawb-node/src/error.rs

@@ -35,18 +35,33 @@ pub enum AppError {
     #[error("invalid request: {0}")]
     BadRequest(String),
 
+    /// A DID was well-formed enough to carry to a resolver but no verifying key
+    /// could be derived from it. Its own code rather than plain `bad_request`
+    /// because the auth middleware already answers `unresolvable_did` for the
+    /// same failure on a request's keyid, and a client should not have to
+    /// substring-match a message to tell this apart from the other validation
+    /// failures on the same route.
+    #[error("unresolvable did: {0}")]
+    UnresolvableDid(String),
+
     #[error("too many requests: {0}")]
     TooManyRequests(String),
 
     #[error("incomplete: {0}")]
     Incomplete(String),
 
+    #[error("search incomplete: {0}")]
+    SearchIncomplete(String),
+
     #[error("git error: {0}")]
     Git(String),
 
     #[error("git service timed out: {0}")]
     Timeout(String),
 
+    #[error("server overloaded: {0}")]
+    Overloaded(String),
+
     #[error("database error: {0}")]
     Db(#[from] sqlx::Error),
 
@@ -60,6 +75,14 @@ pub enum AppError {
 pub const DB_UNAVAILABLE_CODE: &str = "db_unavailable";
 pub const DB_UNAVAILABLE_MESSAGE: &str = "database is temporarily unavailable";
 
+/// Generic client-facing message for `AppError::Internal`. The real error is
+/// logged server-side; never put sqlx/anyhow detail in the HTTP body (#226).
+pub const INTERNAL_ERROR_MESSAGE: &str = "an internal error occurred";
+
+/// Generic client-facing message for non-unavailable `AppError::Db`. Query /
+/// schema errors stay in logs; the HTTP body must not leak them (#226).
+pub const DB_ERROR_MESSAGE: &str = "a database error occurred";
+
 /// Connection-level sqlx failures that mean the database is unreachable right
 /// now (retryable, 503), as opposed to server-reported query errors.
 fn db_unavailable(e: &sqlx::Error) -> bool {
@@ -132,12 +155,24 @@ impl IntoResponse for AppError {
             // IcaptchaProofRequired is handled above (it carries extra headers/fields).
             AppError::IcaptchaProofRequired { .. } => unreachable!("handled before this match"),
             AppError::BadRequest(msg) => (StatusCode::BAD_REQUEST, "bad_request", msg.clone()),
+            AppError::UnresolvableDid(msg) => {
+                (StatusCode::BAD_REQUEST, "unresolvable_did", msg.clone())
+            }
             AppError::TooManyRequests(msg) => {
                 (StatusCode::TOO_MANY_REQUESTS, "rate_limited", msg.clone())
             }
             AppError::Incomplete(msg) => {
                 (StatusCode::UNPROCESSABLE_ENTITY, "incomplete", msg.clone())
             }
+            // A bounded search that could not complete (the CID resolver hit its
+            // legacy-probe or walk ceiling), distinct from the 404 that asserts a
+            // definitive not-found: absence was NOT proven, so the caller should
+            // retry rather than treat it as gone (#173, F2). 503, retryable.
+            AppError::SearchIncomplete(msg) => (
+                StatusCode::SERVICE_UNAVAILABLE,
+                "search_incomplete",
+                msg.clone(),
+            ),
             AppError::Git(msg) => (StatusCode::INTERNAL_SERVER_ERROR, "git_error", msg.clone()),
             // 504, distinct from the 500 git_error and from the read-gate's 404 /
             // the auth 401, so the client can tell a deadline from a failure.
@@ -147,12 +182,35 @@ impl IntoResponse for AppError {
                 DB_UNAVAILABLE_CODE,
                 DB_UNAVAILABLE_MESSAGE.into(),
             ),
-            AppError::Db(e) => (StatusCode::INTERNAL_SERVER_ERROR, "db_error", e.to_string()),
-            AppError::Internal(e) => (
-                StatusCode::INTERNAL_SERVER_ERROR,
-                "internal_error",
-                e.to_string(),
-            ),
+            // 503 with a Retry-After (attached after this match — the shared tail
+            // can't carry per-variant headers). This is the single place Overloaded
+            // becomes a response, so it can never ship a 503 without the retry hint.
+            AppError::Overloaded(msg) => {
+                (StatusCode::SERVICE_UNAVAILABLE, "overloaded", msg.clone())
+            }
+            // Opaque body + server log: bare `?` on sqlx paths becomes `AppError::Db`
+            // via `From`, so this arm (not `Internal`) is the common leak for open
+            // routes like GET /api/v1/repos and GET /api/v1/peers (#226).
+            AppError::Db(e) => {
+                tracing::error!(error = %e, "database error");
+                (
+                    StatusCode::INTERNAL_SERVER_ERROR,
+                    "db_error",
+                    DB_ERROR_MESSAGE.into(),
+                )
+            }
+            // Opaque body: handlers that map with `.map_err(AppError::Internal)`
+            // (e.g. GET /ipfs/{cid}) land here; other DB failures usually hit `Db`.
+            // Log `{e:#}` so context-wrapped anyhow chains keep the leaf cause
+            // (Display alone is only the outermost layer; see api/repos.rs).
+            AppError::Internal(e) => {
+                tracing::error!(error = %format!("{e:#}"), "internal error");
+                (
+                    StatusCode::INTERNAL_SERVER_ERROR,
+                    "internal_error",
+                    INTERNAL_ERROR_MESSAGE.into(),
+                )
+            }
         };
 
         let body = Json(json!({
@@ -160,7 +218,21 @@ impl IntoResponse for AppError {
             "message": message,
         }));
 
-        (status, body).into_response()
+        let mut resp = (status, body).into_response();
+        // Both retryable 503s advertise when to retry: Overloaded (capacity shed) and
+        // SearchIncomplete (a bounded CID search cut short by a cap — retry may complete
+        // it). They ride the shared tail above for body/status, so the header is attached
+        // here rather than in bespoke early returns, keeping each variant handled once.
+        if matches!(
+            self,
+            AppError::Overloaded(_) | AppError::SearchIncomplete(_)
+        ) {
+            resp.headers_mut().insert(
+                axum::http::header::RETRY_AFTER,
+                axum::http::HeaderValue::from_static("1"),
+            );
+        }
+        resp
     }
 }
 
@@ -182,4 +254,93 @@ mod tests {
             StatusCode::INTERNAL_SERVER_ERROR
         );
     }
+
+    #[test]
+    fn overloaded_maps_to_503_with_retry_after() {
+        let resp = AppError::Overloaded("x".into()).into_response();
+        assert_eq!(resp.status(), StatusCode::SERVICE_UNAVAILABLE);
+        assert_eq!(
+            resp.headers().get("retry-after").unwrap().to_str().unwrap(),
+            "1"
+        );
+    }
+
+    /// #226: raw sqlx/DB detail must never appear in the Internal 500 body.
+    #[tokio::test]
+    async fn internal_error_body_is_opaque() {
+        use serde_json::{json, Value};
+
+        let leak = "error returned from database: relation \"repos\" does not exist";
+        let resp = AppError::Internal(anyhow::anyhow!("{leak}")).into_response();
+        assert_eq!(resp.status(), StatusCode::INTERNAL_SERVER_ERROR);
+
+        let bytes = axum::body::to_bytes(resp.into_body(), usize::MAX)
+            .await
+            .expect("read body");
+        let v: Value = serde_json::from_slice(&bytes).expect("json body");
+        // Exact object: a new `detail` field with different sensitive text must
+        // also fail, not only a repeat of the original error string.
+        assert_eq!(
+            v,
+            json!({
+                "error": "internal_error",
+                "message": INTERNAL_ERROR_MESSAGE,
+            })
+        );
+    }
+
+    /// #226: `AppError::Db` query errors (the common `?` path) must also be opaque.
+    #[tokio::test]
+    async fn db_error_body_is_opaque() {
+        use serde_json::{json, Value};
+
+        let resp = AppError::Db(sqlx::Error::Protocol(
+            "error returned from database: column \"is_public\" does not exist".into(),
+        ))
+        .into_response();
+        assert_eq!(resp.status(), StatusCode::INTERNAL_SERVER_ERROR);
+
+        let bytes = axum::body::to_bytes(resp.into_body(), usize::MAX)
+            .await
+            .expect("read body");
+        let v: Value = serde_json::from_slice(&bytes).expect("json body");
+        assert_eq!(
+            v,
+            json!({
+                "error": "db_error",
+                "message": DB_ERROR_MESSAGE,
+            })
+        );
+    }
+
+    /// Connection-level failures must stay 503 `db_unavailable`, not collapse
+    /// into the opaque 500 `db_error` arm if `db_unavailable` loses a variant.
+    #[tokio::test]
+    async fn db_pool_timeout_stays_503_unavailable() {
+        use serde_json::{json, Value};
+
+        let resp = AppError::Db(sqlx::Error::PoolTimedOut).into_response();
+        assert_eq!(resp.status(), StatusCode::SERVICE_UNAVAILABLE);
+
+        let bytes = axum::body::to_bytes(resp.into_body(), usize::MAX)
+            .await
+            .expect("read body");
+        let v: Value = serde_json::from_slice(&bytes).expect("json body");
+        assert_eq!(
+            v,
+            json!({
+                "error": DB_UNAVAILABLE_CODE,
+                "message": DB_UNAVAILABLE_MESSAGE,
+            })
+        );
+    }
+
+    /// #251: bare `?` on anyhow-wrapped sqlx relies on this downcast so a
+    /// closed pool becomes 503 `db_unavailable`, not 500 `internal_error`.
+    #[test]
+    fn pool_closed_via_anyhow_from_is_503_db_unavailable() {
+        let err: AppError = anyhow::Error::from(sqlx::Error::PoolClosed).into();
+        let resp = err.into_response();
+        assert_eq!(resp.status(), StatusCode::SERVICE_UNAVAILABLE);
+    }
 }

crates/gitlawb-node/src/git/push_delta.rs

@@ -29,9 +29,9 @@
 
 use std::collections::HashSet;
 use std::path::{Path, PathBuf};
-use std::process::Command;
+use std::time::{Duration, Instant};
 
-use anyhow::{bail, Context, Result};
+use anyhow::Result;
 
 /// Env var that forces the push path to always full-scan, bypassing the delta
 /// optimization (KTD7 kill-switch). Reuses the already-tested fallback branch
@@ -64,11 +64,21 @@ pub enum PinCandidates {
 /// Fail-closed: any condition where the introduced set cannot be safely
 /// determined returns [`PinCandidates::FullScanRequired`] rather than a partial
 /// set, so the caller full-scans instead of silently under-pinning.
-pub fn resolve_push_delta(repo_path: &Path, new_tips: &[&str], old_tips: &[&str]) -> PinCandidates {
-    // KTD7 kill-switch: force the (already-tested) full-scan fallback. The env
-    // read is split out from the pure logic so the resolver stays unit-testable
-    // without touching process-global state.
-    resolve_push_delta_inner(repo_path, new_tips, old_tips, force_full_scan())
+pub fn resolve_push_delta(
+    repo_path: &Path,
+    new_tips: &[&str],
+    old_tips: &[&str],
+    git_bin: &str,
+    deadline: Instant,
+) -> PinCandidates {
+    resolve_push_delta_inner(
+        repo_path,
+        new_tips,
+        old_tips,
+        force_full_scan(),
+        git_bin,
+        deadline,
+    )
 }
 
 /// Whether the force-full-scan kill-switch env var is set.
@@ -83,6 +93,8 @@ fn resolve_push_delta_inner(
     new_tips: &[&str],
     old_tips: &[&str],
     force_full_scan: bool,
+    git_bin: &str,
+    deadline: Instant,
 ) -> PinCandidates {
     if force_full_scan {
         tracing::debug!("{FORCE_FULL_SCAN_ENV} set — forcing full scan");
@@ -102,7 +114,7 @@ fn resolve_push_delta_inner(
     // commit). Bare `cat-file -t` returns `tag` for an annotated tag, and
     // `for-each-ref %(*objecttype)` peels only one level — neither is correct.
     for tip in new_tips {
-        match peeled_object_type(repo_path, tip) {
+        match peeled_object_type(repo_path, tip, git_bin, deadline) {
             Some(t) if t == "commit" => {}
             other => {
                 tracing::debug!(
@@ -115,7 +127,7 @@ fn resolve_push_delta_inner(
         }
     }
 
-    match rev_list_delta(repo_path, new_tips, old_tips) {
+    match rev_list_delta(repo_path, new_tips, old_tips, git_bin, deadline) {
         Ok(oids) => PinCandidates::Delta(oids),
         Err(e) => {
             tracing::debug!(err = %e, "push-delta rev-list failed — forcing full scan");
@@ -126,41 +138,43 @@ fn resolve_push_delta_inner(
 
 /// Return the fully-peeled object type of `sha` (e.g. `commit`, `tree`,
 /// `blob`), or `None` if the object is missing/unpeelable or git errored.
-fn peeled_object_type(repo_path: &Path, sha: &str) -> Option<String> {
-    let output = Command::new("git")
-        .args(["cat-file", "-t", &format!("{sha}^{{}}")])
-        .current_dir(repo_path)
-        .output()
-        .ok()?;
-    if !output.status.success() {
-        return None;
-    }
-    Some(String::from_utf8_lossy(&output.stdout).trim().to_string())
+fn peeled_object_type(
+    repo_path: &Path,
+    sha: &str,
+    git_bin: &str,
+    deadline: Instant,
+) -> Option<String> {
+    let peel = format!("{sha}^{{}}");
+    let out = crate::git::visibility_pack::run_bounded_git(
+        git_bin,
+        &["cat-file", "-t", &peel],
+        repo_path,
+        b"",
+        deadline,
+    )
+    .ok()?;
+    Some(String::from_utf8_lossy(&out).trim().to_string())
 }
 
 /// Run `git rev-list --objects --no-object-names <new> --not <old>` and return
 /// the bare OID set. Decides on `status.success()` *before* parsing stdout, so
 /// a walk that prints a valid prefix then errors mid-walk is discarded.
-fn rev_list_delta(repo_path: &Path, new_tips: &[&str], old_tips: &[&str]) -> Result<Vec<String>> {
+fn rev_list_delta(
+    repo_path: &Path,
+    new_tips: &[&str],
+    old_tips: &[&str],
+    git_bin: &str,
+    deadline: Instant,
+) -> Result<Vec<String>> {
     let mut args: Vec<&str> = vec!["rev-list", "--objects", "--no-object-names"];
     args.extend_from_slice(new_tips);
     if !old_tips.is_empty() {
         args.push("--not");
         args.extend_from_slice(old_tips);
     }
-
-    let output = Command::new("git")
-        .args(&args)
-        .current_dir(repo_path)
-        .output()
-        .context("failed to run git rev-list for push delta")?;
-
-    if !output.status.success() {
-        let stderr = String::from_utf8_lossy(&output.stderr);
-        bail!("git rev-list failed: {stderr}");
-    }
-
-    let stdout = String::from_utf8_lossy(&output.stdout);
+    let out =
+        crate::git::visibility_pack::run_bounded_git(git_bin, &args, repo_path, b"", deadline)?;
+    let stdout = String::from_utf8_lossy(&out);
     Ok(stdout
         .lines()
         .map(|l| l.trim().to_string())
@@ -175,23 +189,19 @@ fn rev_list_delta(repo_path: &Path, new_tips: &[&str], old_tips: &[&str]) -> Res
 /// reconciliation sweep relies on. It returns *all* objects (including
 /// unreachable/dangling ones), which is what the sweep needs to catch
 /// stragglers — do not swap it for a reachability walk.
-pub fn list_all_objects(repo_path: &Path) -> Result<Vec<String>> {
-    let output = Command::new("git")
-        .args([
+pub fn list_all_objects(repo_path: &Path, git_bin: &str, deadline: Instant) -> Result<Vec<String>> {
+    let out = crate::git::visibility_pack::run_bounded_git(
+        git_bin,
+        &[
             "cat-file",
             "--batch-all-objects",
             "--batch-check=%(objectname)",
-        ])
-        .current_dir(repo_path)
-        .output()
-        .context("failed to run git cat-file")?;
-
-    if !output.status.success() {
-        let stderr = String::from_utf8_lossy(&output.stderr);
-        bail!("git cat-file failed: {stderr}");
-    }
-
-    let stdout = String::from_utf8_lossy(&output.stdout);
+        ],
+        repo_path,
+        b"",
+        deadline,
+    )?;
+    let stdout = String::from_utf8_lossy(&out);
     Ok(stdout
         .lines()
         .map(|l| l.trim().to_string())
@@ -203,23 +213,23 @@ pub fn list_all_objects(repo_path: &Path) -> Result<Vec<String>> {
 /// `--batch-check='%(objectname) %(objecttype)'`. The pin path's fail-closed
 /// filter needs to tell blobs (content, withholdable) from commits/trees
 /// (structural, never withheld) without typing the candidate list itself.
-pub fn list_all_objects_with_type(repo_path: &Path) -> Result<Vec<(String, String)>> {
-    let output = Command::new("git")
-        .args([
+pub fn list_all_objects_with_type(
+    repo_path: &Path,
+    git_bin: &str,
+    deadline: Instant,
+) -> Result<Vec<(String, String)>> {
+    let out = crate::git::visibility_pack::run_bounded_git(
+        git_bin,
+        &[
             "cat-file",
             "--batch-all-objects",
             "--batch-check=%(objectname) %(objecttype)",
-        ])
-        .current_dir(repo_path)
-        .output()
-        .context("failed to run git cat-file")?;
-
-    if !output.status.success() {
-        let stderr = String::from_utf8_lossy(&output.stderr);
-        bail!("git cat-file failed: {stderr}");
-    }
-
-    let stdout = String::from_utf8_lossy(&output.stdout);
+        ],
+        repo_path,
+        b"",
+        deadline,
+    )?;
+    let stdout = String::from_utf8_lossy(&out);
     Ok(stdout
         .lines()
         .filter_map(|l| {
@@ -235,8 +245,12 @@ pub fn list_all_objects_with_type(repo_path: &Path) -> Result<Vec<(String, Strin
 /// fail-closed pin filter drops any candidate blob absent from the reachable,
 /// visibility-allowed set; a dangling private blob is in this set but not the
 /// allowed set, so it never replicates (#99).
-pub fn all_blob_oids(repo_path: &Path) -> Result<HashSet<String>> {
-    Ok(list_all_objects_with_type(repo_path)?
+pub fn all_blob_oids(
+    repo_path: &Path,
+    git_bin: &str,
+    deadline: Instant,
+) -> Result<HashSet<String>> {
+    Ok(list_all_objects_with_type(repo_path, git_bin, deadline)?
         .into_iter()
         .filter(|(_, ty)| ty == "blob")
         .map(|(oid, _)| oid)
@@ -268,22 +282,68 @@ pub struct PinCandidateSet {
 /// it can never leak because the withheld/fail-closed filter still runs on
 /// whatever set is returned. `full_scan` rides on the returned set so the caller
 /// knows when the dangling-inclusive filter is required.
+///
+/// `scan_sem` is the post-receive scan admission pool (`git_encrypt_semaphore`,
+/// #174 F4): both git-spawning stages — the per-tip `cat-file` probe + delta
+/// rev-list, and the full-scan fallback — run under ONE permit held for the
+/// whole blocking scan. The deletion-only fast path (no new tips) spawns no git
+/// and never parks.
+///
+/// `force_full_scan` forces the full-scan fallback regardless of the tips — the
+/// coalesced-drain `PendingWork::FullScan` marker (#174 F5). It composes with
+/// the env kill-switch (either forces), and it disqualifies the empty-tips fast
+/// path: a forced-scan call with no tips must still enumerate the repo, never
+/// silently resolve to an empty delta (which would pin nothing and lose the
+/// drained pushes' work — the F5 bug shape).
 pub async fn resolve_candidates_for_push(
+    scan_sem: std::sync::Arc<tokio::sync::Semaphore>,
     repo_path: PathBuf,
     new_tips: Vec<String>,
     old_tips: Vec<String>,
+    git_bin: String,
+    timeout: Duration,
+    force_full_scan: bool,
 ) -> PinCandidateSet {
+    let force = force_full_scan || self::force_full_scan();
+    // No-git fast path: a deletion-only push resolves to an empty delta without
+    // spawning any git child, so it must not park on the scan pool. A forced
+    // full scan (caller flag or kill-switch) disqualifies it — the scan spawns git.
+    if new_tips.is_empty() && !force {
+        tracing::info!(delta = 0usize, repo = %repo_path.display(), "pin candidate set from push delta");
+        return PinCandidateSet {
+            candidates: Vec::new(),
+            full_scan: false,
+        };
+    }
+    // Scan admission (#174 F4): DEFER, never shed — a dropped scan would
+    // silently under-pin this push. The permit moves into the blocking closure
+    // so a started scan always completes holding it. Residuals at
+    // `acquire_scan_permit`.
+    let permit =
+        crate::state::acquire_scan_permit(scan_sem, &repo_path, "pin-candidate scan").await;
     tokio::task::spawn_blocking(move || {
+        let _permit = permit;
+        // ONE shared deadline for the whole scan, per jatmn ("the same deadline").
+        let deadline = Instant::now() + timeout;
         let new_refs: Vec<&str> = new_tips.iter().map(String::as_str).collect();
         let old_refs: Vec<&str> = old_tips.iter().map(String::as_str).collect();
-        match resolve_push_delta(&repo_path, &new_refs, &old_refs) {
+        // `force` already folds in the env kill-switch, so the forced arm skips the
+        // delta machinery outright; the unforced arm goes through the normal
+        // resolver (whose own env read is false here by construction).
+        let resolved = if force {
+            tracing::debug!("full scan forced (coalesced-drain marker or kill-switch)");
+            PinCandidates::FullScanRequired
+        } else {
+            resolve_push_delta(&repo_path, &new_refs, &old_refs, &git_bin, deadline)
+        };
+        match resolved {
             PinCandidates::Delta(objs) => {
                 tracing::info!(delta = objs.len(), repo = %repo_path.display(), "pin candidate set from push delta");
                 PinCandidateSet { candidates: objs, full_scan: false }
             }
             PinCandidates::FullScanRequired => {
                 tracing::warn!(repo = %repo_path.display(), "pin delta unavailable (non-commit tip, git error, or force-full-scan) — full-scan fallback");
-                match list_all_objects(&repo_path) {
+                match list_all_objects(&repo_path, &git_bin, deadline) {
                     Ok(objs) => PinCandidateSet { candidates: objs, full_scan: true },
                     Err(e) => {
                         tracing::warn!(repo = %repo_path.display(), err = %e, "full-scan fallback failed; pinning nothing this push (reconciliation sweep backstops)");
@@ -304,8 +364,13 @@ pub async fn resolve_candidates_for_push(
 mod tests {
     use super::*;
     use std::collections::HashSet;
+    use std::process::Command;
     use tempfile::TempDir;
 
+    fn td() -> std::time::Instant {
+        std::time::Instant::now() + std::time::Duration::from_secs(600)
+    }
+
     /// Minimal git helper for building test repos.
     struct Repo {
         _td: TempDir,
@@ -363,9 +428,10 @@ mod tests {
         let repo = Repo::new();
         let c1 = repo.commit_file("a.txt", "one\n");
         let c2 = repo.commit_file("b.txt", "two\n");
-        let got: HashSet<String> = delta(resolve_push_delta(&repo.path, &[&c2], &[&c1]))
-            .into_iter()
-            .collect();
+        let got: HashSet<String> =
+            delta(resolve_push_delta(&repo.path, &[&c2], &[&c1], "git", td()))
+                .into_iter()
+                .collect();
         // The new blob b.txt and commit c2 are in the delta; the old blob a.txt
         // and commit c1 are not.
         let new_blob = repo.rev("HEAD:b.txt");
@@ -383,7 +449,7 @@ mod tests {
         // genuinely new objects, never fewer.
         let repo = Repo::new();
         let c1 = repo.commit_file("a.txt", "one\n");
-        let got: HashSet<String> = delta(resolve_push_delta(&repo.path, &[&c1], &[]))
+        let got: HashSet<String> = delta(resolve_push_delta(&repo.path, &[&c1], &[], "git", td()))
             .into_iter()
             .collect();
         assert!(got.contains(&c1));
@@ -399,9 +465,15 @@ mod tests {
         // Rewrite history: reset to base, commit a different file.
         repo.git(&["reset", "-q", "--hard", &base]);
         let new_tip = repo.commit_file("c.txt", "three\n");
-        let got: HashSet<String> = delta(resolve_push_delta(&repo.path, &[&new_tip], &[&old_tip]))
-            .into_iter()
-            .collect();
+        let got: HashSet<String> = delta(resolve_push_delta(
+            &repo.path,
+            &[&new_tip],
+            &[&old_tip],
+            "git",
+            td(),
+        ))
+        .into_iter()
+        .collect();
         assert!(got.contains(&new_tip), "new tip in delta");
         assert!(got.contains(&repo.rev(&format!("{new_tip}:c.txt"))));
         // No error; force-push computes new-minus-old cleanly.
@@ -413,7 +485,7 @@ mod tests {
         repo.commit_file("a.txt", "one\n");
         // All updates were deletions => new_tips empty after the caller strips zeros.
         assert_eq!(
-            resolve_push_delta(&repo.path, &[], &[ZERO]),
+            resolve_push_delta(&repo.path, &[], &[ZERO], "git", td()),
             PinCandidates::Delta(Vec::new())
         );
     }
@@ -424,7 +496,7 @@ mod tests {
         repo.commit_file("a.txt", "one\n");
         let blob = repo.rev("HEAD:a.txt");
         assert_eq!(
-            resolve_push_delta(&repo.path, &[&blob], &[]),
+            resolve_push_delta(&repo.path, &[&blob], &[], "git", td()),
             PinCandidates::FullScanRequired,
             "a blob tip must force full scan (rev-list would exit 0 and walk it)"
         );
@@ -436,7 +508,7 @@ mod tests {
         repo.commit_file("a.txt", "one\n");
         let tree = repo.rev("HEAD^{tree}");
         assert_eq!(
-            resolve_push_delta(&repo.path, &[&tree], &[]),
+            resolve_push_delta(&repo.path, &[&tree], &[], "git", td()),
             PinCandidates::FullScanRequired
         );
     }
@@ -449,7 +521,7 @@ mod tests {
         repo.git(&["tag", "-a", "treetag", "-m", "x", &tree]);
         let tag = repo.rev("treetag");
         assert_eq!(
-            resolve_push_delta(&repo.path, &[&tag], &[]),
+            resolve_push_delta(&repo.path, &[&tag], &[], "git", td()),
             PinCandidates::FullScanRequired,
             "annotated tag peeling to a tree must force full scan"
         );
@@ -465,7 +537,7 @@ mod tests {
         repo.git(&["tag", "-a", "t2", "-m", "x", &t1]);
         let t2 = repo.rev("t2");
         assert_eq!(
-            resolve_push_delta(&repo.path, &[&t2], &[]),
+            resolve_push_delta(&repo.path, &[&t2], &[], "git", td()),
             PinCandidates::FullScanRequired
         );
     }
@@ -480,7 +552,7 @@ mod tests {
         let c1 = repo.commit_file("a.txt", "one\n");
         repo.git(&["tag", "-a", "rel", "-m", "release", &c1]);
         let tag = repo.rev("rel");
-        let got: HashSet<String> = delta(resolve_push_delta(&repo.path, &[&tag], &[]))
+        let got: HashSet<String> = delta(resolve_push_delta(&repo.path, &[&tag], &[], "git", td()))
             .into_iter()
             .collect();
         assert!(
@@ -501,7 +573,7 @@ mod tests {
         let t1 = repo.rev("t1");
         repo.git(&["tag", "-a", "t2", "-m", "x", &t1]);
         let t2 = repo.rev("t2");
-        let got: HashSet<String> = delta(resolve_push_delta(&repo.path, &[&t2], &[]))
+        let got: HashSet<String> = delta(resolve_push_delta(&repo.path, &[&t2], &[], "git", td()))
             .into_iter()
             .collect();
         assert!(
@@ -516,9 +588,16 @@ mod tests {
         let repo = Repo::new();
         let c1 = repo.commit_file("a.txt", "one\n");
         let c2 = repo.commit_file("b.txt", "two\n");
-        let set =
-            resolve_candidates_for_push(repo.path.clone(), vec![c2.clone()], vec![c1.clone()])
-                .await;
+        let set = resolve_candidates_for_push(
+            std::sync::Arc::new(tokio::sync::Semaphore::new(64)),
+            repo.path.clone(),
+            vec![c2.clone()],
+            vec![c1.clone()],
+            "git".to_string(),
+            std::time::Duration::from_secs(600),
+            false,
+        )
+        .await;
         assert!(!set.full_scan, "happy-path delta is not a full scan");
         let got: HashSet<String> = set.candidates.into_iter().collect();
         let new_blob = repo.rev("HEAD:b.txt");
@@ -536,20 +615,206 @@ mod tests {
         let repo = Repo::new();
         repo.commit_file("a.txt", "one\n");
         let blob = repo.rev("HEAD:a.txt");
-        let all: HashSet<String> = list_all_objects(&repo.path).unwrap().into_iter().collect();
-        let set = resolve_candidates_for_push(repo.path.clone(), vec![blob], vec![]).await;
+        let all: HashSet<String> = list_all_objects(&repo.path, "git", td())
+            .unwrap()
+            .into_iter()
+            .collect();
+        let set = resolve_candidates_for_push(
+            std::sync::Arc::new(tokio::sync::Semaphore::new(64)),
+            repo.path.clone(),
+            vec![blob],
+            vec![],
+            "git".to_string(),
+            std::time::Duration::from_secs(600),
+            false,
+        )
+        .await;
         assert!(set.full_scan, "non-commit tip is signalled as a full scan");
         let got: HashSet<String> = set.candidates.into_iter().collect();
         assert_eq!(got, all, "non-commit tip falls back to full repo scan");
     }
 
+    /// F4 defer proof 2: `resolve_candidates_for_push`'s git stages (the per-tip
+    /// cat-file type probe + delta rev-list, and the full-scan fallback) run under a
+    /// scan-admission permit: with a zero-permit pool the call parks and spawns no
+    /// git; once a permit is available the SAME call runs (defer, not shed). On
+    /// ungated code the git runs regardless of the pool (RED).
+    #[cfg(unix)]
+    #[tokio::test]
+    async fn resolve_candidates_defers_when_scan_pool_exhausted() {
+        use std::os::unix::fs::PermissionsExt;
+        use std::sync::Arc;
+        use std::time::Duration;
+        use tokio::sync::Semaphore;
+
+        let dir = tempfile::TempDir::new().unwrap();
+        let marker = dir.path().join("git.ran");
+        // Fake git records ANY invocation; cat-file reports a commit tip so the
+        // delta stage proceeds, rev-list yields an empty delta.
+        let fake = dir.path().join("fakegit");
+        std::fs::write(
+            &fake,
+            format!(
+                "#!/bin/sh\necho ran >> \"{}\"\ncase \"$1\" in\n  cat-file) echo commit ;;\n  *) : ;;\nesac\nexit 0\n",
+                marker.display()
+            ),
+        )
+        .unwrap();
+        let mut perm = std::fs::metadata(&fake).unwrap().permissions();
+        perm.set_mode(0o755);
+        std::fs::set_permissions(&fake, perm).unwrap();
+        let git_bin = fake.to_str().unwrap().to_string();
+        let tip = "deadbeefdeadbeefdeadbeefdeadbeefdeadbeef".to_string();
+
+        let sem: Arc<Semaphore> = Arc::new(Semaphore::new(0));
+        let blocked = tokio::time::timeout(
+            Duration::from_millis(500),
+            resolve_candidates_for_push(
+                sem.clone(),
+                dir.path().to_path_buf(),
+                vec![tip.clone()],
+                vec![],
+                git_bin.clone(),
+                Duration::from_secs(5),
+                false,
+            ),
+        )
+        .await;
+        assert!(
+            blocked.is_err(),
+            "the pin-candidate scan must defer (park on admission) when the pool is exhausted"
+        );
+        assert!(
+            !marker.exists(),
+            "the scan's git must not spawn while its admission permit is unavailable (F4)"
+        );
+
+        // Release admission: the SAME scan now runs (defer, not shed).
+        sem.add_permits(1);
+        let set = resolve_candidates_for_push(
+            sem,
+            dir.path().to_path_buf(),
+            vec![tip],
+            vec![],
+            git_bin,
+            Duration::from_secs(5),
+            false,
+        )
+        .await;
+        assert!(
+            marker.exists(),
+            "once admission is available the deferred scan runs its git"
+        );
+        assert!(!set.full_scan, "commit tip + empty rev-list is a delta");
+        assert!(set.candidates.is_empty());
+    }
+
+    /// F4 fast-path negative arm: a deletion-only push (no new tips, kill-switch
+    /// off) computes its empty delta without spawning ANY git child, so it must
+    /// complete without acquiring from the scan pool — even at zero permits. The
+    /// per-tip cat-file probe means every push with a non-empty new tip DOES spawn
+    /// git, so this is the only genuinely git-free stage.
+    #[cfg(unix)]
+    #[tokio::test]
+    async fn resolve_candidates_no_git_fast_path_skips_admission() {
+        use std::os::unix::fs::PermissionsExt;
+        use std::sync::Arc;
+        use std::time::Duration;
+        use tokio::sync::Semaphore;
+
+        let dir = tempfile::TempDir::new().unwrap();
+        let marker = dir.path().join("git.ran");
+        let fake = dir.path().join("fakegit");
+        std::fs::write(
+            &fake,
+            format!("#!/bin/sh\necho ran >> \"{}\"\nexit 0\n", marker.display()),
+        )
+        .unwrap();
+        let mut perm = std::fs::metadata(&fake).unwrap().permissions();
+        perm.set_mode(0o755);
+        std::fs::set_permissions(&fake, perm).unwrap();
+
+        let set = tokio::time::timeout(
+            Duration::from_millis(500),
+            resolve_candidates_for_push(
+                Arc::new(Semaphore::new(0)),
+                dir.path().to_path_buf(),
+                vec![],
+                vec!["deadbeefdeadbeefdeadbeefdeadbeefdeadbeef".to_string()],
+                fake.to_str().unwrap().to_string(),
+                Duration::from_secs(5),
+                false,
+            ),
+        )
+        .await
+        .expect("the no-new-tips fast path must not park on the scan pool");
+        assert_eq!(
+            set,
+            PinCandidateSet {
+                candidates: Vec::new(),
+                full_scan: false
+            }
+        );
+        assert!(!marker.exists(), "the fast path must spawn no git at all");
+    }
+
+    /// #174 F5: the coalesced-drain FullScan marker is signalled via the explicit
+    /// `force_full_scan` flag, and a flagged call with NO tips must still enumerate
+    /// the whole repo (full_scan=true, non-empty candidates). The RED arm of the
+    /// encoding question: if the marker were encoded as a plain empty-tips call
+    /// (flag off — the fast path), the drain would resolve to an empty delta and
+    /// pin nothing, silently losing the coalesced pushes' work.
+    #[tokio::test]
+    async fn forced_full_scan_with_no_tips_enumerates_the_repo() {
+        let repo = Repo::new();
+        repo.commit_file("a.txt", "one\n");
+        let all: HashSet<String> = list_all_objects(&repo.path, "git", td())
+            .unwrap()
+            .into_iter()
+            .collect();
+        assert!(!all.is_empty(), "fixture repo has objects");
+
+        let set = resolve_candidates_for_push(
+            std::sync::Arc::new(tokio::sync::Semaphore::new(64)),
+            repo.path.clone(),
+            vec![],
+            vec![],
+            "git".to_string(),
+            std::time::Duration::from_secs(600),
+            true,
+        )
+        .await;
+        assert!(set.full_scan, "the forced call is signalled as a full scan");
+        let got: HashSet<String> = set.candidates.into_iter().collect();
+        assert_eq!(
+            got, all,
+            "a forced full scan with no tips enumerates the repo — never an empty delta"
+        );
+
+        // The discriminator: the SAME empty-tips call without the flag is the
+        // deletion-only fast path (empty delta, pin nothing). The two must differ,
+        // or the marker encoding has collapsed into the silent-loss shape.
+        let unforced = resolve_candidates_for_push(
+            std::sync::Arc::new(tokio::sync::Semaphore::new(64)),
+            repo.path.clone(),
+            vec![],
+            vec![],
+            "git".to_string(),
+            std::time::Duration::from_secs(600),
+            false,
+        )
+        .await;
+        assert!(!unforced.full_scan);
+        assert!(unforced.candidates.is_empty());
+    }
+
     #[test]
     fn missing_oid_tip_forces_full_scan() {
         let repo = Repo::new();
         repo.commit_file("a.txt", "one\n");
         let bogus = "deadbeefdeadbeefdeadbeefdeadbeefdeadbeef";
         assert_eq!(
-            resolve_push_delta(&repo.path, &[bogus], &[]),
+            resolve_push_delta(&repo.path, &[bogus], &[], "git", td()),
             PinCandidates::FullScanRequired,
             "a missing/corrupt tip OID must force full scan"
         );
@@ -564,7 +829,7 @@ mod tests {
         let c1 = repo.commit_file("a.txt", "one\n");
         let c2 = repo.commit_file("b.txt", "two\n");
         let old_tree = repo.rev(&format!("{c1}^{{tree}}"));
-        let result = resolve_push_delta(&repo.path, &[&c2], &[&old_tree]);
+        let result = resolve_push_delta(&repo.path, &[&c2], &[&old_tree], "git", td());
         match result {
             PinCandidates::FullScanRequired => {} // safe: caller full-scans
             PinCandidates::Delta(objs) => {
@@ -583,10 +848,15 @@ mod tests {
         // branch2 from base advances independently
         repo.git(&["checkout", "-q", "-b", "branch2", &base]);
         let b2 = repo.commit_file("c.txt", "three\n");
-        let got: HashSet<String> =
-            delta(resolve_push_delta(&repo.path, &[&b1, &b2], &[&base, &base]))
-                .into_iter()
-                .collect();
+        let got: HashSet<String> = delta(resolve_push_delta(
+            &repo.path,
+            &[&b1, &b2],
+            &[&base, &base],
+            "git",
+            td(),
+        ))
+        .into_iter()
+        .collect();
         assert!(got.contains(&b1), "branch1 new commit");
         assert!(got.contains(&b2), "branch2 new commit");
     }
@@ -595,7 +865,7 @@ mod tests {
     fn empty_repo_no_tips_yields_empty_delta() {
         let repo = Repo::new();
         assert_eq!(
-            resolve_push_delta(&repo.path, &[], &[]),
+            resolve_push_delta(&repo.path, &[], &[], "git", td()),
             PinCandidates::Delta(Vec::new())
         );
     }
@@ -609,12 +879,12 @@ mod tests {
         let repo = Repo::new();
         let c1 = repo.commit_file("a.txt", "one\n");
         assert_eq!(
-            resolve_push_delta_inner(&repo.path, &[&c1], &[], true),
+            resolve_push_delta_inner(&repo.path, &[&c1], &[], true, "git", td()),
             PinCandidates::FullScanRequired
         );
         // And with the flag off, the same push yields a Delta.
         assert!(matches!(
-            resolve_push_delta_inner(&repo.path, &[&c1], &[], false),
+            resolve_push_delta_inner(&repo.path, &[&c1], &[], false, "git", td()),
             PinCandidates::Delta(_)
         ));
     }
@@ -624,7 +894,7 @@ mod tests {
         let repo = Repo::new();
         repo.commit_file("a.txt", "one\n");
         repo.commit_file("b.txt", "two\n");
-        let all = list_all_objects(&repo.path).unwrap();
+        let all = list_all_objects(&repo.path, "git", td()).unwrap();
         // 2 commits + 2 trees + 2 blobs = 6 objects.
         assert_eq!(all.len(), 6, "got: {all:?}");
     }
@@ -642,7 +912,7 @@ mod tests {
         std::fs::write(repo.path.join("orphan.bin"), b"dangling\n").unwrap();
         let dangling = repo.git(&["hash-object", "-w", "orphan.bin"]);
 
-        let blobs = all_blob_oids(&repo.path).unwrap();
+        let blobs = all_blob_oids(&repo.path, "git", td()).unwrap();
         assert!(blobs.contains(&reachable_blob), "reachable blob present");
         assert!(
             blobs.contains(&dangling),
@@ -652,7 +922,7 @@ mod tests {
         assert!(!blobs.contains(&tree), "tree is not a blob");
 
         // The typed lister tags each object; spot-check the dangling blob's type.
-        let typed = list_all_objects_with_type(&repo.path).unwrap();
+        let typed = list_all_objects_with_type(&repo.path, "git", td()).unwrap();
         assert!(
             typed
                 .iter()
@@ -660,4 +930,96 @@ mod tests {
             "dangling object is typed as a blob"
         );
     }
+
+    #[cfg(unix)]
+    #[test]
+    fn list_all_objects_times_out_on_a_hung_git_instead_of_blocking() {
+        use std::os::unix::fs::PermissionsExt;
+        use std::time::{Duration, Instant};
+        let dir = tempfile::TempDir::new().unwrap();
+        // Fake git: hang on cat-file (bounded to 30s so a broken test can't wedge).
+        let fake = dir.path().join("fakegit");
+        std::fs::write(
+            &fake,
+            "#!/bin/sh\ncase \"$1\" in\n  cat-file) i=0; while [ $i -lt 30 ]; do sleep 1; i=$((i+1)); done ;;\n  *) : ;;\nesac\n",
+        )
+        .unwrap();
+        let mut perm = std::fs::metadata(&fake).unwrap().permissions();
+        perm.set_mode(0o755);
+        std::fs::set_permissions(&fake, perm).unwrap();
+        let git_bin = fake.to_str().unwrap().to_string();
+
+        let (tx, rx) = std::sync::mpsc::channel();
+        let path = dir.path().to_path_buf();
+        std::thread::spawn(move || {
+            let _ = tx.send(list_all_objects(
+                &path,
+                &git_bin,
+                Instant::now() + Duration::from_millis(150),
+            ));
+        });
+        let res = rx.recv_timeout(Duration::from_secs(10)).expect(
+            "list_all_objects must return within the watchdog budget, not block on a hung git",
+        );
+        assert!(
+            res.is_err(),
+            "a hung git must make list_all_objects error out, not hang"
+        );
+    }
+
+    /// #174 finding 2: the DELTA-path children — `peeled_object_type` (cat-file),
+    /// `rev_list_delta` (rev-list) — and `list_all_objects_with_type` (cat-file) are
+    /// the remaining candidate-discovery execs (the common push path). Each must
+    /// return within the watchdog budget on a hung git rather than block and pin the
+    /// write permit. Revert any one to a bare `Command::output()` and its arm blocks
+    /// past the recv budget (RED).
+    #[cfg(unix)]
+    #[test]
+    fn delta_path_exec_fns_time_out_on_a_hung_git() {
+        use std::os::unix::fs::PermissionsExt;
+        use std::time::{Duration, Instant};
+        let dir = tempfile::TempDir::new().unwrap();
+        // Fake git hangs on BOTH cat-file and rev-list (bounded 30s so a broken
+        // test can't leak a permanent orphan or wedge the suite).
+        let fake = dir.path().join("fakegit");
+        std::fs::write(
+            &fake,
+            "#!/bin/sh\ncase \"$1\" in\n  cat-file|rev-list) i=0; while [ $i -lt 30 ]; do sleep 1; i=$((i+1)); done ;;\n  *) : ;;\nesac\n",
+        )
+        .unwrap();
+        let mut perm = std::fs::metadata(&fake).unwrap().permissions();
+        perm.set_mode(0o755);
+        std::fs::set_permissions(&fake, perm).unwrap();
+        let git_bin = fake.to_str().unwrap().to_string();
+        let path = dir.path().to_path_buf();
+
+        // Run `f` on a thread and require it to RETURN (not block) within 10s.
+        fn returns_within<T: Send + 'static>(f: impl FnOnce() -> T + Send + 'static) -> T {
+            let (tx, rx) = std::sync::mpsc::channel();
+            std::thread::spawn(move || {
+                let _ = tx.send(f());
+            });
+            rx.recv_timeout(Duration::from_secs(10)).expect(
+                "a delta-path exec fn must return within the watchdog budget, not block on a hung git",
+            )
+        }
+        let dl = || Instant::now() + Duration::from_millis(150);
+        let sha = "deadbeefdeadbeefdeadbeefdeadbeefdeadbeef";
+
+        let (p, g, d) = (path.clone(), git_bin.clone(), dl());
+        assert!(
+            returns_within(move || peeled_object_type(&p, sha, &g, d)).is_none(),
+            "peeled_object_type must time out to None on a hung cat-file"
+        );
+        let (p, g, d) = (path.clone(), git_bin.clone(), dl());
+        assert!(
+            returns_within(move || rev_list_delta(&p, &[sha], &[], &g, d)).is_err(),
+            "rev_list_delta must error out on a hung rev-list"
+        );
+        let (p, g, d) = (path.clone(), git_bin.clone(), dl());
+        assert!(
+            returns_within(move || list_all_objects_with_type(&p, &g, d)).is_err(),
+            "list_all_objects_with_type must error out on a hung cat-file"
+        );
+    }
 }

crates/gitlawb-node/src/git/tigris.rs

@@ -31,6 +31,25 @@ impl TigrisClient {
         })
     }
 
+    /// Test-only constructor with an explicit S3 endpoint, region, and static
+    /// credentials — no env-var reads, so parallel tests cannot race each other's
+    /// `AWS_*` environment the way the env-based `new` would. Lets a test point
+    /// the client at a non-routable endpoint to exercise acquire-stall paths.
+    #[cfg(test)]
+    pub(crate) async fn for_testing_with_endpoint(bucket: &str, endpoint_url: &str) -> Self {
+        let creds = aws_sdk_s3::config::Credentials::new("test", "test", None, None, "test");
+        let config = aws_config::defaults(aws_config::BehaviorVersion::latest())
+            .endpoint_url(endpoint_url)
+            .region(aws_config::Region::new("auto"))
+            .credentials_provider(creds)
+            .load()
+            .await;
+        Self {
+            s3: S3Client::new(&config),
+            bucket: bucket.to_string(),
+        }
+    }
+
     /// S3 key for a given repo: `repos/v1/{owner_slug}/{repo_name}.tar.zst`
     fn repo_key(owner_slug: &str, repo_name: &str) -> String {
         format!("repos/v1/{owner_slug}/{repo_name}.tar.zst")

crates/gitlawb-node/src/graphql/mod.rs

@@ -14,6 +14,68 @@ use subscription::SubscriptionRoot;
 
 pub type GitlawbSchema = Schema<QueryRoot, MutationRoot, SubscriptionRoot>;
 
+/// Client-facing message for GraphQL resolver failures that wrap a real
+/// `sqlx::Error`. The real error is logged server-side; never put sqlx/Postgres
+/// detail in the GraphQL `errors` array (#250).
+///
+/// Kept as its own constant on this PR's base (main still renders
+/// `AppError::Db` with `e.to_string()`). If/when #247's `DB_ERROR_MESSAGE`
+/// lands, fold this into that shared constant.
+pub const GRAPHQL_DB_ERROR_MESSAGE: &str = "a database error occurred";
+
+fn anyhow_has_sqlx(e: &anyhow::Error) -> bool {
+    e.chain().any(|c| c.downcast_ref::<sqlx::Error>().is_some())
+}
+
+/// Map an `anyhow` failure from the db layer to a GraphQL error.
+///
+/// - Real DB faults (`sqlx::Error` anywhere in the chain) → opaque client
+///   message + `error!` log with the full `{e:#}` cause chain.
+/// - Application/business errors (e.g. claim race, not-in-claimed-state) →
+///   keep the actionable message; log at `warn!` so they are not mistaken for
+///   infrastructure failures (#250 review).
+pub(crate) fn graphql_db_err(e: anyhow::Error) -> async_graphql::Error {
+    if anyhow_has_sqlx(&e) {
+        tracing::error!(error = %format!("{e:#}"), "graphql database error");
+        async_graphql::Error::new(GRAPHQL_DB_ERROR_MESSAGE)
+    } else {
+        tracing::warn!(error = %format!("{e:#}"), "graphql application error");
+        async_graphql::Error::new(e.to_string())
+    }
+}
+
+/// Map an `AppError` from a shared collector (e.g. ref-update feed) to a
+/// GraphQL error.
+///
+/// Fail closed: only explicitly curated variants surface their `Display`
+/// text. Unnamed variants (including `Git`, which may embed on-disk paths)
+/// render opaque so a future addition cannot leak by default (#255 review).
+pub(crate) fn graphql_app_err(e: crate::error::AppError) -> async_graphql::Error {
+    match e {
+        crate::error::AppError::Db(sql) => graphql_db_err(sql.into()),
+        crate::error::AppError::Internal(err) => {
+            tracing::error!(error = %format!("{err:#}"), "graphql internal error");
+            async_graphql::Error::new(GRAPHQL_DB_ERROR_MESSAGE)
+        }
+        // Curated client-safe variants — `Display` is intentional API text.
+        safe @ (crate::error::AppError::RepoNotFound(_)
+        | crate::error::AppError::RepoExists(_)
+        | crate::error::AppError::NotFound(_)
+        | crate::error::AppError::Unauthorized(_)
+        | crate::error::AppError::Forbidden(_)
+        | crate::error::AppError::BadRequest(_)
+        | crate::error::AppError::TooManyRequests(_)
+        | crate::error::AppError::Incomplete(_)) => {
+            tracing::warn!(error = %safe, "graphql application error");
+            async_graphql::Error::new(safe.to_string())
+        }
+        other => {
+            tracing::error!(error = %other, "graphql unclassified AppError (opaque)");
+            async_graphql::Error::new(GRAPHQL_DB_ERROR_MESSAGE)
+        }
+    }
+}
+
 pub fn build_schema(
     db: Arc<Db>,
     ref_update_tx: tokio::sync::broadcast::Sender<RefUpdateBroadcast>,
@@ -25,3 +87,105 @@ pub fn build_schema(
         .data(task_event_tx)
         .finish()
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn graphql_db_err_opaques_sqlx_chain() {
+        let leak = "error returned from database: column \"is_public\" does not exist";
+        // Context layer must not hide sqlx from the chain walk (db helpers
+        // wrap with `.context(...)` in several places).
+        let err = graphql_db_err(
+            anyhow::Error::from(sqlx::Error::Protocol(leak.into())).context("loading repos"),
+        );
+        assert_eq!(err.message, GRAPHQL_DB_ERROR_MESSAGE);
+        assert!(!err.message.contains("is_public"));
+        assert!(!err.message.contains(leak));
+        assert!(!err.message.contains("loading repos"));
+    }
+
+    #[test]
+    fn graphql_db_err_keeps_business_message() {
+        let msg = "task not claimable: not found or already claimed";
+        let err = graphql_db_err(anyhow::anyhow!("{msg}"));
+        assert_eq!(err.message, msg);
+    }
+
+    #[test]
+    fn graphql_app_err_opaques_db_and_internal() {
+        let leak = "column \"is_public\" does not exist";
+        let db_err = graphql_app_err(crate::error::AppError::Db(sqlx::Error::Protocol(
+            leak.into(),
+        )));
+        assert_eq!(db_err.message, GRAPHQL_DB_ERROR_MESSAGE);
+        assert!(!db_err.message.contains("is_public"));
+
+        let internal = graphql_app_err(crate::error::AppError::Internal(anyhow::anyhow!(
+            "loading repo: {leak}"
+        )));
+        assert_eq!(internal.message, GRAPHQL_DB_ERROR_MESSAGE);
+        assert!(!internal.message.contains("is_public"));
+    }
+
+    #[test]
+    fn graphql_app_err_keeps_safe_variant_messages() {
+        let err = graphql_app_err(crate::error::AppError::NotFound("widget".into()));
+        assert!(
+            err.message.contains("widget"),
+            "safe NotFound message must reach the client: {}",
+            err.message
+        );
+        assert_ne!(err.message, GRAPHQL_DB_ERROR_MESSAGE);
+
+        let err = graphql_app_err(crate::error::AppError::BadRequest("bad cid".into()));
+        assert!(
+            err.message.contains("bad cid"),
+            "safe BadRequest message must reach the client: {}",
+            err.message
+        );
+        assert_ne!(err.message, GRAPHQL_DB_ERROR_MESSAGE);
+    }
+
+    #[test]
+    fn graphql_app_err_opaques_unclassified_variants() {
+        // `Git` may embed on-disk paths from libgit2; fail closed.
+        let path = "/var/lib/gitlawb/repos/owner/secret.git";
+        let err = graphql_app_err(crate::error::AppError::Git(format!(
+            "failed to open '{path}'"
+        )));
+        assert_eq!(err.message, GRAPHQL_DB_ERROR_MESSAGE);
+        assert!(!err.message.contains(path));
+        assert!(!err.message.contains("failed to open"));
+    }
+
+    /// Every `.map_err(` in the GraphQL query/mutation resolvers must route
+    /// through the opaque helpers, or discard the error (`|_|`). Same source-
+    /// scrape pattern as `api::authz_guard` (#255 review).
+    #[test]
+    fn every_graphql_map_err_uses_opaque_helpers() {
+        for (file, src) in [
+            ("query.rs", include_str!("query.rs")),
+            ("mutation.rs", include_str!("mutation.rs")),
+        ] {
+            for (lineno, line) in src.lines().enumerate() {
+                let code = line.split("//").next().unwrap_or(line);
+                let Some(idx) = code.find(".map_err(") else {
+                    continue;
+                };
+                let after = code[idx + ".map_err(".len()..].trim_start();
+                let ok = after.starts_with("crate::graphql::graphql_db_err")
+                    || after.starts_with("crate::graphql::graphql_app_err")
+                    || after.starts_with("|_|")
+                    || after.starts_with("|_ ");
+                assert!(
+                    ok,
+                    "{file}:{}: `.map_err(` must use graphql_db_err / graphql_app_err \
+                     or discard (`|_|`): {line}",
+                    lineno + 1
+                );
+            }
+        }
+    }
+}

crates/gitlawb-node/src/graphql/mutation.rs

@@ -54,7 +54,7 @@ impl MutationRoot {
         };
         db.create_task(&task)
             .await
-            .map_err(|e| async_graphql::Error::new(e.to_string()))?;
+            .map_err(crate::graphql::graphql_db_err)?;
         Ok(AgentTaskType::from(task))
     }
 
@@ -76,7 +76,7 @@ impl MutationRoot {
         let task = db
             .claim_task(&id, &assignee_did)
             .await
-            .map_err(|e| async_graphql::Error::new(e.to_string()))?;
+            .map_err(crate::graphql::graphql_db_err)?;
         let _ = tx.send(TaskEventBroadcast {
             task_id: id,
             old_status: "pending".to_string(),
@@ -108,7 +108,7 @@ impl MutationRoot {
         let existing = db
             .get_task(&id)
             .await
-            .map_err(|e| async_graphql::Error::new(e.to_string()))?
+            .map_err(crate::graphql::graphql_db_err)?
             .ok_or_else(|| async_graphql::Error::new("task not found"))?;
         if !crate::api::did_matches(caller, existing.assignee_did.as_deref().unwrap_or_default()) {
             return Err(async_graphql::Error::new(
@@ -118,7 +118,7 @@ impl MutationRoot {
         let task = db
             .finish_task(&id, "completed", input.result.as_deref())
             .await
-            .map_err(|e| async_graphql::Error::new(e.to_string()))?;
+            .map_err(crate::graphql::graphql_db_err)?;
         let _ = tx.send(TaskEventBroadcast {
             task_id: id,
             old_status: "claimed".to_string(),
@@ -149,7 +149,7 @@ impl MutationRoot {
         let existing = db
             .get_task(&id)
             .await
-            .map_err(|e| async_graphql::Error::new(e.to_string()))?
+            .map_err(crate::graphql::graphql_db_err)?
             .ok_or_else(|| async_graphql::Error::new("task not found"))?;
         if !crate::api::did_matches(caller, existing.assignee_did.as_deref().unwrap_or_default()) {
             return Err(async_graphql::Error::new(
@@ -160,7 +160,7 @@ impl MutationRoot {
         let task = db
             .finish_task(&id, "failed", Some(&reason))
             .await
-            .map_err(|e| async_graphql::Error::new(e.to_string()))?;
+            .map_err(crate::graphql::graphql_db_err)?;
         let _ = tx.send(TaskEventBroadcast {
             task_id: id,
             old_status: "claimed".to_string(),
@@ -218,8 +218,9 @@ mod tests {
             errors(&resp)
         );
 
-        // 3. Signed as the claimed assignee → passes the auth gate (any remaining
-        //    error is the missing task, not an auth error).
+        // 3. Signed as the claimed assignee → passes the auth gate. The missing
+        //    task is a business error from claim_task, not a sqlx fault, so the
+        //    actionable message must survive (not the opaque DB string) (#250).
         let resp = schema
             .execute(Request::new(&q).data(AuthenticatedDid(assignee.into())))
             .await;
@@ -228,6 +229,47 @@ mod tests {
             !errs.contains("authentication required") && !errs.contains("authenticated signer"),
             "matching signer must pass the auth gate: {errs}"
         );
+        assert!(
+            errs.contains("task not claimable"),
+            "claim race / missing task must keep its business message: {errs}"
+        );
+        assert!(
+            !errs.contains(crate::graphql::GRAPHQL_DB_ERROR_MESSAGE),
+            "business error must not be rewritten as opaque DB error: {errs}"
+        );
+    }
+
+    /// #250: mutation DB faults must be opaque; create_task hits agent_tasks.
+    #[sqlx::test]
+    async fn create_task_db_error_message_is_opaque(pool: PgPool) {
+        let state = crate::test_support::test_state(pool.clone()).await;
+        sqlx::query("ALTER TABLE agent_tasks DROP COLUMN status")
+            .execute(&pool)
+            .await
+            .unwrap();
+
+        let delegator = "did:key:zGQLDELEGATORAAAAAAAAAAAAAAAAAAAAAAAAAA";
+        let q = format!(
+            r#"mutation {{
+                createTask(
+                    delegatorDid: "{delegator}",
+                    input: {{ kind: "build", capability: "repo:write" }}
+                ) {{ id }}
+            }}"#
+        );
+        let resp = state
+            .graphql_schema
+            .execute(Request::new(&q).data(AuthenticatedDid(delegator.into())))
+            .await;
+        let errs = errors(&resp);
+        assert!(
+            errs.contains(crate::graphql::GRAPHQL_DB_ERROR_MESSAGE),
+            "sqlx fault must be opaque: {errs}"
+        );
+        assert!(
+            !errs.contains("column") && !errs.contains("status"),
+            "schema text leaked: {errs}"
+        );
     }
 
     /// Adversarial-review GATE-1 (GraphQL): completing a task requires being its

crates/gitlawb-node/src/graphql/query.rs

@@ -14,7 +14,7 @@ impl QueryRoot {
         let repos = db
             .list_all_repos_deduped()
             .await
-            .map_err(|e| async_graphql::Error::new(e.to_string()))?;
+            .map_err(crate::graphql::graphql_db_err)?;
 
         // Apply the same "/" visibility gate the REST/per-repo endpoints use so
         // this surface does not enumerate private repos (#97). The caller DID is
@@ -27,7 +27,7 @@ impl QueryRoot {
         let rules_by_repo = db
             .list_visibility_rules_for_repos(&ids)
             .await
-            .map_err(|e| async_graphql::Error::new(e.to_string()))?;
+            .map_err(crate::graphql::graphql_db_err)?;
 
         Ok(repos
             .into_iter()
@@ -71,7 +71,7 @@ impl QueryRoot {
         let updates =
             crate::api::events::collect_visible_ref_updates(db, repo.as_deref(), limit, caller)
                 .await
-                .map_err(|e| async_graphql::Error::new(e.to_string()))?;
+                .map_err(crate::graphql::graphql_app_err)?;
 
         // Resolve the trusted display owner_did per row, identical to the REST
         // feed: the stored wire value is untrusted, so it is echoed only when it
@@ -86,7 +86,7 @@ impl QueryRoot {
         let owner_dids = db
             .resolve_ref_update_owner_dids(&pairs)
             .await
-            .map_err(|e| async_graphql::Error::new(e.to_string()))?;
+            .map_err(crate::graphql::graphql_db_err)?;
 
         let resolved: Vec<RefUpdateType> = updates
             .into_iter()
@@ -110,13 +110,21 @@ impl QueryRoot {
         ctx: &Context<'_>,
         status: Option<String>,
         assignee_did: Option<String>,
-        #[graphql(default = 50)] limit: i64,
+        #[graphql(
+            default = 50,
+            desc = "Max 200; larger requests are clamped to 200 (no error). Negative values clamp to 0."
+        )]
+        limit: i64,
     ) -> Result<Vec<AgentTaskType>> {
         let db = ctx.data_unchecked::<Arc<Db>>();
+        // Clamp before SQL: a negative LIMIT is a client fault that Postgres
+        // rejects with 2201W, which would otherwise trip the opaque DB path
+        // and write an error-level log on every probe (#250 review).
+        let limit = limit.clamp(0, 200);
         let tasks = db
             .list_tasks(status.as_deref(), assignee_did.as_deref(), limit)
             .await
-            .map_err(|e| async_graphql::Error::new(e.to_string()))?;
+            .map_err(crate::graphql::graphql_db_err)?;
         Ok(tasks.into_iter().map(AgentTaskType::from).collect())
     }
 
@@ -125,7 +133,7 @@ impl QueryRoot {
         let t = db
             .get_task(&id)
             .await
-            .map_err(|e| async_graphql::Error::new(e.to_string()))?;
+            .map_err(crate::graphql::graphql_db_err)?;
         Ok(t.map(AgentTaskType::from))
     }
 }
@@ -419,4 +427,91 @@ mod tests {
         let q = r#"{ refUpdates { repo } }"#;
         assert_eq!(count(&authed(&schema, q, "did:key:z6MkQuar").await), 0);
     }
+
+    /// #250: anonymous GraphQL query DB failures must not leak sqlx/schema text.
+    #[sqlx::test]
+    async fn repos_query_db_error_message_is_opaque(pool: PgPool) {
+        let db = db(pool.clone()).await;
+        db.create_repo(&repo("r1", OWNER, "widget", true))
+            .await
+            .unwrap();
+        sqlx::query("ALTER TABLE repos DROP COLUMN is_public")
+            .execute(&pool)
+            .await
+            .unwrap();
+
+        let schema = schema(db);
+        let resp = anon(&schema, "{ repos { name ownerDid } }").await;
+        assert!(
+            !resp.errors.is_empty(),
+            "DB failure must surface as a GraphQL error"
+        );
+        for err in &resp.errors {
+            assert_eq!(
+                err.message,
+                crate::graphql::GRAPHQL_DB_ERROR_MESSAGE,
+                "raw DB detail leaked into GraphQL error: {}",
+                err.message
+            );
+            assert!(
+                !err.message.contains("is_public") && !err.message.contains("column"),
+                "schema text leaked: {}",
+                err.message
+            );
+        }
+    }
+
+    /// #250: negative tasks(limit) must not hit Postgres (and must not 500-log).
+    #[sqlx::test]
+    async fn tasks_negative_limit_clamped(pool: PgPool) {
+        let db = db(pool).await;
+        let schema = schema(db);
+        let resp = anon(&schema, "{ tasks(limit: -1) { id } }").await;
+        assert!(
+            resp.errors.is_empty(),
+            "negative limit must clamp, not fail: {:?}",
+            resp.errors
+        );
+        assert_eq!(count_tasks(&resp), 0);
+    }
+
+    /// #255: ceiling of the tasks(limit) clamp must be held (schema promises Max 200).
+    #[sqlx::test]
+    async fn tasks_limit_ceiling_clamped_to_200(pool: PgPool) {
+        let db = db(pool).await;
+        let now = Utc::now().to_rfc3339();
+        for i in 0..201 {
+            db.create_task(&crate::db::AgentTask {
+                id: format!("task-ceil-{i}"),
+                repo_id: None,
+                kind: "build".into(),
+                status: "pending".into(),
+                delegator_did: OWNER.into(),
+                assignee_did: None,
+                capability: "repo:write".into(),
+                ucan_token: None,
+                payload: None,
+                result: None,
+                created_at: now.clone(),
+                updated_at: now.clone(),
+                deadline: None,
+            })
+            .await
+            .unwrap();
+        }
+        let schema = schema(db);
+        let resp = anon(&schema, "{ tasks(limit: 5000) { id } }").await;
+        assert_eq!(count_tasks(&resp), 200, "limit above 200 must clamp to 200");
+    }
+
+    fn count_tasks(resp: &async_graphql::Response) -> usize {
+        assert!(resp.errors.is_empty(), "graphql errors: {:?}", resp.errors);
+        let async_graphql::Value::Object(obj) = &resp.data else {
+            panic!("data not an object: {:?}", resp.data);
+        };
+        let async_graphql::Value::List(rows) = obj.get("tasks").expect("tasks key") else {
+            panic!("tasks not a list");
+        };
+        rows.len()
+    }
 }

crates/gitlawb-node/src/main.rs

@@ -31,6 +31,7 @@ use axum::response::IntoResponse;
 use axum::routing::get;
 use axum::{Json, Router};
 use clap::Parser;
+use std::collections::HashSet;
 use std::sync::atomic::{AtomicU64, Ordering};
 use std::sync::Arc;
 use tokio::net::TcpListener;
@@ -58,6 +59,32 @@ struct DbStartupStatus {
     next_retry_secs: AtomicU64,
 }
 
+/// Hard ceiling on the advisory-lock pool's `max_connections`.
+///
+/// `max_concurrent_git_pushes` is validated all the way up to 1_048_576, and the lock
+/// pool used to derive its size straight from that knob, so raising the push cap
+/// silently raised the node's Postgres connection ceiling with no CLI error and no
+/// relation to the server's own `max_connections` (#173 F4). The node's total budget is
+/// now bounded: `db_max_connections` (default 48) + at most this.
+const LOCK_POOL_MAX_CONNECTIONS: u32 = 64;
+
+/// Connections the lock pool keeps above the push cap. Covers the three non-push
+/// `acquire_write` callers (`api/issues.rs` x2, `api/pulls.rs`), which hold no
+/// concurrency permit, so a push never queues here for a connection where it did not
+/// before.
+const LOCK_POOL_PUSH_HEADROOM: u8 = 8;
+
+/// Size the advisory-lock pool for a given push cap: the cap plus
+/// [`LOCK_POOL_PUSH_HEADROOM`], clamped to [`LOCK_POOL_MAX_CONNECTIONS`]. Past the
+/// clamp a push may wait for a lock-pool connection, which is a bounded wait that sheds
+/// a clean 503 (see `LockPoolBusy`), not an unbounded hang.
+fn lock_pool_size(max_concurrent_git_pushes: usize) -> u32 {
+    u32::try_from(max_concurrent_git_pushes)
+        .unwrap_or(u32::MAX)
+        .saturating_add(u32::from(LOCK_POOL_PUSH_HEADROOM))
+        .min(LOCK_POOL_MAX_CONNECTIONS)
+}
+
 #[tokio::main]
 async fn main() -> Result<()> {
     tracing_subscriber::fmt()
@@ -74,6 +101,13 @@ async fn main() -> Result<()> {
     // bootstrap peers. Operators can opt out via GITLAWB_BOOTSTRAP_DISABLE_SEEDS.
     bootstrap::merge_seeds(&mut config);
 
+    // Fail fast on config combinations that are individually in-range but jointly
+    // unsafe — notably a DB pool too small for the concurrent-write cap, which
+    // would let a push burst starve every other DB path (#174 F1).
+    config
+        .validate()
+        .map_err(|e| anyhow::anyhow!("invalid configuration: {e}"))?;
+
     if !config.public_read {
         warn!(
             "GITLAWB_PUBLIC_READ=false is reserved; per-repository private-read enforcement is not wired in alpha"
@@ -279,8 +313,20 @@ async fn main() -> Result<()> {
         None
     };
 
-    let repo_store =
-        git::repo_store::RepoStore::new(config.repos_dir.clone(), tigris, db.pool().clone());
+    // Repo write locks run on their own pool, never the main query pool: each push
+    // holds its connection for the whole receive-pack, so a burst of concurrent
+    // pushes drawing from the main pool would park that many connections for the
+    // duration of their receive-packs and starve every other query. That holds
+    // whatever the two pools are sized at, which is why the separation is
+    // structural rather than a consequence of the defaults; config validate()
+    // separately requires db_max_connections >= max_concurrent_git_pushes + 8. See
+    // build_lock_pool for the cancellation semantics (#173).
+    let lock_pool = git::repo_store::build_lock_pool(
+        db.pool(),
+        lock_pool_size(config.max_concurrent_git_pushes),
+        std::time::Duration::from_secs(config.db_acquire_timeout_secs),
+    );
+    let repo_store = git::repo_store::RepoStore::new(config.repos_dir.clone(), tigris, lock_pool);
 
     // Per-DID limiter for the creation endpoints. Keyed on the authenticated
     // DID (attacker-varied), so bound its key set to cap memory.
@@ -374,11 +420,100 @@ async fn main() -> Result<()> {
         rate_limiter,
         create_ip_rate_limiter,
         push_rate_limiter,
+        ipfs_max_history_walks: crate::api::ipfs::MAX_HISTORY_WALKS_PER_REQUEST,
+        // The legacy-probe budget is operator-tunable via GITLAWB_IPFS_MAX_REPOS_WALKED
+        // (R5); the history-walk ceiling above stays constant (a smaller value false-503s
+        // a provenanced request). Default 256 preserves the shipped behaviour.
+        ipfs_max_legacy_probes: AppState::ipfs_legacy_probe_budget(&config),
+        ipfs_max_served_object_bytes: crate::api::ipfs::MAX_SERVED_OBJECT_BYTES,
         push_limiter_trust,
         sync_trigger_rate_limiter,
         peer_write_rate_limiter,
         shutdown_tx: shutdown_tx.clone(),
+        git_read_semaphore: Arc::new(tokio::sync::Semaphore::new(config.max_concurrent_git_ops)),
+        git_write_semaphore: Arc::new(tokio::sync::Semaphore::new(
+            config.max_concurrent_git_pushes,
+        )),
+        // Anon receive-pack advertisements get their OWN pool, same size as the
+        // write pool but disjoint, so filling it (which takes many source IPs, each
+        // capped by git_push_advert_per_caller) never occupies a permit the
+        // authenticated POST needs (#174).
+        git_push_advert_semaphore: Arc::new(tokio::sync::Semaphore::new(
+            config.max_concurrent_git_pushes,
+        )),
+        // Bounds concurrent detached post-push encryption walks, sized from the push
+        // pool (no separate knob — Q1): completed pushes cannot outnumber active
+        // encryption walks past this (#174 P1-e).
+        git_encrypt_semaphore: Arc::new(tokio::sync::Semaphore::new(
+            config.max_concurrent_git_pushes,
+        )),
+        // Bounds how many post-push pin loops run concurrently across all repos (#174 F6),
+        // independent of the per-repo encrypt-task coalescing below. Not a bound on the
+        // MB-scale object-id lists themselves: parked tasks still hold theirs (see the
+        // field doc on AppState::pin_semaphore).
+        pin_semaphore: Arc::new(tokio::sync::Semaphore::new(config.max_concurrent_pin_tasks)),
+        // Coalesces the DETACHED post-push encryption tasks per repo so a rapid pusher
+        // cannot grow the outstanding parked-waiter set past one task per repo (#174
+        // P2-2). No knob: it is a natural cap (one entry per distinct repo), not a
+        // sized pool.
+        encrypt_inflight: crate::state::EncryptInflight::new(),
+        // Per-repo in-process write-lease serializer (#174 U2/F3): supplements the pg
+        // advisory lock so a disconnected push's still-reaping git group can't be raced
+        // by a second same-node push. The map is naturally capped (one entry per contended
+        // repo, freed when unreferenced); the sized knob is how many pushes may PARK on
+        // one repo, since each parked push holds a fully buffered pack.
+        repo_write_leases: crate::state::RepoWriteLeases::new(config.repo_lease_max_waiters),
+        git_read_per_caller: rate_limit::PerCallerConcurrency::with_default_max_keys(
+            config.max_concurrent_reads_per_caller,
+        ),
+        // Per-source cap on the receive-pack advertisement, sized to an eighth of the
+        // write pool (min 1): one resolved client key (rate_limit::client_key) can hold
+        // at most this many slots in the DEDICATED advert pool (git_push_advert_semaphore,
+        // disjoint from the write pool), so saturating that pool takes ~8 distinct keys
+        // (#174). That bounds an IPv4 or single-address caller; a caller controlling many
+        // addresses (an IPv6 /64 is 2^64 keys) still gets one cap per address, since
+        // client_key uses the full IP with no prefix folding. Narrowing the keying is a
+        // deferred design call, not something these caps claim to solve. Sized off the
+        // write pool only because the advert pool is created at the same size; an advert
+        // flood cannot touch a write permit.
+        git_push_advert_per_caller: rate_limit::PerCallerConcurrency::with_default_max_keys(
+            rate_limit::per_source_push_cap(config.max_concurrent_git_pushes),
+        ),
+        // Per-source cap on the authenticated receive-pack POST, sized like the advert
+        // cap: one resolved client key can hold at most this many write-pool slots, so
+        // monopolizing the pool takes ~8 distinct keys (#174 P1-d). Same residual as
+        // above: keys are full IPs, so a caller with many addresses has many caps.
+        git_write_per_caller: rate_limit::PerCallerConcurrency::with_default_max_keys(
+            rate_limit::per_source_push_cap(config.max_concurrent_git_pushes),
+        ),
+        // Bounds concurrent /ipfs visibility walks — a distinct public cost center, so
+        // its own pool + per-source sub-cap + per-IP rate limiter, never a git pool
+        // (#174 P1-3). The per-source map is bounded (reject-before-insert, INV-15).
+        git_ipfs_walk_semaphore: Arc::new(tokio::sync::Semaphore::new(
+            config.max_concurrent_ipfs_walks,
+        )),
+        git_ipfs_walk_per_caller: rate_limit::PerCallerConcurrency::with_default_max_keys(
+            config.ipfs_walk_per_source,
+        ),
+        ipfs_rate_limiter: rate_limit::RateLimiter::new_bounded(
+            config.ipfs_rate_limit,
+            std::time::Duration::from_secs(3600),
+            200_000,
+        ),
+        // Separate WORK-budget bucket for the resolver's per-probe/per-walk charges (R6).
+        // Its capacity is DERIVED from the route limit (no new knob) and floored at the
+        // legacy-probe budget, so one full default-config legacy scan never self-throttles
+        // mid-request while the route brake above stays the pure once-per-request cap.
+        ipfs_work_rate_limiter: rate_limit::RateLimiter::new_bounded(
+            AppState::ipfs_work_budget(&config),
+            std::time::Duration::from_secs(3600),
+            200_000,
+        ),
+        git_bin: "git".to_string(),
     };
+    if config.ipfs_rate_limit == 0 {
+        tracing::warn!("GITLAWB_IPFS_RATE_LIMIT=0 — per-IP /ipfs rate limiting disabled");
+    }
 
     // Periodic peer-count poll for the metrics gauge. If p2p is disabled
     // we still set the gauge to 0 so dashboards don't show "no data".
@@ -408,22 +543,16 @@ async fn main() -> Result<()> {
 
     // Periodic cleanup of expired rate limit entries + consumed-proof ledger
     {
-        let rl = state.rate_limiter.clone();
-        let create_ip_rl = state.create_ip_rate_limiter.clone();
-        let push_rl = state.push_rate_limiter.clone();
-        let sync_trigger_rl = state.sync_trigger_rate_limiter.clone();
-        let peer_write_rl = state.peer_write_rate_limiter.clone();
+        let cleanup_state = state.clone();
         let db = state.db.clone();
         let mut shutdown_rx = state.subscribe_shutdown();
         tokio::spawn(async move {
             loop {
                 tokio::select! {
                     _ = tokio::time::sleep(std::time::Duration::from_secs(300)) => {
-                        rl.cleanup().await;
-                        create_ip_rl.cleanup().await;
-                        push_rl.cleanup().await;
-                        sync_trigger_rl.cleanup().await;
-                        peer_write_rl.cleanup().await;
+                        // Sweep every per-IP/DID limiter (incl. the ipfs walk brake)
+                        // so bounded maps shed stale keys instead of sitting at cap.
+                        cleanup_state.sweep_rate_limiters().await;
                         let now = std::time::SystemTime::now()
                             .duration_since(std::time::UNIX_EPOCH)
                             .map(|d| d.as_secs() as i64)
@@ -442,6 +571,8 @@ async fn main() -> Result<()> {
         });
     }
 
+    let _legacy_cid_sweep = spawn_legacy_cid_sweep(&state, &config);
+
     let router = server::build_router(state.clone());
     // Re-register the socket bound at startup — same fd, so there was never a
     // moment with the port closed between the degraded and full servers.
@@ -564,6 +695,49 @@ async fn main() -> Result<()> {
     Ok(())
 }
 
+/// U4 (#173): spawn the one-shot legacy provider-CID repair sweep. Releases before this
+/// version stored the PROVIDER CID (Kubo dag-pb / Pinata CIDv0) in `pinned_cids.cid`,
+/// and this version's `/ipfs/{cid}` resolver withholds any row whose stored key is not
+/// the raw-content CID. The opportunistic repair on the pin path only fires when a push
+/// re-carries the object, which normal git negotiation makes it not do, so those rows
+/// need a walk. DETACHED, never on the boot path: the caller keeps serving while this
+/// runs, and the sweep's own batch bound plus inter-batch delay keep it off the DB's
+/// critical path. Its cursor is durable, so a restart mid-walk resumes instead of
+/// rewinding.
+///
+/// A named function rather than an inline block in `main` so the WIRING has a seam a
+/// test can call: that the task is spawned at all, that it reads its batch and delay
+/// from the config knobs rather than some other field, that the caller is not blocked
+/// on it, and that the shutdown watcher actually ends it mid-walk. The sweep's own
+/// behavior is covered elsewhere; this is the boot-path half.
+fn spawn_legacy_cid_sweep(state: &AppState, config: &Config) -> tokio::task::JoinHandle<()> {
+    let db = state.db.clone();
+    let repos_dir = config.repos_dir.clone();
+    let git_bin = state.git_bin.clone();
+    let git_timeout = std::time::Duration::from_secs(config.git_service_timeout_secs);
+    let batch = config.pin_repair_sweep_batch;
+    let delay = std::time::Duration::from_secs(config.pin_repair_sweep_delay_secs);
+    let mut shutdown_rx = state.subscribe_shutdown();
+    tokio::spawn(async move {
+        tokio::select! {
+            stats = ipfs_pin::sweep_legacy_provider_cids(
+                &repos_dir, &git_bin, git_timeout, batch, delay, &db,
+            ) => {
+                if stats.repaired > 0 {
+                    tracing::info!(
+                        scanned = stats.scanned,
+                        repaired = stats.repaired,
+                        "legacy provider-CID sweep finished"
+                    );
+                }
+            }
+            // Shutdown mid-walk simply drops the run; the persisted cursor means the
+            // next boot picks up where this one stopped.
+            _ = shutdown_rx.changed() => {}
+        }
+    })
+}
+
 fn spawn_shutdown_signal(tx: watch::Sender<bool>) {
     tokio::spawn(async move {
         #[cfg(unix)]
@@ -733,8 +907,8 @@ fn build_degraded_router(node_did: String, db_startup: Arc<DbStartupStatus>) ->
         db_startup,
     };
     // Everything answers 503 with the same body — including /health and
-    // /ready, so peer pings (which treat any 2xx /health as alive) and
-    // uptime monitors correctly see a node that cannot serve traffic.
+    // /ready, so peer readiness probes and uptime monitors correctly see a
+    // node that cannot serve traffic.
     // `/` additionally carries the node identity for probing peers.
     Router::new()
         .route("/", get(degraded_node_info))
@@ -866,7 +1040,7 @@ async fn gossip_task(
     }
 
     // Reuse the shared no-redirect client for every gossip outbound call (the
-    // bootstrap announce POST and the periodic peer /health ping). Peer URLs are
+    // bootstrap announce POST and the periodic peer /ready ping). Peer URLs are
     // attacker-influenceable, so a 3xx to a private address must not be followed.
     // Do NOT fall back to reqwest::Client::new(): its default follows redirects
     // and would reintroduce the SSRF closed here (#93).
@@ -921,8 +1095,33 @@ async fn gossip_task(
                             json.get("node_url").and_then(|v| v.as_str()),
                         ) {
                             if !their_url.is_empty() {
-                                let _ = state.db.upsert_peer(their_did, their_url).await;
-                                tracing::info!(did = %their_did, url = %their_url, "bootstrap peer added");
+                                // Unproven, unconditionally: their_did and
+                                // their_url come straight out of the contacted
+                                // peer's JSON response body, with no signature
+                                // and no proof the claimed DID belongs to the
+                                // peer we reached. This path therefore seeds
+                                // new peers and can never repoint an existing
+                                // row. The upsert's result is matched rather
+                                // than discarded, because "bootstrap peer
+                                // added" printed over a refused write is a
+                                // denial rendering as success. Non-fatal to the
+                                // loop either way.
+                                match state
+                                    .db
+                                    .upsert_peer(
+                                        their_did,
+                                        their_url,
+                                        db::PeerWriteAuthority::Unproven,
+                                    )
+                                    .await
+                                {
+                                    Ok(()) => {
+                                        tracing::info!(did = %their_did, url = %their_url, "bootstrap peer added")
+                                    }
+                                    Err(e) => {
+                                        tracing::warn!(did = %their_did, url = %their_url, err = %e, "bootstrap peer announce-back rejected")
+                                    }
+                                }
                             }
                         }
                     }
@@ -937,6 +1136,8 @@ async fn gossip_task(
 
     // Periodic ping every 5 minutes — exit on shutdown.
     let mut interval = tokio::time::interval(std::time::Duration::from_secs(300));
+    interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Delay);
+    let mut failed_once: HashSet<String> = HashSet::new();
     loop {
         tokio::select! {
             _ = interval.tick() => {
@@ -944,10 +1145,13 @@ async fn gossip_task(
                     Ok(p) => p,
                     Err(_) => continue,
                 };
-                for peer in peers {
-                    let ok = ping_peer_health(&client, &peer.http_url).await;
-                    let _ = state.db.mark_peer_ping(&peer.did, ok).await;
-                }
+                gossip_ping_round(
+                    state.db.as_ref(),
+                    client.as_ref(),
+                    &mut failed_once,
+                    peers,
+                )
+                .await;
             }
             _ = shutdown_rx.changed() => {
                 if *shutdown_rx.borrow() {
@@ -959,6 +1163,93 @@ async fn gossip_task(
     }
 }
 
+#[cfg(test)]
+mod rate_limiter_sweep_tests {
+    use crate::rate_limit::RateLimiter;
+    use std::time::Duration;
+
+    // Every per-key limiter the router mounts must be swept by the periodic
+    // task, the `/ipfs` one included: a limiter left out keeps expired keys
+    // until its map fills and the inline capacity sweep fires. Fails on the
+    // pre-fix sweeper, which skipped `ipfs_rate_limiter`.
+    #[tokio::test]
+    async fn sweep_evicts_expired_keys_from_every_limiter() {
+        let window = Duration::from_millis(30);
+        let mut state = crate::test_support::test_state_lazy();
+        state.rate_limiter = RateLimiter::new(10, window);
+        state.create_ip_rate_limiter = RateLimiter::new(10, window);
+        state.push_rate_limiter = RateLimiter::new(10, window);
+        state.sync_trigger_rate_limiter = RateLimiter::new(10, window);
+        state.peer_write_rate_limiter = RateLimiter::new(10, window);
+        state.ipfs_rate_limiter = RateLimiter::new(10, window);
+        state.ipfs_work_rate_limiter = RateLimiter::new(10, window);
+
+        let limiters = |s: &crate::state::AppState| {
+            [
+                s.rate_limiter.clone(),
+                s.create_ip_rate_limiter.clone(),
+                s.push_rate_limiter.clone(),
+                s.sync_trigger_rate_limiter.clone(),
+                s.peer_write_rate_limiter.clone(),
+                s.ipfs_rate_limiter.clone(),
+                s.ipfs_work_rate_limiter.clone(),
+            ]
+        };
+        for l in limiters(&state) {
+            assert!(l.check("1.2.3.4").await);
+            assert_eq!(l.tracked_keys().await, 1);
+        }
+
+        tokio::time::sleep(window * 3).await;
+        state.sweep_rate_limiters().await;
+
+        for (i, l) in limiters(&state).into_iter().enumerate() {
+            assert_eq!(l.tracked_keys().await, 0, "limiter {i} was not swept");
+        }
+    }
+}
+
+async fn gossip_ping_round(
+    db: &Db,
+    client: &reqwest::Client,
+    failed_once: &mut HashSet<String>,
+    peers: Vec<db::PeerRecord>,
+) {
+    {
+        let current_dids: HashSet<&str> = peers.iter().map(|peer| peer.did.as_str()).collect();
+        failed_once.retain(|did| current_dids.contains(did.as_str()));
+    }
+    for peer in peers {
+        let ok = ping_peer_readiness(client, &peer.http_url).await;
+        match peer_ping_db_update(failed_once, &peer.did, ok) {
+            Some(reachable) => {
+                if let Err(error) = db.mark_peer_ping(&peer.did, reachable).await {
+                    warn!(did = %peer.did, err = %error, "failed to persist peer readiness");
+                }
+            }
+            None => warn!(
+                did = %peer.did,
+                "peer readiness probe failed once; preserving previous federation status"
+            ),
+        }
+    }
+}
+
+/// Decide whether one readiness sample should update the persisted federation
+/// gate. A success is authoritative immediately. A failure must repeat on the
+/// next gossip tick before it can mark a peer unreachable, so one transient
+/// database hiccup does not hide the peer's repositories for five minutes.
+fn peer_ping_db_update(failed_once: &mut HashSet<String>, did: &str, ready: bool) -> Option<bool> {
+    if ready {
+        failed_once.remove(did);
+        Some(true)
+    } else if failed_once.insert(did.to_owned()) {
+        None
+    } else {
+        Some(false)
+    }
+}
+
 /// Build the shared node HTTP client used for every outbound fan-out (sync
 /// trigger, profile/repo fetches, gossip announce + peer pings).
 ///
@@ -969,26 +1260,96 @@ async fn gossip_task(
 /// runs, not a hand-rolled equivalent.
 fn build_http_client() -> reqwest::Result<reqwest::Client> {
     reqwest::Client::builder()
-        .timeout(std::time::Duration::from_secs(10))
+        .timeout(OUTBOUND_HTTP_TIMEOUT)
         .redirect(reqwest::redirect::Policy::none())
         .build()
 }
 
-/// Ping a peer's `/health` endpoint and report whether it answered 2xx.
+const OUTBOUND_HTTP_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(10);
+
+/// Ping a peer's DB-aware `/ready` endpoint and report whether it answered 2xx.
+///
+/// A 404 falls back to `/health` for compatibility with nodes released before
+/// `/ready` existed. Other readiness failures, including 503 during a database
+/// outage, fail closed and must not use the liveness-only endpoint. The complete
+/// `/ready`-then-`/health` probe shares one timeout budget.
 ///
 /// Takes the client by reference so callers supply the shared, no-redirect
 /// `state.http_client`. Peer URLs are attacker-influenceable, so a `3xx` to a
 /// private address must not be followed. Do NOT call this with a bare
 /// `reqwest::Client::new()`: its default follows redirects and would
 /// reintroduce the SSRF this guards against (#93).
-async fn ping_peer_health(client: &reqwest::Client, http_url: &str) -> bool {
-    let url = format!("{}/health", http_url.trim_end_matches('/'));
-    client
-        .get(&url)
-        .send()
-        .await
-        .map(|r| r.status().is_success())
-        .unwrap_or(false)
+pub(crate) async fn ping_peer_readiness(client: &reqwest::Client, http_url: &str) -> bool {
+    ping_peer_readiness_with_timeout(client, http_url, OUTBOUND_HTTP_TIMEOUT).await
+}
+
+async fn ping_peer_readiness_with_timeout(
+    client: &reqwest::Client,
+    http_url: &str,
+    timeout: std::time::Duration,
+) -> bool {
+    let base_url = http_url.trim_end_matches('/');
+    let result = tokio::time::timeout(timeout, async {
+        let readiness = client.get(format!("{base_url}/ready")).send().await;
+
+        match readiness {
+            Ok(response) if response.status().is_success() => true,
+            Ok(response) if response.status() == reqwest::StatusCode::NOT_FOUND => {
+                info!(
+                    peer_url = %http_url,
+                    "peer has no readiness endpoint; falling back to legacy health probe"
+                );
+                match client.get(format!("{base_url}/health")).send().await {
+                    Ok(response) if response.status().is_success() => true,
+                    Ok(response) => {
+                        warn!(
+                            peer_url = %http_url,
+                            status = %response.status(),
+                            "legacy peer health probe reported unhealthy"
+                        );
+                        false
+                    }
+                    Err(error) => {
+                        warn!(
+                            peer_url = %http_url,
+                            err = %error,
+                            "legacy peer health probe failed"
+                        );
+                        false
+                    }
+                }
+            }
+            Ok(response) => {
+                warn!(
+                    peer_url = %http_url,
+                    status = %response.status(),
+                    "peer readiness probe reported unready"
+                );
+                false
+            }
+            Err(error) => {
+                warn!(
+                    peer_url = %http_url,
+                    err = %error,
+                    "peer readiness probe failed"
+                );
+                false
+            }
+        }
+    })
+    .await;
+
+    match result {
+        Ok(ready) => ready,
+        Err(_) => {
+            warn!(
+                peer_url = %http_url,
+                timeout_ms = timeout.as_millis(),
+                "peer readiness probe timed out"
+            );
+            false
+        }
+    }
 }
 
 fn load_or_create_keypair(config: &Config) -> Result<Keypair> {
@@ -1024,22 +1385,266 @@ fn load_or_create_keypair(config: &Config) -> Result<Keypair> {
     }
 }
 
+#[cfg(test)]
+mod legacy_cid_sweep_wiring_tests {
+    use super::spawn_legacy_cid_sweep;
+    use sqlx::PgPool;
+    use std::time::Duration;
+
+    /// Seed `count` `pinned_cids` rows whose keys are already canonical raw CIDv1, in a
+    /// known `sha256_hex` order. The sweep's own cost gate skips a raw-CIDv1 row without
+    /// reading bytes or resolving a repo, so each row is SCANNED (it advances the cursor)
+    /// and nothing else. That is what makes the cursor a clean readout of how far the
+    /// walk got, with no dependency on repos on disk.
+    async fn seed_scannable_rows(pool: &PgPool, count: usize) -> Vec<String> {
+        let mut shas = Vec::new();
+        for i in 1..=count {
+            let sha = format!("wire{i:02}");
+            let cid = gitlawb_core::cid::Cid::from_git_object_bytes(sha.as_bytes()).to_string();
+            assert!(
+                gitlawb_core::cid::is_raw_cidv1(&cid),
+                "the seeded key must hit the sweep's raw-CIDv1 skip, not a repair attempt"
+            );
+            sqlx::query("INSERT INTO pinned_cids (sha256_hex, cid, pinned_at) VALUES ($1, $2, $3)")
+                .bind(&sha)
+                .bind(&cid)
+                .bind("2020-01-01T00:00:00Z")
+                .execute(pool)
+                .await
+                .unwrap();
+            shas.push(sha);
+        }
+        shas
+    }
+
+    /// Poll the persisted sweep cursor until it reaches `want`, or give up.
+    async fn cursor_reaches(db: &crate::db::Db, want: &str, within: Duration) -> String {
+        let deadline = std::time::Instant::now() + within;
+        loop {
+            let c = db.pin_repair_cursor().await.unwrap();
+            if c == want || std::time::Instant::now() >= deadline {
+                return c;
+            }
+            tokio::time::sleep(Duration::from_millis(20)).await;
+        }
+    }
+
+    /// #173 U4, the BOOT-PATH half. The sweep's own logic (batching, cursor resumption,
+    /// terminal vs retryable skips) is covered in `test_support`; what this covers is the
+    /// wiring `main` performs, which nothing else executes: the task is spawned at all,
+    /// it takes its batch and delay from the two `pin_repair_sweep_*` knobs rather than
+    /// some other config field, the caller is not blocked on the walk, and the shutdown
+    /// watcher ends the run mid-walk.
+    ///
+    /// Six scannable rows, batch 2, delay 30s. One pass must land the cursor on exactly
+    /// the second row and the task must then still be alive in its inter-batch sleep,
+    /// which pins both knobs at once: a different batch stops at a different row, and a
+    /// delay that did not come from the knob either finishes the table or leaves the task
+    /// gone. Shutdown must then end it while four rows are still unwalked.
+    #[sqlx::test]
+    async fn the_boot_path_spawns_the_sweep_detached_with_its_configured_knobs(pool: PgPool) {
+        let state = crate::test_support::test_state(pool.clone()).await;
+        let shas = seed_scannable_rows(&pool, 6).await;
+        let repos_dir = tempfile::TempDir::new().unwrap();
+
+        let mut config = (*state.config).clone();
+        config.repos_dir = repos_dir.path().to_path_buf();
+        config.pin_repair_sweep_batch = 2;
+        // Far longer than this test runs, so a task still alive after the first pass can
+        // only be one that is honoring the configured inter-batch delay.
+        config.pin_repair_sweep_delay_secs = 30;
+
+        let started = std::time::Instant::now();
+        let handle = spawn_legacy_cid_sweep(&state, &config);
+        let spawn_cost = started.elapsed();
+
+        let cursor = cursor_reaches(&state.db, &shas[1], Duration::from_secs(10)).await;
+        assert_eq!(
+            cursor, shas[1],
+            "the spawned sweep must run and stop its first pass at the CONFIGURED batch \
+             bound (2), leaving the cursor on the second row"
+        );
+        assert!(
+            spawn_cost < Duration::from_secs(1),
+            "the sweep must be detached, not awaited on the boot path; the spawn took \
+             {spawn_cost:?}"
+        );
+        assert!(
+            !handle.is_finished(),
+            "with a 30s inter-batch delay the task must still be sleeping between passes, \
+             not finished: a finished task means the delay was not the configured one"
+        );
+
+        state.shutdown();
+        tokio::time::timeout(Duration::from_secs(10), handle)
+            .await
+            .expect("the shutdown watcher must end the sweep, and not after its 30s delay")
+            .expect("the sweep task must not panic");
+
+        assert_eq!(
+            state.db.pin_repair_cursor().await.unwrap(),
+            shas[1],
+            "shutdown must have ended the run MID-walk, with the remaining rows unwalked"
+        );
+    }
+}
+
+#[cfg(test)]
+mod lock_pool_sizing_tests {
+    use super::{lock_pool_size, LOCK_POOL_MAX_CONNECTIONS, LOCK_POOL_PUSH_HEADROOM};
+
+    /// The default push cap gets its cap plus headroom, so no push ever queues for a
+    /// lock-pool connection where it did not before.
+    #[test]
+    fn default_push_cap_gets_headroom_over_the_cap() {
+        assert_eq!(lock_pool_size(32), 32 + u32::from(LOCK_POOL_PUSH_HEADROOM));
+        assert_eq!(lock_pool_size(1), 1 + u32::from(LOCK_POOL_PUSH_HEADROOM));
+    }
+
+    /// #173 F4: `max_concurrent_git_pushes` is validated all the way to 1_048_576, so an
+    /// operator raising it used to raise the node's Postgres connection ceiling with it,
+    /// silently and without bound. The lock pool is CLAMPED instead.
+    #[test]
+    fn an_oversized_push_cap_is_clamped_not_propagated() {
+        assert_eq!(lock_pool_size(1_048_576), LOCK_POOL_MAX_CONNECTIONS);
+        assert_eq!(lock_pool_size(usize::MAX), LOCK_POOL_MAX_CONNECTIONS);
+        // The largest cap that still fits under the clamp keeps its full headroom.
+        let widest = (LOCK_POOL_MAX_CONNECTIONS - u32::from(LOCK_POOL_PUSH_HEADROOM)) as usize;
+        assert_eq!(lock_pool_size(widest), LOCK_POOL_MAX_CONNECTIONS);
+        assert_eq!(
+            lock_pool_size(widest - 1),
+            LOCK_POOL_MAX_CONNECTIONS - 1,
+            "values below the clamp must not be rounded up to it"
+        );
+    }
+}
+
 #[cfg(test)]
 mod gossip_ssrf_tests {
-    use super::ping_peer_health;
+    use super::{
+        gossip_ping_round, peer_ping_db_update, ping_peer_readiness,
+        ping_peer_readiness_with_timeout,
+    };
+    use axum::{http::StatusCode, routing::get, Router};
+    use sqlx::PgPool;
+    use std::collections::HashSet;
+    use std::sync::atomic::{AtomicUsize, Ordering};
+    use std::sync::Arc;
+    use std::time::Duration;
 
     // Build the client exactly as production does (super::build_http_client) so
     // these tests bind the redirect guarantee to the real shared client the
     // node runs. A regression that makes build_http_client follow redirects
-    // fails ping_peer_health_does_not_follow_redirect.
+    // fails ping_peer_readiness_does_not_follow_redirect.
     fn production_http_client() -> reqwest::Client {
         super::build_http_client().expect("failed to build production http client")
     }
 
-    // A peer answering `/health` with a 302 toward an internal address must not
+    #[test]
+    fn peer_ping_requires_two_failures_before_marking_unreachable() {
+        let mut failed_once = HashSet::new();
+        let did = "did:key:z6MkPeer";
+
+        assert_eq!(
+            peer_ping_db_update(&mut failed_once, did, false),
+            None,
+            "one transient failure must preserve the persisted federation gate"
+        );
+        assert_eq!(
+            peer_ping_db_update(&mut failed_once, did, false),
+            Some(false),
+            "a sustained failure must mark the peer unreachable"
+        );
+        assert_eq!(
+            peer_ping_db_update(&mut failed_once, did, true),
+            Some(true),
+            "a success must restore reachability immediately"
+        );
+        assert_eq!(
+            peer_ping_db_update(&mut failed_once, did, false),
+            None,
+            "a success must reset the consecutive-failure state"
+        );
+    }
+
+    #[sqlx::test]
+    async fn gossip_ping_round_requires_two_failures_before_persisting_unreachable(pool: PgPool) {
+        let mut server = mockito::Server::new_async().await;
+        let ready = server
+            .mock("GET", "/ready")
+            .with_status(503)
+            .expect(2)
+            .create_async()
+            .await;
+        let state = crate::test_support::test_state(pool.clone()).await;
+        let did = "did:key:z6MkGossipHysteresis";
+        let now = chrono::Utc::now().to_rfc3339();
+        sqlx::query(
+            "INSERT INTO peers (did, http_url, last_seen, last_ping_ok, announced_at)
+             VALUES ($1, $2, $3, TRUE, $3)",
+        )
+        .bind(did)
+        .bind(server.url())
+        .bind(now)
+        .execute(&pool)
+        .await
+        .unwrap();
+
+        let mut failed_once = HashSet::from(["did:key:z6MkRemovedPeer".to_owned()]);
+        gossip_ping_round(
+            state.db.as_ref(),
+            &production_http_client(),
+            &mut failed_once,
+            state.db.list_peers().await.unwrap(),
+        )
+        .await;
+        assert!(
+            !failed_once.contains("did:key:z6MkRemovedPeer"),
+            "failure tracking must prune peers outside the current snapshot"
+        );
+        assert!(
+            failed_once.contains(did),
+            "the first failed sample must be retained for the next round"
+        );
+        assert!(
+            state
+                .db
+                .list_peers()
+                .await
+                .unwrap()
+                .into_iter()
+                .find(|peer| peer.did == did)
+                .unwrap()
+                .last_ping_ok,
+            "one transient failure must preserve the persisted federation gate"
+        );
+
+        gossip_ping_round(
+            state.db.as_ref(),
+            &production_http_client(),
+            &mut failed_once,
+            state.db.list_peers().await.unwrap(),
+        )
+        .await;
+        assert!(
+            !state
+                .db
+                .list_peers()
+                .await
+                .unwrap()
+                .into_iter()
+                .find(|peer| peer.did == did)
+                .unwrap()
+                .last_ping_ok,
+            "two consecutive failed rounds must persist the peer as unreachable"
+        );
+        ready.assert_async().await;
+    }
+
+    // A peer answering `/ready` with a 302 toward an internal address must not
     // be followed: the redirect target must never be requested (#93).
     #[tokio::test]
-    async fn ping_peer_health_does_not_follow_redirect() {
+    async fn ping_peer_readiness_does_not_follow_redirect() {
         let mut server = mockito::Server::new_async().await;
         let internal = server
             .mock("GET", "/internal-metadata")
@@ -1047,6 +1652,154 @@ mod gossip_ssrf_tests {
             .expect(0)
             .create_async()
             .await;
+        let _ready = server
+            .mock("GET", "/ready")
+            .with_status(302)
+            .with_header("location", &format!("{}/internal-metadata", server.url()))
+            .create_async()
+            .await;
+
+        let ok = ping_peer_readiness(&production_http_client(), &server.url()).await;
+
+        assert!(!ok, "a 302 must not count as a healthy peer");
+        // expect(0) is enforced only at assert time; this fails if the redirect
+        // was followed to the internal target.
+        internal.assert_async().await;
+    }
+
+    #[tokio::test]
+    async fn ping_peer_readiness_reports_success_on_200() {
+        let mut server = mockito::Server::new_async().await;
+        let _ready = server
+            .mock("GET", "/ready")
+            .with_status(200)
+            .create_async()
+            .await;
+
+        let ok = ping_peer_readiness(&production_http_client(), &server.url()).await;
+
+        assert!(ok, "a 200 /ready must count as a ready peer");
+    }
+
+    #[tokio::test]
+    async fn ping_peer_readiness_ignores_liveness_only_health() {
+        let mut server = mockito::Server::new_async().await;
+        let health = server
+            .mock("GET", "/health")
+            .with_status(200)
+            .expect(0)
+            .create_async()
+            .await;
+        let ready = server
+            .mock("GET", "/ready")
+            .with_status(503)
+            .expect(1)
+            .create_async()
+            .await;
+
+        let ok = ping_peer_readiness(&production_http_client(), &server.url()).await;
+
+        assert!(!ok, "a peer with an unavailable database must not be ready");
+        health.assert_async().await;
+        ready.assert_async().await;
+    }
+
+    #[tokio::test]
+    async fn ping_peer_readiness_falls_back_for_legacy_peer() {
+        let mut server = mockito::Server::new_async().await;
+        let ready = server
+            .mock("GET", "/ready")
+            .with_status(404)
+            .expect(1)
+            .create_async()
+            .await;
+        let health = server
+            .mock("GET", "/health")
+            .with_status(200)
+            .expect(1)
+            .create_async()
+            .await;
+
+        let ok = ping_peer_readiness(&production_http_client(), &server.url()).await;
+
+        assert!(
+            ok,
+            "a legacy peer with a healthy /health must remain reachable"
+        );
+        ready.assert_async().await;
+        health.assert_async().await;
+    }
+
+    #[tokio::test]
+    async fn ping_peer_readiness_legacy_fallback_shares_deadline() {
+        let health_requests = Arc::new(AtomicUsize::new(0));
+        let health_requests_for_route = Arc::clone(&health_requests);
+        let app = Router::new()
+            .route(
+                "/ready",
+                get(|| async {
+                    tokio::time::sleep(Duration::from_millis(100)).await;
+                    StatusCode::NOT_FOUND
+                }),
+            )
+            .route(
+                "/health",
+                get(move || {
+                    let health_requests = Arc::clone(&health_requests_for_route);
+                    async move {
+                        health_requests.fetch_add(1, Ordering::Relaxed);
+                        tokio::time::sleep(Duration::from_millis(300)).await;
+                        StatusCode::OK
+                    }
+                }),
+            );
+        let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
+            .await
+            .expect("failed to bind delayed legacy peer");
+        let peer_url = format!(
+            "http://{}",
+            listener
+                .local_addr()
+                .expect("delayed legacy peer has no local address")
+        );
+        let server = tokio::spawn(async move {
+            axum::serve(listener, app)
+                .await
+                .expect("delayed legacy peer failed");
+        });
+
+        let ok = ping_peer_readiness_with_timeout(
+            &production_http_client(),
+            &peer_url,
+            // Each response arrives within 350 ms, but the two serial requests
+            // cannot both finish within one 350 ms probe budget.
+            Duration::from_millis(350),
+        )
+        .await;
+
+        assert!(!ok, "the fallback must not start a fresh timeout budget");
+        assert_eq!(
+            health_requests.load(Ordering::Relaxed),
+            1,
+            "the delayed 404 should reach the legacy fallback"
+        );
+        server.abort();
+    }
+
+    #[tokio::test]
+    async fn ping_peer_readiness_legacy_fallback_does_not_follow_redirect() {
+        let mut server = mockito::Server::new_async().await;
+        let internal = server
+            .mock("GET", "/internal-metadata")
+            .with_status(200)
+            .expect(0)
+            .create_async()
+            .await;
+        let _ready = server
+            .mock("GET", "/ready")
+            .with_status(404)
+            .create_async()
+            .await;
         let _health = server
             .mock("GET", "/health")
             .with_status(302)
@@ -1054,33 +1807,17 @@ mod gossip_ssrf_tests {
             .create_async()
             .await;
 
-        let ok = ping_peer_health(&production_http_client(), &server.url()).await;
+        let ok = ping_peer_readiness(&production_http_client(), &server.url()).await;
 
-        assert!(!ok, "a 302 must not count as a healthy peer");
-        // expect(0) is enforced only at assert time; this fails if the redirect
-        // was followed to the internal target.
+        assert!(!ok, "the legacy fallback must not follow redirects");
         internal.assert_async().await;
     }
 
-    #[tokio::test]
-    async fn ping_peer_health_reports_success_on_200() {
-        let mut server = mockito::Server::new_async().await;
-        let _health = server
-            .mock("GET", "/health")
-            .with_status(200)
-            .create_async()
-            .await;
-
-        let ok = ping_peer_health(&production_http_client(), &server.url()).await;
-
-        assert!(ok, "a 200 /health must count as a healthy peer");
-    }
-
     // A transport error (nothing listening) must map to unhealthy, never a
     // spurious healthy — the .unwrap_or(false) arm.
     #[tokio::test]
-    async fn ping_peer_health_reports_unhealthy_on_connection_error() {
-        let ok = ping_peer_health(&production_http_client(), "http://127.0.0.1:1").await;
-        assert!(!ok, "a connection error must count as an unhealthy peer");
+    async fn ping_peer_readiness_reports_unready_on_connection_error() {
+        let ok = ping_peer_readiness(&production_http_client(), "http://127.0.0.1:1").await;
+        assert!(!ok, "a connection error must count as an unready peer");
     }
 }

crates/gitlawb-node/src/metrics.rs

@@ -57,10 +57,15 @@ static PEERS_CONNECTED: OnceLock<IntGauge> = OnceLock::new();
 /// more than once is a silent no-op. MUST be called from `main()` after
 /// the node DID is known.
 pub fn init(version: &str, node_did: &str) {
-    if REGISTRY.get().is_some() {
-        return;
-    }
+    // Guard with Once so two concurrent callers cannot both pass an unsynchronized
+    // `REGISTRY.get()` check and then race on `OnceLock::set(...).expect(...)`,
+    // panicking the loser (#192 F4). Once runs the body exactly once, so the
+    // `.expect("set X once")` calls below can never observe an already-set slot.
+    static INIT: std::sync::Once = std::sync::Once::new();
+    INIT.call_once(|| init_inner(version, node_did));
+}
 
+fn init_inner(version: &str, node_did: &str) {
     let registry = Registry::new();
 
     let info = IntGaugeVec::new(
@@ -218,6 +223,17 @@ pub fn record_fetch(repo: &str) {
     }
 }
 
+/// Test-only: current `gitlawb_fetches_total` value for `repo` (0 if the registry
+/// is not initialized). Lets api-layer tests assert the completed-fetch count with
+/// a unique label instead of scraping the encoded text.
+#[cfg(test)]
+pub fn fetch_count_for_test(repo: &str) -> u64 {
+    FETCHES
+        .get()
+        .map(|c| c.with_label_values(&[repo]).get())
+        .unwrap_or(0)
+}
+
 /// Record one HTTP signature check that passed.
 #[allow(dead_code)] // wired in a follow-up; helpers are part of the public metrics surface
 pub fn record_auth_success(route: &str) {
@@ -286,11 +302,11 @@ pub fn encode() -> Result<String, prometheus::Error> {
 mod tests {
     use super::*;
 
-    // Note: these tests are not run in parallel by default (cargo runs
-    // tests in a binary in parallel via threads but the OnceLock guard
-    // means only the first init() call succeeds; subsequent ones are
-    // no-ops). The encode test below is structured so it's safe to run
-    // alongside other tests in the same binary.
+    // Note: cargo runs tests in a binary in parallel via threads, and several
+    // tests here call init(). init() is guarded by std::sync::Once, so concurrent
+    // callers run the body exactly once and never race on the OnceLock setters
+    // (#192 F4). The encode test below is structured so it's safe to run alongside
+    // other tests in the same binary regardless of ordering.
 
     #[test]
     fn encode_after_init_returns_prometheus_text() {
@@ -321,6 +337,24 @@ mod tests {
         );
     }
 
+    /// #192 F4: `init` is idempotent and safe to call repeatedly. The panic that
+    /// hit concurrent callers (both passing the old unsynchronized `REGISTRY.get()`
+    /// check, then racing on `OnceLock::set(...).expect(...)`) is fixed by the
+    /// `Once` guard. That race is inherently non-deterministic to assert in the
+    /// shared-binary suite — a 32-thread barrier stress-test reproduces it only in
+    /// isolation (verified: RED before the `Once` fix, GREEN after). This guard
+    /// covers the deterministic half of the contract: a repeat call is a no-op,
+    /// never a panic, and the registry stays usable.
+    #[test]
+    fn init_is_idempotent_no_panic_on_repeat() {
+        init("0.0.0-a", "did:key:a");
+        init("0.0.0-b", "did:key:b");
+        assert!(
+            encode().is_ok(),
+            "registry must stay usable after a repeated init"
+        );
+    }
+
     #[test]
     fn record_helpers_are_noops_before_init() {
         // These don't panic. They also don't show up in encode() output

crates/gitlawb-node/src/rate_limit.rs

@@ -121,6 +121,28 @@ impl RateLimiter {
         true
     }
 
+    /// Non-consuming check: is this key ALREADY at its limit for the current window?
+    /// Unlike [`check`], it records nothing and never inserts a new key — used to shed
+    /// expensive preparatory work (e.g. the `/ipfs/{cid}` legacy scan's O(repos) DB
+    /// preload) BEFORE it runs, without perturbing the per-unit budget the consuming
+    /// `check` maintains (#173, F3). An unknown key or a disabled limiter is not
+    /// throttled. Prunes the key's expired timestamps as a side effect (keeps state
+    /// tidy) but adds none, so it cannot itself fill or grow the map.
+    pub(crate) async fn is_throttled(&self, key: &str) -> bool {
+        if self.max_requests == 0 {
+            return false;
+        }
+        let now = Instant::now();
+        let mut state = self.state.lock().await;
+        if let Some(window) = state.get_mut(key) {
+            window
+                .timestamps
+                .retain(|t| now.duration_since(*t) < self.window);
+            return window.timestamps.len() >= self.max_requests;
+        }
+        false
+    }
+
     pub async fn cleanup(&self) {
         let now = Instant::now();
         let mut state = self.state.lock().await;
@@ -130,6 +152,118 @@ impl RateLimiter {
             !w.timestamps.is_empty()
         });
     }
+
+    /// Number of distinct keys currently tracked. Test-only introspection so a
+    /// cross-module test can assert that a sweep actually evicted expired entries
+    /// and observe what it reclaimed. There is no production reader.
+    #[cfg(test)]
+    pub(crate) async fn tracked_keys(&self) -> usize {
+        self.state.lock().await.len()
+    }
+}
+
+/// Per-source concurrency cap derived from the write-pool size: one resolved client
+/// key (see [`client_key`]) may hold at most an eighth of the pool, so saturating it
+/// takes ~8 distinct keys. Real for an IPv4 or single-address caller; a caller with a
+/// routed IPv6 /64 has 2^64 keys, because `client_key` returns the full address with
+/// no prefix folding. Narrowing that keying is a deferred decision, so this cap is a
+/// bound per key, not a bound per operator.
+///
+/// Floored at 1 because the value feeds [`PerCallerConcurrency`], where a cap of 0
+/// would shed EVERY receive-pack advertisement and break all pushes. The floor is
+/// load-bearing at the minimum write-pool size (1), which integer-divides to 0.
+pub(crate) fn per_source_push_cap(max_concurrent_git_pushes: usize) -> usize {
+    (max_concurrent_git_pushes / 8).max(1)
+}
+
+/// A bounded per-caller CONCURRENCY limiter — distinct from [`RateLimiter`], which
+/// caps request RATE. Each caller key may hold at most `per_caller` in-flight
+/// permits at once; beyond that [`try_acquire`](Self::try_acquire) returns `None`
+/// and the caller sheds. Used to stop one caller (a single anonymous source-IP or
+/// DID) monopolizing the served-git read pool (#174).
+///
+/// The key map is self-bounding: a key is removed the instant its in-flight count
+/// reaches zero, so it never holds more keys than there are concurrently-active
+/// callers (itself bounded by the read semaphore). A `max_keys` reject-before-insert
+/// backstop guarantees a key farm can never grow the map even if that invariant
+/// weakened — a NEW key at the cap is rejected WITHOUT allocating an entry (INV-15).
+///
+/// Uses a `std::sync::Mutex` (not the file's `tokio::sync::Mutex`) because the
+/// permit's `Drop` must release synchronously; the critical section holds no await.
+#[derive(Clone)]
+pub struct PerCallerConcurrency {
+    state: Arc<std::sync::Mutex<HashMap<String, usize>>>,
+    per_caller: usize,
+    max_keys: usize,
+}
+
+/// RAII permit from [`PerCallerConcurrency::try_acquire`]. On drop it decrements
+/// the caller's in-flight count and removes the key when it reaches zero.
+pub struct PerCallerPermit {
+    state: Arc<std::sync::Mutex<HashMap<String, usize>>>,
+    key: String,
+}
+
+impl PerCallerConcurrency {
+    pub fn new(per_caller: usize, max_keys: usize) -> Self {
+        Self {
+            state: Arc::new(std::sync::Mutex::new(HashMap::new())),
+            per_caller: per_caller.max(1),
+            max_keys: max_keys.max(1),
+        }
+    }
+
+    /// Convenience constructor with the default key bound.
+    pub fn with_default_max_keys(per_caller: usize) -> Self {
+        Self::new(per_caller, DEFAULT_MAX_KEYS)
+    }
+
+    /// `Some(permit)` when the caller is under its cap and the map has room;
+    /// `None` (shed) otherwise. Reject-before-insert: a new key at `max_keys` is
+    /// rejected without allocating.
+    pub fn try_acquire(&self, key: &str) -> Option<PerCallerPermit> {
+        // Recover from a poisoned lock rather than panicking: the critical section
+        // is pure counter arithmetic and cannot itself panic, so a poisoned mutex
+        // would only ever come from an unrelated abort, and a slightly-off count
+        // self-heals as permits drop. A panic here would instead brick the limiter
+        // for every caller (each subsequent lock re-panics).
+        let mut map = self.state.lock().unwrap_or_else(|e| e.into_inner());
+        match map.get_mut(key) {
+            Some(count) => {
+                if *count >= self.per_caller {
+                    return None;
+                }
+                *count += 1;
+            }
+            None => {
+                if map.len() >= self.max_keys {
+                    return None;
+                }
+                map.insert(key.to_string(), 1);
+            }
+        }
+        Some(PerCallerPermit {
+            state: self.state.clone(),
+            key: key.to_string(),
+        })
+    }
+
+    #[cfg(test)]
+    pub fn tracked_keys(&self) -> usize {
+        self.state.lock().unwrap().len()
+    }
+}
+
+impl Drop for PerCallerPermit {
+    fn drop(&mut self) {
+        let mut map = self.state.lock().unwrap_or_else(|e| e.into_inner());
+        if let Some(count) = map.get_mut(&self.key) {
+            *count -= 1;
+            if *count == 0 {
+                map.remove(&self.key);
+            }
+        }
+    }
 }
 
 pub async fn rate_limit_by_did(request: Request, next: Next) -> Response {
@@ -288,6 +422,63 @@ pub async fn rate_limit_by_ip(request: Request, next: Next) -> Response {
 mod tests {
     use super::*;
 
+    #[test]
+    fn per_caller_concurrency_caps_one_caller_and_frees_on_drop() {
+        let lim = PerCallerConcurrency::new(2, 100);
+        let p1 = lim.try_acquire("did:key:zA").expect("first under cap");
+        let p2 = lim.try_acquire("did:key:zA").expect("second under cap");
+        assert!(
+            lim.try_acquire("did:key:zA").is_none(),
+            "a third in-flight op for the same caller sheds (over the per-caller cap)"
+        );
+        // A DIFFERENT caller is unaffected — the cap is per-caller, not global.
+        let _other = lim
+            .try_acquire("did:key:zB")
+            .expect("a different caller has its own budget");
+        drop(p1);
+        assert!(
+            lim.try_acquire("did:key:zA").is_some(),
+            "freeing one in-flight slot lets the same caller back in"
+        );
+        drop(p2);
+    }
+
+    #[test]
+    fn per_caller_concurrency_map_is_self_bounding_and_reject_before_insert() {
+        // Self-bounding: acquire+drop many distinct keys — the map never grows
+        // because a key is removed the instant its in-flight count hits zero.
+        let lim = PerCallerConcurrency::new(4, 3);
+        for i in 0..50 {
+            let _p = lim.try_acquire(&format!("k{i}"));
+        }
+        assert_eq!(
+            lim.tracked_keys(),
+            0,
+            "keys with zero in-flight ops are removed, so an acquire+drop flood leaves the map empty"
+        );
+        // Reject-before-insert: HOLD max_keys distinct keys, then a new key sheds
+        // WITHOUT growing the map past the cap (INV-15 — a rejected request never
+        // allocates an entry).
+        let held: Vec<_> = (0..3)
+            .map(|i| lim.try_acquire(&format!("h{i}")).unwrap())
+            .collect();
+        assert_eq!(
+            lim.tracked_keys(),
+            3,
+            "three distinct callers held concurrently"
+        );
+        assert!(
+            lim.try_acquire("h3").is_none(),
+            "a new key at max_keys is rejected"
+        );
+        assert_eq!(
+            lim.tracked_keys(),
+            3,
+            "the rejected new key did not allocate an entry (reject-before-insert)"
+        );
+        drop(held);
+    }
+
     #[tokio::test]
     async fn allows_within_limit() {
         let limiter = RateLimiter::new(3, Duration::from_secs(60));

crates/gitlawb-node/src/server.rs

@@ -14,7 +14,7 @@ use tracing::Level;
 
 use crate::api::{
     agents, arweave, bounties, certs, changelog, events, ipfs, issues, labels, peers, profiles,
-    protect, pulls, register, replicas, repos, resolve, stars, status, tasks, visibility, webhooks,
+    protect, pulls, register, replicas, repos, resolve, stars, tasks, visibility, webhooks,
 };
 use crate::auth;
 use crate::rate_limit;
@@ -183,64 +183,6 @@ pub fn build_router(state: AppState) -> Router {
         state.clone(),
     );
 
-    // ── Status claim writes — signature, plus the per-DID throttle AND the
-    // per-IP flood brake `creation_routes` carries. Not in `write_routes`, which
-    // has neither: every call here appends a row, so an unthrottled writer grows
-    // the claim log on demand and the three per-repo caps would be the only bound.
-    let status_write_routes = add_auth_layers(
-        Router::new()
-            .route(
-                "/api/v1/repos/{owner}/{repo}/statuses/{sha}",
-                post(status::create_status),
-            )
-            .layer(middleware::from_fn(rate_limit::rate_limit_by_did))
-            .layer(axum::Extension(state.rate_limiter.clone())),
-        state.clone(),
-    )
-    // The route's advertised body bound, applied at the transport. It sits
-    // OUTSIDE the auth layers because `require_signature` collects and hashes
-    // the whole body before any handler runs: the handler's own check measures
-    // an allocation that has already happened, so without this layer the 8 KiB
-    // figure bounded what gets stored and not what gets buffered, and
-    // concurrent requests multiplied exactly the cost it was written to
-    // prevent. It sits INSIDE the rate limiters so an oversized request is
-    // still counted by the per-IP brake before it is refused.
-    //
-    // A declared Content-Length over the limit is answered 413 without reading
-    // a byte; a body that declares nothing (or understates) is truncated at the
-    // limit and fails where it is read, which `require_signature` reports as an
-    // unreadable body.
-    .layer(RequestBodyLimitLayer::new(status::MAX_REQUEST_BODY_BYTES))
-    // The one route that persists the signed request body, so the one route
-    // whose signature material carries it. Applied OUTSIDE `add_auth_layers`
-    // (outermost = runs first) because `require_signature` reads this marker to
-    // decide whether to carry the body; a layer added inside the auth pair runs
-    // after the middleware and is never seen. `create_status` refuses an absent
-    // body rather than storing an empty column, so getting this order wrong
-    // fails loudly instead of quietly writing unverifiable claims.
-    .layer(axum::Extension(auth::PersistsSignedBody))
-    .layer(middleware::from_fn(rate_limit::rate_limit_by_ip))
-    .layer(axum::Extension(rate_limit::IpRateLimiter {
-        limiter: state.create_ip_rate_limiter.clone(),
-        trust: state.push_limiter_trust,
-    }));
-
-    // ── Status claim reads — open, behind `optional_signature` so the handler
-    // sees the caller when one signs and still answers a public repo for an
-    // anonymous reader. Without the layer the handler's optional auth extension
-    // is None for EVERY caller, including the owner, and every private repo
-    // reads as not-found.
-    let status_read_routes = Router::new()
-        .route(
-            "/api/v1/repos/{owner}/{repo}/commits/{sha}/status",
-            get(status::commit_status),
-        )
-        .route(
-            "/api/v1/repos/{owner}/{repo}/pulls/{number}/status",
-            get(status::pull_request_status),
-        )
-        .layer(middleware::from_fn(auth::optional_signature));
-
     // Body limit is raised to GITLAWB_MAX_PACK_BYTES (default 2 GB) for git
     // routes only — all other API routes keep axum's default 2 MB cap.
     // HTTP Signature is enforced on receive-pack (push) — the git-remote-gitlawb
@@ -272,9 +214,20 @@ pub fn build_router(state: AppState) -> Router {
     // identity and can apply per-repo visibility (#110); anonymous callers stay
     // anonymous and still read genuinely public content. `/api/v1/ipfs/pins`
     // stays unsigned — gating the pin index is tracked separately (#121).
+    // `/ipfs/{cid}` also carries a per-IP flood brake: it is anon-reachable and each
+    // request can drive a full-history git walk, so the per-IP rate limiter is the
+    // outermost layer (rejects a flood before the walk-admission work), mirroring the
+    // push/create routers. The extension MUST be attached or rate_limit_by_ip is a
+    // silent no-op. `/api/v1/ipfs/pins` (no walk) is merged in unbraked, as before.
+    let ipfs_limiter = rate_limit::IpRateLimiter {
+        limiter: state.ipfs_rate_limiter.clone(),
+        trust: state.push_limiter_trust,
+    };
     let ipfs_routes = Router::new()
         .route("/ipfs/{cid}", get(ipfs::get_by_cid))
         .layer(middleware::from_fn(auth::optional_signature))
+        .layer(middleware::from_fn(rate_limit::rate_limit_by_ip))
+        .layer(axum::Extension(ipfs_limiter))
         .merge(Router::new().route("/api/v1/ipfs/pins", get(ipfs::list_pins)));
 
     // ── Arweave permanent anchors ──────────────────────────────────────────
@@ -431,10 +384,6 @@ pub fn build_router(state: AppState) -> Router {
             "/api/v1/repos/{owner}/{repo}/events",
             get(events::list_repo_events),
         )
-        .route(
-            "/api/v1/repos/{owner}/{repo}/push-events",
-            get(events::list_repo_push_events),
-        )
         .route("/api/v1/agents", get(agents::list_agents))
         .route("/api/v1/agents/{did}", get(agents::show_agent))
         .route("/api/v1/agents/{did}/trust", get(agents::get_trust))
@@ -531,8 +480,6 @@ pub fn build_router(state: AppState) -> Router {
         .merge(profile_write_routes)
         .merge(creation_routes)
         .merge(write_routes)
-        .merge(status_write_routes)
-        .merge(status_read_routes)
         .merge(git_write_routes)
         .merge(git_read_routes)
         .merge(issue_write_routes)

crates/gitlawb-node/src/sync.rs

@@ -605,7 +605,7 @@ async fn replicate_encrypted_blobs(
                 continue;
             }
         };
-        match crate::ipfs_pin::pin_git_object(ipfs_api, &blob.oid, &envelope).await {
+        match crate::ipfs_pin::pin_git_object(ipfs_api, &blob.oid, &envelope, None).await {
             Ok(cid) if !cid.is_empty() => {
                 if cid != blob.cid {
                     warn!(oid = %blob.oid, expected = %blob.cid, got = %cid, "replicated envelope CID mismatch; skipping record");

crates/gitlawb-node/src/visibility.rs

@@ -437,6 +437,31 @@ mod tests {
         );
     }
 
+    // #135 T1: a Mode-B rule on `/secret/**` must DENY the withheld directory's
+    // OWN path `/secret` (the `path == prefix` arm), not just strict descendants —
+    // otherwise get_by_cid's tree gate would serve the /secret tree object and leak
+    // its children. Pins parity with get_tree, which denies the /secret path.
+    #[test]
+    fn subtree_rule_denies_the_withheld_directory_itself() {
+        let reader = "did:key:z6MkReader";
+        let rules = [rule("/secret/**", VisibilityMode::B, &[reader])];
+        assert_eq!(
+            visibility_check(&rules, true, OWNER, None, "/secret"),
+            Decision::Deny,
+            "anon denied at the withheld directory's OWN path /secret"
+        );
+        assert_eq!(
+            visibility_check(&rules, true, OWNER, None, "/public"),
+            Decision::Allow,
+            "anon allowed at a sibling path outside the withheld subtree"
+        );
+        assert_eq!(
+            visibility_check(&rules, true, OWNER, Some(reader), "/secret"),
+            Decision::Allow,
+            "listed reader allowed at the withheld directory (caller-aware)"
+        );
+    }
+
     // #153 regression: cross-method DID must still be denied even when the
     // trailing segment collides with a bare owner key.
     #[test]

crates/gitlawb-node/tests/inv22_gates.rs

@@ -0,0 +1,573 @@
+//! #174 U6 — INV-22 completeness guard (rung-raising).
+//!
+//! INV-22: a permit held per op recovers only if every path that holds it is also
+//! duration-bounded and reaps the process group before releasing admission, and every
+//! detached git/blocking task carries its own admission. PR #174 fixed five paths
+//! (U1-U5) that violated this. Each fix has a per-unit RED/GREEN regression; together
+//! those form the five-revert matrix. This guard adds the missing piece: a source-scan
+//! tripwire that fails when a NEW site reintroduces the class, or when one of the five
+//! gates is removed.
+//!
+//! It lives in `tests/` (a separate crate) on purpose: a guard that scanned the same
+//! file it lives in would match its own identifier literals and pass vacuously. Here
+//! the scanned `src/` files never contain this file's literals, so each check is
+//! load-bearing — reverting the named gate turns the assertion red.
+//!
+//! These are deliberately coarse structural checks, not a parser. They cannot prove a
+//! gate is *correct* (the per-unit tests do that); they prove a gate is *present and
+//! not bypassed*, which is what stops the class from silently regressing.
+
+use std::path::Path;
+
+fn src(rel: &str) -> String {
+    let p = Path::new(env!("CARGO_MANIFEST_DIR")).join("src").join(rel);
+    std::fs::read_to_string(&p).unwrap_or_else(|e| panic!("read {}: {e}", p.display()))
+}
+
+#[test]
+fn inv22_concurrency_gates_present_and_not_bypassed() {
+    let repos = src("api/repos.rs");
+    let smart_http = src("git/smart_http.rs");
+    let vis = src("git/visibility_pack.rs");
+    let ipfs = src("api/ipfs.rs");
+
+    // U1 / P1-a: run_bounded_git stands the watchdog down only after confirming the
+    // child actually terminated (WNOWAIT), not on the raw stdout-drain EOF — otherwise
+    // a child that closes stdout then hangs pins the permit past the deadline. The
+    // probe is defined and called, so >= 2 occurrences; reverting the fix removes both.
+    assert!(
+        vis.matches("child_terminated_without_reaping").count() >= 2,
+        "U1/P1-a gate missing: run_bounded_git must confirm child exit via \
+         child_terminated_without_reaping before signalling the watchdog"
+    );
+
+    // U2 / P1-c: on client disconnect KillGroupOnDrop must launch a detached reaper
+    // that runs the full TERM/grace/KILL/reap, not a lone SIGTERM. The reaper is spawned
+    // via a runtime handle in Drop; `Handle::try_current` is unique to that launch (the
+    // timeout path already has an async context and never calls it).
+    assert!(
+        smart_http.contains("Handle::try_current"),
+        "U2/P1-c gate missing: KillGroupOnDrop::drop must launch the full \
+         TERM/grace/KILL reaper on disconnect (Handle::try_current), not a lone SIGTERM"
+    );
+
+    // U4 / P1-d: git_receive_pack must acquire the per-source write sub-cap before the
+    // global write permit. The acquire reads `state.git_write_per_caller`; comments name
+    // the field without the `state.` prefix, so this targets the real acquire site.
+    assert!(
+        repos.contains("state.git_write_per_caller"),
+        "U4/P1-d gate missing: git_receive_pack must acquire the per-source write cap \
+         (state.git_write_per_caller) before the global write permit"
+    );
+
+    // U5 / P1-e: the detached post-push encryption walk must run through the
+    // admission-gated helper, which is wired to the shared encrypt pool.
+    assert!(
+        repos.contains("fn withheld_recipients_gated")
+            && repos.contains("state.git_encrypt_semaphore"),
+        "U5/P1-e gate missing: the encryption walk must run through \
+         withheld_recipients_gated, which acquires git_encrypt_semaphore"
+    );
+
+    // U1 / R2 (#173 round-10): the path-scoped filtered-pack serve must thread the
+    // caller's AdmissionGuard through BOTH git stages so read + per-caller admission is
+    // held until the pack-objects group is reaped on disconnect, closing the cap bypass
+    // the plain upload_pack path already fixed. Two load-bearing markers: rev-list hands
+    // the disarmed guard back (its tuple return type), and build_filtered_pack forwards
+    // that guard into the pack-objects stage (the `admission` arg after the
+    // "pack-objects" label). Reverting either — dropping the guard between stages, or
+    // passing `None` to pack-objects — trips this.
+    assert!(
+        smart_http.contains("Result<(Vec<String>, Option<AdmissionGuard>)>")
+            && smart_http.contains("\"pack-objects\",\n        admission,"),
+        "U1/R2 gate missing: build_filtered_pack must thread the AdmissionGuard through \
+         rev-list -> pack-objects so the permits are held until the pack-objects group \
+         is reaped on disconnect (the path-scoped half of #174 P1-a)"
+    );
+
+    // U2 / R1: a cancelled or timed-out `GET /ipfs/{cid}` must release admission only
+    // after the blocking work it admitted has finished, not the instant the handler
+    // future drops (the /ipfs half of #174 P1-a). The mechanism is the shared
+    // `Arc<WalkAdmission>`: both walk permits are moved into it once per request and a
+    // clone rides every `spawn_blocking`, so the permits release when the LAST holder
+    // drops. Reverting to handler-local permits trips this; the per-site clones are
+    // bound separately by `inv22_ipfs_walk_admission_reaches_every_blocking_site`.
+    //
+    // This previously required the permits to be owned by a detached `tokio::spawn`
+    // running the whole pipeline. That closed the same bypass but kept an abandoned
+    // request's full legacy scan running against a held slot, so the merge of #173 and
+    // #174 kept the Arc and dropped the detached task.
+    assert!(
+        ipfs.contains("struct WalkAdmission")
+            && ipfs.contains("let admission = std::sync::Arc::new(WalkAdmission {"),
+        "U2/R1 gate missing: get_by_cid must move both /ipfs admission permits into a \
+         shared Arc<WalkAdmission> whose clones ride the blocking work, so admission is \
+         released only once that work completes (the /ipfs half of #174 P1-a)"
+    );
+
+    // U2 / KTD2 (#173 round-10): the probe/read children on the /ipfs path must be the
+    // duration-bounded twins (process-group teardown via run_bounded_git), not the bare
+    // `store::object_type` / `read_object_content` (or an unbounded `cat-file -s`) a tokio
+    // timeout cannot cancel — otherwise a wedged cat-file lingers and pins the held
+    // admission past the deadline. Reverting any twin call site back to a bare read trips
+    // this.
+    assert!(
+        ipfs.contains("object_type_bounded(")
+            && ipfs.contains("object_size_bounded(")
+            && ipfs.contains("read_object_content_bounded("),
+        "U2/KTD2 gate missing: the /ipfs probe+read must call the run_bounded_git-backed \
+         *_bounded twins so a wedged cat-file is reaped at the deadline, not left to pin \
+         the held /ipfs walk admission"
+    );
+
+    // P1-e non-bypass tripwire: the bounded recipients walk is spawn_blocking'd nowhere
+    // but inside withheld_recipients_gated. A second call site (count > 1) is a new
+    // detached git walk that skips the admission gate — exactly the class U5 closed.
+    assert_eq!(
+        repos.matches("withheld_blob_recipients_bounded").count(),
+        1,
+        "P1-e bypass: the bounded recipients walk must be invoked only inside \
+         withheld_recipients_gated; a new call site bypasses the encrypt-walk admission cap"
+    );
+
+    // U4 / P2-2: the detached post-push encryption task must be gated by the per-repo
+    // coalescing set (`encrypt_inflight.try_begin`) so the OUTSTANDING parked-task set is
+    // bounded to <=1 per repo. Removing the gate lets N rapid pushes spawn N parked
+    // waiters (the unbounded set U4 closed); the semaphore only caps active walks.
+    assert!(
+        repos.contains("state.encrypt_inflight.try_begin"),
+        "U4/P2-2 gate missing: the detached post-push encryption spawn must consult \
+         encrypt_inflight.try_begin to coalesce per repo (bound the outstanding-task set)"
+    );
+
+    // F5: coalescing must REQUEUE, not shed. The in-flight task pins only its own
+    // pre-spawn snapshot, so a coalesced push's tip pairs are recorded on its key and
+    // the task must loop-drain them (`finish_or_take_pending`) before releasing it.
+    // Removing the drain reverts to the silent loss: a coalesced push's pins and
+    // recovery copies are absent until an unrelated later push. Scan only the
+    // production half of the file — the u5 tests in its `mod tests` also name the
+    // drain call, and matching them would make this check vacuous.
+    // Split at the TEST MODULE, not at the first `#[cfg(test)]`. api/repos.rs carries
+    // test-only items (the drain fault seam, the task entry point) ABOVE the production
+    // code these gates scan for, so splitting on the attribute truncated the production
+    // half above every line being checked and the gate went vacuously blind.
+    let repos_production = repos
+        .split("\nmod tests {")
+        .next()
+        .expect("split always yields a first chunk");
+    assert!(
+        repos_production.contains("finish_or_take_pending"),
+        "F5 gate missing: the post-push encryption task must loop-drain coalesced \
+         pushes via finish_or_take_pending before releasing its repo key"
+    );
+
+    // F4: every post-receive scan helper admits itself to the shared scan pool via
+    // `crate::state::acquire_scan_permit` BEFORE its spawn_blocking git walk, so a
+    // push burst cannot accumulate unbounded concurrent scans once the write permit
+    // is released. Two halves, both load-bearing: the helper body must actually
+    // acquire the pool (state.rs sits the helper at the end of the file, so the
+    // definition tail contains no other `acquire_owned` to match vacuously), and
+    // within each scan helper the first qualified call precedes the first
+    // `spawn_blocking`. Severing a call site pushes the next occurrence past the
+    // helper's own `spawn_blocking` (or off the end of the file), turning the
+    // assertion red; comments name the helper without the `crate::state::` prefix,
+    // so this targets the real call sites.
+    let state_rs = src("state.rs");
+    let helper_def = state_rs
+        .find("fn acquire_scan_permit")
+        .expect("F4 gate missing: state.rs no longer defines acquire_scan_permit");
+    assert!(
+        state_rs[helper_def..].contains("acquire_owned"),
+        "F4 gate gutted: acquire_scan_permit must acquire the scan pool via acquire_owned"
+    );
+    let push_delta = src("git/push_delta.rs");
+    for (file_src, file, helper) in [
+        (&repos, "api/repos.rs", "fn replication_withheld_set"),
+        (&repos, "api/repos.rs", "fn fail_closed_full_scan_objects"),
+        (
+            &push_delta,
+            "git/push_delta.rs",
+            "fn resolve_candidates_for_push",
+        ),
+    ] {
+        let start = file_src
+            .find(helper)
+            .unwrap_or_else(|| panic!("{file}: `{helper}` not found"));
+        let tail = &file_src[start..];
+        let acquire = tail
+            .find("crate::state::acquire_scan_permit(")
+            .unwrap_or_else(|| {
+                panic!("F4 gate missing: {file} `{helper}` no longer acquires a scan permit")
+            });
+        let spawn = tail.find("spawn_blocking").unwrap_or_else(|| {
+            panic!("{file}: `{helper}` lost its spawn_blocking walk — update this guard")
+        });
+        assert!(
+            acquire < spawn,
+            "F4 gate bypassed: {file} `{helper}` must acquire its git_encrypt_semaphore \
+             permit BEFORE dispatching the blocking git scan"
+        );
+    }
+}
+
+/// F4 (repo_store advisory-unlock cancellation safety): `RepoWriteGuard::release`
+/// must await `pg_advisory_unlock` while `self` still owns the pooled connection,
+/// and must not mark itself `released` until that await resolves. Either shape,
+/// reintroduced, re-opens the mid-unlock cancellation leak: taking the connection
+/// early leaves `Drop` with `conn == None`, and setting `released = true` early
+/// leaves the `Drop` backstop inert — both strand the session lock on cancellation.
+///
+/// Scoped to the `release` fn body: the `Drop` impl legitimately takes the
+/// connection and unlocks, so a whole-file scan would match it and read as a false
+/// pass. Reverting either ordering turns this red (proven load-bearing).
+#[test]
+fn f4_release_keeps_conn_owned_until_unlock_resolves() {
+    let repo_store = src("git/repo_store.rs");
+
+    let rel_start = repo_store
+        .find("pub async fn release(mut self")
+        .expect("F4 gate: repo_store.rs no longer defines RepoWriteGuard::release");
+    let rel_end = repo_store[rel_start..]
+        .find("impl Drop for RepoWriteGuard")
+        .map(|off| rel_start + off)
+        .expect("F4 gate: release fn / Drop impl markers moved — update this guard");
+    let release_body = &repo_store[rel_start..rel_end];
+
+    let unlock = release_body
+        .find("pg_advisory_unlock")
+        .expect("F4 gate: release must still issue pg_advisory_unlock");
+    let before_unlock = &release_body[..unlock];
+
+    // (a) the connection must still be owned by `self` at the unlock await.
+    assert!(
+        !before_unlock.contains("self.conn.take()"),
+        "F4 regression: RepoWriteGuard::release takes self.conn BEFORE awaiting \
+         pg_advisory_unlock. A cancellation during the unlock await then strands the \
+         session advisory lock (Drop sees conn == None and skips its backstop). \
+         Unlock through the still-owned connection instead."
+    );
+    // (b) `released` must not be set before the unlock await — the other
+    // reintroduction shape a single-reorder check on (a) alone is blind to.
+    assert!(
+        !before_unlock.contains("released = true"),
+        "F4 regression: RepoWriteGuard::release sets `released = true` BEFORE awaiting \
+         pg_advisory_unlock. A cancellation during the await then leaves the Drop \
+         backstop inert (it early-returns on released). Set released only AFTER the \
+         unlock await resolves."
+    );
+}
+
+/// F6/KTD-5 (initial IPFS metadata queries deadline-wrapped): `get_by_cid` acquires
+/// the scarce walk permits (RAII, held for the whole request) BEFORE its two initial
+/// metadata queries, and the per-repo loop's first budget gate runs only later. So
+/// both `list_all_repos` and `list_visibility_rules_for_repos` must be clamped to the
+/// remaining request budget — otherwise a query blocked in Postgres pins the walk slot
+/// for the whole stall, past the budget. This scans the PRODUCTION half of `api/ipfs.rs`
+/// (the `mod tests` half names the same calls in its own harness and would make the
+/// check vacuous) and asserts each query call is immediately preceded by a
+/// `tokio::time::timeout(` wrapper. Removing either wrapper turns this red (proven
+/// load-bearing).
+#[test]
+fn f6_ipfs_metadata_queries_are_deadline_wrapped() {
+    let ipfs = src("api/ipfs.rs");
+    // Split at the TEST MODULE, not at the first `#[cfg(test)]`: the handler carries
+    // in-line `#[cfg(test)]` query counters, so splitting on the attribute cut the
+    // production half off above the calls this guard exists to check and the scan went
+    // vacuously quiet (found 0 of each rather than failing on a missing wrapper).
+    let production = ipfs
+        .split("\nmod tests {")
+        .next()
+        .expect("split always yields a first chunk");
+
+    // EVERY occurrence must be wrapped, not just the first. The handler now reaches
+    // these queries from two places (the provenance fast path, one repo at a time, and
+    // the legacy scan's preload), and an exact-count check would have to be relaxed
+    // every time a call site is added, which is how a guard quietly stops covering the
+    // site that matters. Requiring all of them scales with the code instead.
+    for call in [
+        ".list_all_repos()",
+        ".list_visibility_rules_for_repos(",
+        ".get_repo_by_id(",
+        ".is_repo_quarantined(",
+    ] {
+        let occurrences = production.matches(call).count();
+        assert!(
+            occurrences >= 1,
+            "F6 guard stale: api/ipfs.rs no longer calls `{call}` — update this guard"
+        );
+        for (n, (idx, _)) in production.match_indices(call).enumerate() {
+            // The wrapper opens a few lines above the call (match tokio::time::timeout(
+            // ... remaining budget ..., <query> )); a 240-char lookback covers it
+            // without reaching the previous statement.
+            let window = &production[idx.saturating_sub(240)..idx];
+            assert!(
+                window.contains("tokio::time::timeout("),
+                "F6 gate missing: occurrence {n} of `{call}` (of {occurrences}) is not \
+                 wrapped in tokio::time::timeout(...) clamped to the remaining request \
+                 budget. An unwrapped await pins the held walk permit for the whole DB \
+                 stall, past GITLAWB_IPFS_REQUEST_BUDGET_SECS."
+            );
+        }
+    }
+}
+
+/// #174 F2 / KTD-3: the detached post-receive Pinata replication task must enqueue
+/// only the push's `(ref, old, new)` tuples and RE-DERIVE its object set inside the
+/// worker once a pin slot frees — it must NOT move the full per-push object list into
+/// the closure and hold it across the `pin_semaphore` acquire. Retaining the list makes
+/// every parked task (under a slow Pinata backend) hold an MB-scale OID list, so
+/// outstanding memory grows O(pushes x object-list). Coalescing/shedding the task is
+/// forbidden (its per-ref effects are non-idempotent), so the fix bounds the retained
+/// data, not the task count.
+///
+/// Two load-bearing checks, both against the PRODUCTION half of `api/repos.rs` (the
+/// `mod tests` half names the same identifiers in its own harness and would make the
+/// scan vacuous): (a) the closure-local `object_list_pinata` binding — the retain form —
+/// must be gone; reintroducing `let object_list_pinata = object_list;` turns this red.
+/// (b) the re-derivation (`pinata_object_list_for_refs`) must appear AFTER the Pinata
+/// pin permit is acquired, so the object list is materialized only inside the pin-bounded
+/// section and a parked task holds O(ref tuples).
+#[test]
+fn f2_pinata_enqueues_refs_not_retained_object_lists() {
+    let repos = src("api/repos.rs");
+    // Split at the TEST MODULE, not at the first `#[cfg(test)]`. api/repos.rs carries
+    // test-only items (the drain fault seam, the task entry point) ABOVE the production
+    // code these gates scan for, so splitting on the attribute truncated the production
+    // half above every line being checked and the gate went vacuously blind.
+    let production = repos
+        .split("\nmod tests {")
+        .next()
+        .expect("split always yields a first chunk");
+
+    // (a) the retained-list form must be gone from production.
+    assert!(
+        !production.contains("object_list_pinata"),
+        "F2/KTD-3 regression: the Pinata task retains a full per-push object list \
+         (`object_list_pinata`) across the pin-permit acquire. Enqueue only the ref \
+         tuples and re-derive the object set inside the worker (pinata_object_list_for_refs)."
+    );
+
+    // (b) the re-derivation runs AFTER the pin permit is acquired. Anchor on the
+    // Pinata pin-admission clone so the window is the Pinata task, not the sibling
+    // IPFS/encrypt spawn (which shares `pin_semaphore` but never re-derives).
+    let anchor = production
+        .find("let pin_sem_pinata")
+        .expect("F2 gate stale: the Pinata pin-admission clone (pin_sem_pinata) moved");
+    let tail = &production[anchor..];
+    let acquire = tail
+        .find(".acquire_owned()")
+        .expect("F2 gate: the Pinata task no longer acquires a pin permit (acquire_owned)");
+    let rederive = tail.find("pinata_object_list_for_refs(").expect(
+        "F2 gate missing: the Pinata task must re-derive its object set via \
+         pinata_object_list_for_refs; it can no longer move a pre-resolved list into the closure",
+    );
+    assert!(
+        acquire < rederive,
+        "F2 gate bypassed: the Pinata object-set re-derivation must run AFTER the pin \
+         permit is acquired, so a parked task never holds the MB-scale object list"
+    );
+
+    // The re-derivation is driven by the push's ref tuples (the enqueued unit), not a
+    // retained object list — tie "enqueue ref_updates" to the call explicitly.
+    assert!(
+        tail[rederive..].starts_with("pinata_object_list_for_refs(")
+            && tail[rederive..]
+                .get(..400)
+                .map(|w| w.contains("ref_updates_clone"))
+                .unwrap_or(false),
+        "F2 gate: pinata_object_list_for_refs must re-derive from the push's ref tuples \
+         (ref_updates_clone), the small unit the parked task retains"
+    );
+}
+
+/// #174 U2 / F3 (second same-repo writer serialized until a disconnected first push's
+/// git group is reaped): `git_receive_pack` must take the per-repo in-process write
+/// lease and CARRY it on the write-path `AdmissionGuard` (via `.with_lease`), so the
+/// lease rides `KillGroupOnDrop`'s detached reaper and frees only after the group is
+/// reaped — supplementing the pg advisory lock, which `RepoWriteGuard::Drop` releases at
+/// the disconnect instant. Tying the lease to `RepoWriteGuard` instead (or dropping the
+/// `.with_lease` carry) reopens the race; the behavioral RED/GREEN test
+/// (`f3_second_push_serialized_until_disconnected_group_reaped`) is the real bar, this
+/// is the completeness tripwire. Scanned against the PRODUCTION half of `api/repos.rs`
+/// (the `mod tests` half names these identifiers in its own harness).
+#[test]
+fn f3_second_writer_leased_until_reap() {
+    let repos = src("api/repos.rs");
+    let smart_http = src("git/smart_http.rs");
+    // Split at the TEST MODULE, not at the first `#[cfg(test)]`. api/repos.rs carries
+    // test-only items (the drain fault seam, the task entry point) ABOVE the production
+    // code these gates scan for, so splitting on the attribute truncated the production
+    // half above every line being checked and the gate went vacuously blind.
+    let repos_production = repos
+        .split("\nmod tests {")
+        .next()
+        .expect("split always yields a first chunk");
+
+    // The lease is acquired, then carried by the AdmissionGuard (.with_lease), before
+    // receive_pack runs the write. Severing any of the three turns this red.
+    let lease_acquire = repos_production.find("repo_write_leases").expect(
+        "F3 gate missing: git_receive_pack no longer takes the per-repo write lease \
+         (state.repo_write_leases)",
+    );
+    let with_lease = repos_production.find(".with_lease(").expect(
+        "F3 gate missing: the write-path AdmissionGuard no longer carries the lease \
+         (.with_lease). The lease must ride the disconnect reaper via the AdmissionGuard, \
+         NOT RepoWriteGuard (which drops at the disconnect instant, reopening F3).",
+    );
+    let receive = repos_production
+        .find("smart_http::receive_pack(")
+        .expect("F3 gate stale: git_receive_pack no longer calls smart_http::receive_pack");
+    assert!(
+        lease_acquire < with_lease && with_lease < receive,
+        "F3 gate bypassed: the write lease must be acquired, then carried by the \
+         AdmissionGuard (.with_lease), BEFORE receive_pack runs the write"
+    );
+
+    // The AdmissionGuard must actually hold the lease (Option<RepoWriteLease>) via a
+    // with_lease setter, so it travels into the detached reaper. Removing the field or
+    // method turns this red.
+    assert!(
+        smart_http.contains("_lease: Option<crate::state::RepoWriteLease>")
+            && smart_http.contains("pub fn with_lease("),
+        "F3 gate missing: AdmissionGuard must hold an Option<RepoWriteLease> set via \
+         with_lease, so the lease rides the guard into KillGroupOnDrop's reaper"
+    );
+}
+
+/// #174 U1 — every blocking walk in the `/ipfs` scan carries the request's walk
+/// admission.
+///
+/// The admission is an `Arc<WalkAdmission>` cloned into each `spawn_blocking`
+/// closure, so the global + per-source permits release only when the last holder
+/// drops: a client disconnect leaves the abandoned closure holding the slot, and a
+/// panicking closure leaves the handler holding it.
+///
+/// Only the walk site runs under `state.git_bin`, so only it can be pinned by the
+/// fake-git harness and mutation-verified dynamically (see
+/// `get_by_cid_walk_permit_held_through_blocking_walk`). The probe and the content
+/// read deliberately shell to the real `git`, which is why this structural check
+/// exists: it binds all three sites, and any blocking site added to this loop
+/// later, without reversing that deliberate independence.
+///
+/// MUTATION (RED): delete any one `Arc::clone(ctx.admission)` binding, or drop the
+/// clone from inside its closure, and the count falls below three.
+#[test]
+fn inv22_ipfs_walk_admission_reaches_every_blocking_site() {
+    let ipfs = src("api/ipfs.rs");
+
+    // The shared owner must exist and be built once per request.
+    assert!(
+        ipfs.contains("struct WalkAdmission") && ipfs.contains("Arc::new(WalkAdmission {"),
+        "U1 gate missing: the /ipfs walk admission must be a shared WalkAdmission, \
+         not a handler-local permit pair"
+    );
+
+    // Every blocking site in the scan takes its own clone...
+    // `Arc::clone(ctx.admission)` in the gate, `Arc::clone(&admission)` if a site is
+    // ever added back in the handler body itself; count both spellings.
+    let clones = ipfs.matches("Arc::clone(ctx.admission)").count()
+        + ipfs.matches("Arc::clone(&admission)").count();
+    assert!(
+        clones >= 3,
+        "U1 gate bypassed: expected an admission clone for each of the three \
+         /ipfs spawn_blocking sites (probe, walk, read); found {clones}. A blocking \
+         walk that does not hold the admission lets a disconnect or a panic free the \
+         slot while its git child is still running."
+    );
+
+    // ...and each clone is actually moved INTO the blocking closure, not merely
+    // created in the async frame (which would hold nothing across the join).
+    let held = ipfs.matches("let _admission = ").count();
+    assert!(
+        held >= 3,
+        "U1 gate bypassed: each admission clone must be bound inside its \
+         spawn_blocking closure so the blocking work owns it; found {held} of 3."
+    );
+
+    // The count of blocking sites is itself the thing being covered: if a fourth
+    // appears, it needs an admission clone too and this gate must be revisited.
+    let sites = ipfs.matches("spawn_blocking(move ||").count();
+    assert_eq!(
+        sites, 3,
+        "the /ipfs scan grew or lost a spawn_blocking site ({sites} found, expected 3); \
+         give any new blocking walk its own Arc::clone(&admission) and update this gate"
+    );
+}
+
+/// #174 U5: the post-receive replication tail is spawned at the DURABILITY BOUNDARY,
+/// which is the moment receive-pack returns success, not the end of the handler and
+/// not after `guard.release()`.
+///
+/// The tail owes this push its pins, recovery copy, and announcements. Everything
+/// below the spawn stays in the cancellable request future, so anything the tail is
+/// spawned after is a window where a client disconnect drops that work while the pack
+/// is already durable on disk. `guard.release()` is such a window: on success it
+/// awaits the Tigris upload and then the advisory unlock.
+///
+/// The lower bound matters just as much as the upper one: `release` runs on failure
+/// too, so an ungated spawn would fire for a push git rejected, pinning and announcing
+/// a half-applied repo. Above `release` the `?` on `receive_result` can no longer be
+/// what gates it, so the success check is explicit and this gate binds it: the spawn
+/// must sit inside `if push_succeeded`, and `release` must consume the same flag so
+/// the two cannot drift apart.
+///
+/// This is an ordering check rather than a cancellation-race test on purpose: it is
+/// the companion to `receive_pack_tail_survives_a_disconnect_during_release`, which
+/// drives the actual disconnect through a parked `release`. Same instrument the F3
+/// gate above uses.
+///
+/// MUTATION (RED): move the `tokio::spawn(post_receive_replication_tail` call below
+/// `guard.release(` and the ordering assertion fails; take it out of the
+/// `if push_succeeded` block and the failed-push assertion fails.
+#[test]
+fn inv22_replication_tail_spawns_at_the_durability_boundary() {
+    let repos = src("api/repos.rs");
+    // Production half only — the tests below name these identifiers too.
+    // Split at the TEST MODULE, not at the first `#[cfg(test)]`. api/repos.rs carries
+    // test-only items (the drain fault seam, the task entry point) ABOVE the production
+    // code these gates scan for, so splitting on the attribute truncated the production
+    // half above every line being checked and the gate went vacuously blind.
+    let production = repos
+        .split("\nmod tests {")
+        .next()
+        .expect("split always yields a first chunk");
+
+    let success_flag = production
+        .find("let push_succeeded = receive_result.is_ok();")
+        .expect(
+            "U5 gate missing: the tail's success gate must be bound from receive_result.is_ok()",
+        );
+    let gate_open = production
+        .find("if push_succeeded {")
+        .expect("U5 gate missing: the tail spawn must be gated on the push having succeeded");
+    let spawn = production
+        .find("tokio::spawn(post_receive_replication_tail(")
+        .expect("U5 gate missing: the replication tail must be spawned by git_receive_pack");
+    let release = production
+        .find(".release(push_succeeded)")
+        .expect("U5 gate stale: release must consume the same success flag as the tail gate");
+    let touch = production
+        .find("state.db.touch_repo(")
+        .expect("U5 gate stale: git_receive_pack no longer calls touch_repo");
+    let webhook = production
+        .find("webhooks::fire_event(")
+        .expect("U5 gate stale: git_receive_pack no longer fires push webhooks");
+
+    assert!(
+        success_flag < gate_open && gate_open < spawn,
+        "U5 gate bypassed: the tail must be spawned inside `if push_succeeded`, or a \
+         rejected push spawns a tail that pins and announces a half-applied repo"
+    );
+    // Still inside that block: no `}` may close it between the gate and the spawn.
+    assert!(
+        !production[gate_open + "if push_succeeded {".len()..spawn].contains('}'),
+        "U5 gate bypassed: the tail spawn left the `if push_succeeded` block, so a \
+         rejected push now spawns a tail"
+    );
+    assert!(
+        spawn < release && spawn < touch && spawn < webhook,
+        "U5 gate bypassed: the tail must be spawned BEFORE guard.release, touch_repo \
+         and the webhook fan-out, so a disconnect in any of those windows cannot drop \
+         this push's pins, recovery copy, and announcements"
+    );
+}

crates/gl/src/http.rs

@@ -203,6 +203,39 @@ async fn obtain_proof(cfg: IcaptchaCfg) -> Result<String> {
         .context("iCaptcha solver task panicked")?
 }
 
+/// Read at most `cap` bytes of a response body. Bounds the allocation from a
+/// hostile or broken node returning a huge error body — the display is capped
+/// separately, but the read itself must not be unbounded (INV-6, read half).
+pub(crate) async fn read_body_capped(mut resp: reqwest::Response, cap: usize) -> String {
+    let mut buf: Vec<u8> = Vec::new();
+    while buf.len() < cap {
+        match resp.chunk().await {
+            Ok(Some(chunk)) => {
+                let take = (cap - buf.len()).min(chunk.len());
+                buf.extend_from_slice(&chunk[..take]);
+                if take < chunk.len() {
+                    break; // hit the cap mid-chunk
+                }
+            }
+            _ => break, // end of body or read error — return what we have
+        }
+    }
+    String::from_utf8_lossy(&buf).into_owned()
+}
+
+/// Strip terminal-dangerous characters from (and cap the length of) a
+/// node-supplied error string before surfacing it. The node a caller talks to
+/// could be hostile and embed escape sequences in its error body; those must not
+/// reach the terminal verbatim (INV-6). We drop the C0/C1 control bytes (which
+/// defangs ANSI/OSC escapes) AND the Unicode bidi/format controls (which
+/// `char::is_control` does not cover — they can reorder the displayed line).
+pub(crate) fn sanitize_node_msg(s: &str) -> String {
+    s.chars()
+        .filter(|c| !c.is_control() && !gitlawb_core::sanitize::is_bidi_format(*c))
+        .take(200)
+        .collect()
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -587,4 +620,35 @@ mod tests {
         ic.challenge.assert();
         ic.answer.assert();
     }
+
+    #[test]
+    fn sanitize_strips_controls_bidi_and_caps_length() {
+        // C0 (ESC/BEL) and the Cf bidi override (U+202E) are both removed; the
+        // printable text survives. (Note: a stripped ESC leaves any following
+        // "[31m" as inert literal text — that is the point, so the input here
+        // avoids that residue to keep the expectation unambiguous.)
+        let out = sanitize_node_msg("a\u{1b}\u{07}b\u{202e}c");
+        assert!(
+            !out.chars().any(|c| c.is_control()),
+            "control char leaked: {out:?}"
+        );
+        assert!(
+            !out.contains('\u{202e}'),
+            "RLO bidi override leaked: {out:?}"
+        );
+        assert_eq!(out, "abc");
+        // Length is capped at 200 chars regardless of input size.
+        let long = "x".repeat(250);
+        assert_eq!(sanitize_node_msg(&long).chars().count(), 200);
+    }
+
+    #[test]
+    fn sanitize_preserves_legitimate_and_rtl_text() {
+        // Must not over-strip: a plain word, a genuine RTL SCRIPT letter (Arabic
+        // U+0627, category Lo — NOT a format char), and ZWJ (U+200D, a legitimate
+        // Cf char, e.g. emoji sequences) all survive. Guards the shared predicate
+        // against being widened into a blanket Cf stripper.
+        let out = sanitize_node_msg("ok \u{0627}\u{200D}b");
+        assert_eq!(out, "ok \u{0627}\u{200D}b");
+    }
 }

crates/gl/src/ipfs_cmd.rs

@@ -33,13 +33,16 @@ pub enum IpfsCmd {
         cid: String,
         #[arg(long, default_value = "https://node.gitlawb.com", env = "GITLAWB_NODE")]
         node: String,
+        /// Identity directory (default: ~/.gitlawb)
+        #[arg(long)]
+        dir: Option<PathBuf>,
     },
 }
 
 pub async fn run(args: IpfsArgs) -> Result<()> {
     match args.cmd {
         IpfsCmd::List { node, dir } => cmd_list(node, dir).await,
-        IpfsCmd::Get { cid, node } => cmd_get(cid, node).await,
+        IpfsCmd::Get { cid, node, dir } => cmd_get(cid, node, dir).await,
     }
 }
 
@@ -86,11 +89,32 @@ async fn cmd_list(node: String, dir: Option<PathBuf>) -> Result<()> {
     Ok(())
 }
 
-async fn cmd_get(cid: String, node: String) -> Result<()> {
-    let client = NodeClient::new(&node, None);
-    let path = format!("/ipfs/{cid}");
+async fn cmd_get(cid: String, node: String, dir: Option<PathBuf>) -> Result<()> {
+    // #173 (F5): the resolver now serves path-scoped objects to authorized readers,
+    // so sign with an available identity like `gl ipfs list` — otherwise an owner or
+    // listed reader gets the opaque anonymous 404 for content they can read.
+    // `get_authed` signs when a keypair is present and falls back to unsigned.
+    //
+    // An explicit `--dir` is a request to use THAT identity: propagate a
+    // missing/corrupt-keystore error (like `list`) instead of silently sending an
+    // anonymous request the authorized reader would see as the node's opaque 404
+    // (#173 review). Only the default (no `--dir`) keeps the best-effort unsigned
+    // fallback, so `get` stays usable for genuinely public content.
+    let keypair = match dir.as_deref() {
+        Some(dir) => Some(crate::identity::load_keypair_from_dir(Some(dir))?),
+        None => crate::identity::load_keypair_from_dir(None).ok(),
+    };
+    let client = NodeClient::new(&node, keypair);
+    // #173 review (F1): the node now accepts equivalent multibase spellings,
+    // including base64 CIDs (prefix 'm'), whose alphabet contains '/', '+', '='.
+    // Interpolating the CID raw would make the client request (and sign)
+    // `/ipfs/<prefix>/<suffix>`, which neither matches the single-segment Axum
+    // route nor points at the intended target. Percent-encode the CID as exactly
+    // one path segment so the signed and sent target agree and the server's
+    // `Path` extractor decodes it back to the original CID.
+    let path = format!("/ipfs/{}", encode_cid_segment(&cid));
     let resp = client
-        .get(&path)
+        .get_authed(&path)
         .await
         .with_context(|| format!("failed to fetch CID {cid} from {node}"))?;
 
@@ -119,6 +143,16 @@ async fn cmd_get(cid: String, node: String) -> Result<()> {
     Ok(())
 }
 
+/// Percent-encode a CID so it occupies exactly one path segment of `/ipfs/<cid>`.
+/// `urlencoding::encode` escapes every byte outside the RFC 3986 unreserved set
+/// (ALPHA / DIGIT / `-._~`), so the base64-CID characters that would otherwise
+/// break the single-segment route — `/`, `+`, `=` — are all escaped, and the
+/// server's `Path` extractor decodes the result back to the original CID (#173
+/// review, F1).
+fn encode_cid_segment(cid: &str) -> String {
+    urlencoding::encode(cid).into_owned()
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -235,4 +269,162 @@ mod tests {
 
         m.assert_async().await;
     }
+
+    /// #173 (F5): `gl ipfs get` must SIGN with an available identity, like
+    /// `gl ipfs list`, so an owner/reader can retrieve a path-scoped object the node
+    /// now resolves by CID. RED before the fix: cmd_get ignores the identity dir and
+    /// sends an unsigned request, so the signature-matching mock is never hit
+    /// (cmd_get errors on the unmatched 501, and m.assert fails). GREEN after: the
+    /// signed request carries the RFC 9421 headers and is served 200.
+    #[tokio::test]
+    async fn test_cmd_get_signs_when_identity_present() {
+        let mut server = mockito::Server::new_async().await;
+        let keystore = seed_keystore();
+
+        let m = server
+            .mock("GET", "/ipfs/bafkreitestcid")
+            .match_header("signature", mockito::Matcher::Any)
+            .match_header("signature-input", mockito::Matcher::Any)
+            .with_status(200)
+            .with_header("content-type", "application/octet-stream")
+            .with_header("x-git-hash", "abc123")
+            .with_body("object bytes")
+            .create_async()
+            .await;
+
+        cmd_get(
+            "bafkreitestcid".to_string(),
+            server.url(),
+            Some(keystore.path().to_path_buf()),
+        )
+        .await
+        .expect("signed get of a resolvable object should succeed");
+
+        m.assert_async().await;
+    }
+
+    /// #173 (F5) must-not: a genuine anonymous denial must surface as an error, not
+    /// be masked as success. With no identity dir the request is unsigned; a 404
+    /// from the node must produce an Err mentioning the status.
+    #[tokio::test]
+    async fn test_cmd_get_anonymous_denial_is_error() {
+        let mut server = mockito::Server::new_async().await;
+
+        let m = server
+            .mock("GET", "/ipfs/bafkreidenied")
+            .with_status(404)
+            .with_header("content-type", "text/plain")
+            .with_body("no git object found")
+            .create_async()
+            .await;
+
+        let err = cmd_get("bafkreidenied".to_string(), server.url(), None)
+            .await
+            .expect_err("a 404 denial must be an error, not masked success");
+        assert!(
+            err.to_string().contains("404"),
+            "error should mention the status, got: {err}"
+        );
+
+        m.assert_async().await;
+    }
+
+    /// #173 (INV-8) must-not: the node's new 503 "search incomplete" (the legacy CID
+    /// scan hit its bound and could not prove absence) must surface as an actionable
+    /// Err naming the status, NOT be rendered as an empty/"not found" success — a
+    /// retryable outcome the caller has to see. Mirrors the 404 denial case for the
+    /// bounded-search response the resolver now emits.
+    #[tokio::test]
+    async fn test_cmd_get_search_incomplete_503_is_error() {
+        let mut server = mockito::Server::new_async().await;
+
+        let m = server
+            .mock("GET", "/ipfs/bafkreiincomplete")
+            .with_status(503)
+            .with_header("content-type", "application/json")
+            .with_body(r#"{"error":"search_incomplete","message":"CID search incomplete — retry"}"#)
+            .create_async()
+            .await;
+
+        let err = cmd_get("bafkreiincomplete".to_string(), server.url(), None)
+            .await
+            .expect_err("a 503 incomplete-search must be an error, not masked as not-found");
+        assert!(
+            err.to_string().contains("503"),
+            "error should mention the status, got: {err}"
+        );
+
+        m.assert_async().await;
+    }
+
+    /// #173 review (F1): a base64 CID (multibase prefix 'm') can contain '/', '+',
+    /// and '='. The client must percent-encode it into ONE path segment before
+    /// building and signing `/ipfs/<cid>`; otherwise the '/' splits the target so
+    /// it misses the single-segment Axum route and the signature covers the wrong
+    /// path. Assert the encoded segment carries no raw '/', '+', or '=', and that
+    /// it decodes back to the original CID (the server's `Path` extractor performs
+    /// that same decode). RED with the old raw `format!("/ipfs/{cid}")`: the
+    /// segment still contains '/'.
+    #[test]
+    fn test_encode_cid_segment_escapes_base64_alphabet() {
+        let cid = "mFoo/Bar+baz==";
+        let encoded = encode_cid_segment(cid);
+
+        assert!(
+            !encoded.contains('/'),
+            "encoded CID must be a single path segment (no raw '/'), got: {encoded}"
+        );
+        assert!(
+            !encoded.contains('+'),
+            "encoded CID must escape '+', got: {encoded}"
+        );
+        assert!(
+            !encoded.contains('='),
+            "encoded CID must escape '=', got: {encoded}"
+        );
+
+        let decoded = urlencoding::decode(&encoded).expect("encoded CID must decode");
+        assert_eq!(
+            decoded, cid,
+            "encoding must round-trip back to the original CID"
+        );
+    }
+
+    /// #173 review: `gl ipfs get --dir <path>` must PROPAGATE a missing/corrupt
+    /// identity-load error like `gl ipfs list`, not silently fall back to an anonymous
+    /// request — otherwise an authorized reader pointing `--dir` at a broken keystore
+    /// gets the node's opaque 404 instead of the actionable key-load error. The
+    /// unsigned fallback is preserved only when NO `--dir` is given (covered by
+    /// `test_cmd_get_anonymous_denial_is_error`). RED before the fix (`.ok()` swallows
+    /// the error, an anonymous request is sent, and the `.expect(0)` mock is hit),
+    /// GREEN after.
+    #[tokio::test]
+    async fn test_cmd_get_explicit_dir_no_identity_errors_without_request() {
+        let mut server = mockito::Server::new_async().await;
+        // Empty keystore dir passed explicitly via --dir: no identity.pem present.
+        let empty = tempfile::TempDir::new().unwrap();
+
+        // The endpoint must never be hit when an explicit --dir fails to load.
+        let m = server
+            .mock("GET", "/ipfs/bafkreitestcid")
+            .expect(0)
+            .create_async()
+            .await;
+
+        let err = cmd_get(
+            "bafkreitestcid".to_string(),
+            server.url(),
+            Some(empty.path().to_path_buf()),
+        )
+        .await
+        .expect_err("an explicit --dir that fails to load must be an error");
+        assert!(
+            err.to_string().contains("gl identity new")
+                || err.to_string().contains("no identity found")
+                || err.to_string().contains("failed to load keypair"),
+            "error should name the key-load failure, got: {err}"
+        );
+
+        m.assert_async().await;
+    }
 }

crates/gl/src/peer.rs

@@ -7,7 +7,7 @@ use clap::{Args, Subcommand};
 use serde_json::Value;
 use std::path::PathBuf;
 
-use crate::http::NodeClient;
+use crate::http::{read_body_capped, sanitize_node_msg, NodeClient};
 use crate::identity::load_keypair_from_dir;
 
 #[derive(Args)]
@@ -97,6 +97,74 @@ async fn cmd_list(node: String) -> Result<()> {
     Ok(())
 }
 
+/// The warning text for a local peer-add reply, or `None` when the node
+/// accepted it.
+///
+/// Split out so the refusal path is assertable. The node now answers 403 when
+/// an unproven caller tries to repoint an existing peer's `http_url`, so a
+/// reply that arrived and refused must not reach the success line.
+fn local_add_refusal(status: reqwest::StatusCode, body: &Value) -> Option<String> {
+    if status.is_success() {
+        return None;
+    }
+    // The message is the node's, not ours, so it is defanged before it reaches
+    // the terminal. Only the message: the status and the prose are ours.
+    let msg = sanitize_node_msg(body["message"].as_str().unwrap_or("unknown error"));
+    Some(format!(
+        "warning: local peer list not updated ({status}): {msg}"
+    ))
+}
+
+/// The error text for a remote announce reply, or `None` when the peer accepted
+/// it.
+///
+/// Split out so the ordering is assertable: the status has to reach the caller
+/// even when the body does not parse. That case is reachable rather than
+/// theoretical, because the read above is capped, so a peer answering with a
+/// body past the cap leaves truncated JSON behind, and `peer_url` is whatever
+/// the caller passed, so a non-JSON error page is just as easy. Parsing first
+/// and failing on the parse would swallow the status the user needs.
+fn remote_announce_failure(status: reqwest::StatusCode, raw: &str) -> Option<String> {
+    if status.is_success() {
+        return None;
+    }
+    // Falls back to the body itself when there is no `message` field, which is
+    // what a truncated or non-JSON reply leaves. Sanitized either way: it is the
+    // peer's text and it is headed for the terminal.
+    let parsed: Value = serde_json::from_str(raw).unwrap_or(Value::Null);
+    let msg = sanitize_node_msg(parsed["message"].as_str().unwrap_or(raw));
+    Some(format!("announce failed ({status}): {msg}"))
+}
+
+/// Which line the local peer-add prints, and whether it is a warning.
+///
+/// Split out because the SELECTION is what the fix is: `local_add_refusal` was
+/// already unit-tested six ways, and replacing this whole match with an
+/// unconditional "Added to local peer list." still left 312 tests green. The
+/// helper was pinned; the wiring was not, which is the shape
+/// `unit-test-on-helper-does-not-prove-handler-wiring` names. With the choice
+/// extracted, the call site is a two-line dispatch carrying no logic.
+fn local_add_report(status: reqwest::StatusCode, body: &Value) -> (bool, String) {
+    match local_add_refusal(status, body) {
+        Some(warning) => (true, warning),
+        None => (false, "  Added to local peer list.".to_string()),
+    }
+}
+
+/// The block printed after a peer accepts our announce. Split out so the
+/// defanging is assertable: the DID and URL are the remote peer's own strings,
+/// and `peer_url` is caller-chosen, so this is the least trusted body the
+/// command handles. Only the display is sanitized; the values sent on to our
+/// local node stay verbatim, since that is data rather than terminal output and
+/// the node runs its own validation on them.
+fn announced_peer_summary(their_did: &str, their_url: &str, peer_count: u64) -> String {
+    format!(
+        "Announced to peer node:\n  DID:        {}\n  URL:        {}\n  Their peers: {peer_count}\n",
+        sanitize_node_msg(their_did),
+        sanitize_node_msg(their_url),
+    )
+}
+
 async fn cmd_add(peer_url: String, node: String, dir: Option<PathBuf>) -> Result<()> {
     let keypair = load_keypair_from_dir(dir.as_deref())?;
     let my_did = keypair.did().to_string();
@@ -127,21 +195,26 @@ async fn cmd_add(peer_url: String, node: String, dir: Option<PathBuf>) -> Result
         .await
         .context("failed to connect to peer")?;
     let status = resp.status();
-    let result: Value = resp.json().await.context("invalid JSON response")?;
+    // `peer_url` is fully caller-chosen, so this body is the least trusted one
+    // in the command: bound the read, and defang the message before it reaches
+    // the terminal through the error return. An announce reply is a DID, a URL
+    // and a count, so 8 KiB is well past what the shape needs.
+    let raw = read_body_capped(resp, 8 * 1024).await;
 
-    if !status.is_success() {
-        let msg = result["message"].as_str().unwrap_or("unknown error");
-        anyhow::bail!("announce failed ({status}): {msg}");
+    if let Some(failure) = remote_announce_failure(status, &raw) {
+        anyhow::bail!("{failure}");
     }
 
+    let result: Value = serde_json::from_str(&raw).context("invalid JSON response")?;
+
     let their_did = result["node_did"].as_str().unwrap_or("?");
     let their_url = result["node_url"].as_str().unwrap_or("?");
     let peer_count = result["peer_count"].as_u64().unwrap_or(0);
 
-    println!("Announced to peer node:");
-    println!("  DID:        {their_did}");
-    println!("  URL:        {their_url}");
-    println!("  Their peers: {peer_count}");
+    print!(
+        "{}",
+        announced_peer_summary(their_did, their_url, peer_count)
+    );
 
     // Also add their info to our local node's peer list
     // (the peer's /announce response includes their did + url)
@@ -150,9 +223,31 @@ async fn cmd_add(peer_url: String, node: String, dir: Option<PathBuf>) -> Result
             "did": their_did,
             "http_url": their_url,
         }))?;
-        // This requires the local node to be running; ignore errors here
-        let _ = local_client.post("/api/v1/peers/announce", &add_body).await;
-        println!("  Added to local peer list.");
+        // This requires the local node to be running, so a transport failure
+        // stays a warning rather than failing the command. A reply that
+        // ARRIVED and refused is different: the announce route answers 403
+        // when an unproven caller tries to repoint an existing peer, and
+        // printing the success line over that reports a completed add that
+        // never happened. Same status handling as the remote announce above,
+        // except best effort.
+        match local_client.post("/api/v1/peers/announce", &add_body).await {
+            Ok(resp) => {
+                let status = resp.status();
+                // Same bound as the remote announce above: a compromised local
+                // node (or a MITM on plain http) must not force an unbounded
+                // read. A body that does not parse stays `Null`, which still
+                // routes a non-success status to the warning.
+                let raw = read_body_capped(resp, 8 * 1024).await;
+                let result: Value = serde_json::from_str(&raw).unwrap_or(Value::Null);
+                let (is_warning, line) = local_add_report(status, &result);
+                if is_warning {
+                    eprintln!("{line}");
+                } else {
+                    println!("{line}");
+                }
+            }
+            Err(e) => eprintln!("warning: local peer list not updated: {e}"),
+        }
     }
 
     Ok(())
@@ -210,3 +305,302 @@ async fn cmd_resolve(did: String, node: String) -> Result<()> {
     }
     Ok(())
 }
+
+#[cfg(test)]
+mod tests {
+    use super::{
+        announced_peer_summary, cmd_add, local_add_refusal, local_add_report,
+        remote_announce_failure,
+    };
+    use reqwest::StatusCode;
+    use serde_json::json;
+
+    /// The node's 403 for repointing an existing peer must surface, not print
+    /// as a completed add. Without the status check the command prints "Added
+    /// to local peer list." over a refusal.
+    ///
+    /// The fixture body is the real wire shape, not an invented one: the
+    /// message is the Display of `PeerWriteDenied::UnprovenRepoint`, declared
+    /// in `crates/gitlawb-node/src/db/mod.rs`. The executable detector for a
+    /// wording change is the node-side pin
+    /// `announce_unsigned_repoint_is_a_403_denial` in
+    /// `crates/gitlawb-node/src/api/peers.rs`, which asserts this same
+    /// substring against a response driven through the real router, so
+    /// rewording the Display turns that test red and the grep for the old
+    /// phrase lands here.
+    ///
+    /// The assertion bites rather than echoing its own input because the
+    /// substring is reachable only through the helper's `body["message"]`
+    /// extraction; the fixture's `error` field carries a different string, so
+    /// reading `body["error"]` instead fails this test.
+    #[test]
+    fn a_refused_local_add_warns_with_the_node_reason() {
+        let warning = local_add_refusal(
+            StatusCode::FORBIDDEN,
+            &json!({
+                "error": "forbidden",
+                "message": "unproven announce cannot change an existing peer's http_url: did:key:z6MkuMqUm4i228K9qXidJ57zqSWAcQLgrcbMxB8RKVLuqitj"
+            }),
+        )
+        .expect("a refusal must not render as success");
+
+        assert!(warning.contains("403"), "must name the status: {warning}");
+        assert!(
+            warning.contains("unproven announce cannot change an existing peer"),
+            "must carry the node's own reason: {warning}"
+        );
+    }
+
+    /// A refusal with no message body still warns rather than passing silently.
+    #[test]
+    fn a_refusal_without_a_message_still_warns() {
+        let warning = local_add_refusal(StatusCode::BAD_REQUEST, &serde_json::Value::Null)
+            .expect("a refusal must not render as success");
+        assert!(warning.contains("400"), "must name the status: {warning}");
+    }
+
+    /// The accepted case stays quiet, so the success line still prints.
+    #[test]
+    fn an_accepted_local_add_produces_no_warning() {
+        assert!(local_add_refusal(StatusCode::OK, &json!({ "peer_count": 3 })).is_none());
+    }
+
+    /// The warning is printed straight to a terminal, so a node-supplied message
+    /// carrying an OSC title-rewrite plus a C0 escape must reach it defanged.
+    #[test]
+    fn a_refusal_message_cannot_carry_terminal_escapes() {
+        let warning = local_add_refusal(
+            StatusCode::FORBIDDEN,
+            &json!({ "message": "\u{1b}]2;pwned\u{7}legit-looking text" }),
+        )
+        .expect("a refusal must not render as success");
+
+        assert!(
+            !warning.chars().any(|c| c.is_control()),
+            "control char leaked to the terminal: {warning:?}"
+        );
+        assert!(
+            warning.contains("legit-looking text"),
+            "printable text dropped: {warning:?}"
+        );
+    }
+
+    /// Bidi format chars are not `char::is_control`, yet they reorder the
+    /// displayed line, so a refusal must not carry them either.
+    #[test]
+    fn a_refusal_message_cannot_carry_bidi_overrides() {
+        let warning = local_add_refusal(
+            StatusCode::FORBIDDEN,
+            &json!({ "message": "peer \u{202e}refused\u{202c} here" }),
+        )
+        .expect("a refusal must not render as success");
+
+        assert!(
+            !warning.chars().any(gitlawb_core::sanitize::is_bidi_format),
+            "bidi format char leaked to the terminal: {warning:?}"
+        );
+    }
+
+    /// A hostile node must not be able to dump an arbitrary amount of text into
+    /// the user's scrollback through the warning line.
+    #[test]
+    fn a_refusal_message_is_length_bounded() {
+        let warning = local_add_refusal(
+            StatusCode::FORBIDDEN,
+            &json!({ "message": "x".repeat(5000) }),
+        )
+        .expect("a refusal must not render as success");
+
+        assert!(
+            warning.chars().count() < 500,
+            "warning not bounded: {} chars",
+            warning.chars().count()
+        );
+    }
+
+    /// The status is the part the user can act on, so it must survive a body
+    /// that does not parse. The read is capped, so a peer answering past the cap
+    /// leaves exactly this: a valid status and truncated JSON.
+    #[test]
+    fn a_remote_announce_failure_keeps_the_status_when_the_body_does_not_parse() {
+        let truncated = r#"{"error":"service_unavailable","message":"backend is do"#;
+        let failure = remote_announce_failure(StatusCode::SERVICE_UNAVAILABLE, truncated)
+            .expect("a non-success status must produce a failure");
+
+        assert!(
+            failure.contains("503"),
+            "the status must survive an unparseable body: {failure:?}"
+        );
+    }
+
+    /// A parseable error body still reports the peer's own message.
+    #[test]
+    fn a_remote_announce_failure_carries_the_peers_message() {
+        let failure = remote_announce_failure(
+            StatusCode::FORBIDDEN,
+            r#"{"error":"forbidden","message":"unproven announce cannot change an existing peer"}"#,
+        )
+        .expect("a non-success status must produce a failure");
+
+        assert!(
+            failure.contains("403")
+                && failure.contains("unproven announce cannot change an existing peer"),
+            "status and reason must both survive: {failure:?}"
+        );
+    }
+
+    /// The fallback path prints the raw body, so it is defanged like every other
+    /// peer-supplied string headed for the terminal.
+    #[test]
+    fn a_remote_announce_failure_defangs_an_unparseable_body() {
+        let failure = remote_announce_failure(
+            StatusCode::BAD_GATEWAY,
+            "\u{1b}]2;pwned\u{7}<html>gateway error</html>",
+        )
+        .expect("a non-success status must produce a failure");
+
+        assert!(
+            !failure.chars().any(|c| c.is_control()),
+            "control char leaked to the terminal: {failure:?}"
+        );
+        assert!(failure.contains("502"), "status dropped: {failure:?}");
+        assert!(
+            failure.contains("gateway error"),
+            "the body is all the user gets when there is no message field: {failure:?}"
+        );
+    }
+
+    /// The unit tests above bind the helper. This one binds the CALL SITE: the
+    /// failure check has to run before the parse, or a body past the read cap
+    /// turns a 503 into "invalid JSON response" and the status the user needs is
+    /// gone. Reordering the two statements in `cmd_add` compiles and passes every
+    /// other test in this file, so only driving the command catches it.
+    #[tokio::test]
+    async fn a_peer_failure_past_the_read_cap_still_reports_its_status() {
+        let mut peer = mockito::Server::new_async().await;
+        let mut local = mockito::Server::new_async().await;
+
+        let dir = tempfile::TempDir::new().unwrap();
+        let kp = gitlawb_core::identity::Keypair::generate();
+        std::fs::write(
+            dir.path().join("identity.pem"),
+            kp.to_pem().unwrap().as_bytes(),
+        )
+        .unwrap();
+
+        let _local_info = local
+            .mock("GET", "/")
+            .with_status(200)
+            .with_header("content-type", "application/json")
+            .with_body(r#"{"public_url":"https://me.example"}"#)
+            .create_async()
+            .await;
+
+        // Valid JSON, but past the 8 KiB read cap, so what survives the read is
+        // truncated and unparseable. This is the shape the cap itself creates.
+        let oversized = format!(r#"{{"message":"{}"}}"#, "x".repeat(16 * 1024));
+        let _peer_refusal = peer
+            .mock("POST", "/api/v1/peers/announce")
+            .with_status(503)
+            .with_header("content-type", "application/json")
+            .with_body(oversized)
+            .create_async()
+            .await;
+
+        let err = cmd_add(peer.url(), local.url(), Some(dir.path().to_path_buf()))
+            .await
+            .expect_err("a 503 from the peer must fail the command");
+
+        let rendered = format!("{err:#}");
+        assert!(
+            rendered.contains("503"),
+            "the status must survive a body past the read cap: {rendered:?}"
+        );
+        assert!(
+            !rendered.contains("invalid JSON response"),
+            "the parse failure must not stand in for the status: {rendered:?}"
+        );
+    }
+
+    /// An accepted announce produces no error, so the caller proceeds to parse.
+    #[test]
+    fn an_accepted_remote_announce_produces_no_failure() {
+        assert!(remote_announce_failure(StatusCode::OK, r#"{"peer_count":3}"#).is_none());
+    }
+
+    /// The selection, not the helper. A refusal must never yield the success
+    /// line, and the success line must never carry the warning prefix. This is
+    /// what stayed green when the entire match was replaced with an
+    /// unconditional "Added to local peer list."
+    #[test]
+    fn a_local_add_refusal_never_selects_the_success_line() {
+        let (is_warning, line) = local_add_report(
+            StatusCode::FORBIDDEN,
+            &json!({ "message": "unproven announce cannot change an existing peer's http_url: did:key:zAbc" }),
+        );
+
+        assert!(is_warning, "a 403 must select the warning stream: {line:?}");
+        assert!(
+            !line.contains("Added to local peer list"),
+            "a refusal rendered as the success line: {line:?}"
+        );
+        assert!(
+            line.contains("unproven announce cannot change an existing peer"),
+            "the node's reason must reach the user: {line:?}"
+        );
+    }
+
+    /// The other direction, so the fix cannot be satisfied by always warning.
+    #[test]
+    fn an_accepted_local_add_selects_the_success_line() {
+        let (is_warning, line) = local_add_report(StatusCode::OK, &json!({ "peer_count": 3 }));
+
+        assert!(!is_warning, "a 200 must not select the warning stream");
+        assert!(
+            line.contains("Added to local peer list"),
+            "the success line must still print: {line:?}"
+        );
+    }
+
+    /// The accepted-announce block prints the remote peer's own DID and URL, so
+    /// a hostile peer answering 200 must not get escapes onto the terminal that
+    /// way either. The refusal path is not the only sink in this command.
+    #[test]
+    fn an_accepted_announce_summary_cannot_carry_terminal_escapes() {
+        let summary = announced_peer_summary(
+            "did:key:z6Mk\u{1b}]2;pwned\u{7}abc",
+            "https://peer.example\u{202e}moc.live//:sptth",
+            3,
+        );
+
+        assert!(
+            !summary.chars().any(|c| c.is_control() && c != '\n'),
+            "control char leaked to the terminal: {summary:?}"
+        );
+        assert!(
+            !summary.chars().any(gitlawb_core::sanitize::is_bidi_format),
+            "bidi format char leaked to the terminal: {summary:?}"
+        );
+        assert!(
+            summary.contains("did:key:z6Mk") && summary.contains("Their peers: 3"),
+            "printable content dropped: {summary:?}"
+        );
+    }
+
+    /// The counterweight to the stripping tests: a legitimate message with RTL
+    /// script letters and a ZWJ must survive intact, so the sanitizer is not
+    /// proven by over-stripping.
+    #[test]
+    fn a_legitimate_refusal_message_survives_intact() {
+        let warning = local_add_refusal(
+            StatusCode::FORBIDDEN,
+            &json!({ "message": "peer refused \u{0627}\u{200D}b" }),
+        )
+        .expect("a refusal must not render as success");
+
+        assert!(
+            warning.contains("peer refused \u{0627}\u{200D}b"),
+            "legitimate text mangled: {warning:?}"
+        );
+    }
+}

crates/gl/src/sync.rs

@@ -2,7 +2,7 @@ use anyhow::{Context, Result};
 use clap::{Args, Subcommand};
 use std::path::PathBuf;
 
-use crate::http::NodeClient;
+use crate::http::{read_body_capped, sanitize_node_msg, NodeClient};
 use crate::identity::load_keypair_from_dir;
 
 #[derive(Args)]
@@ -104,39 +104,6 @@ fn trigger_counts(resp: &serde_json::Value) -> (u64, u64) {
     )
 }
 
-/// Read at most `cap` bytes of a response body. Bounds the allocation from a
-/// hostile or broken node returning a huge error body — the display is capped
-/// separately, but the read itself must not be unbounded (INV-6, read half).
-async fn read_body_capped(mut resp: reqwest::Response, cap: usize) -> String {
-    let mut buf: Vec<u8> = Vec::new();
-    while buf.len() < cap {
-        match resp.chunk().await {
-            Ok(Some(chunk)) => {
-                let take = (cap - buf.len()).min(chunk.len());
-                buf.extend_from_slice(&chunk[..take]);
-                if take < chunk.len() {
-                    break; // hit the cap mid-chunk
-                }
-            }
-            _ => break, // end of body or read error — return what we have
-        }
-    }
-    String::from_utf8_lossy(&buf).into_owned()
-}
-
-/// Strip terminal-dangerous characters from (and cap the length of) a
-/// node-supplied error string before surfacing it. The node a caller talks to
-/// could be hostile and embed escape sequences in its error body; those must not
-/// reach the terminal verbatim (INV-6). We drop the C0/C1 control bytes (which
-/// defangs ANSI/OSC escapes) AND the Unicode bidi/format controls (which
-/// `char::is_control` does not cover — they can reorder the displayed line).
-fn sanitize_node_msg(s: &str) -> String {
-    s.chars()
-        .filter(|c| !c.is_control() && !gitlawb_core::sanitize::is_bidi_format(*c))
-        .take(200)
-        .collect()
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -260,37 +227,6 @@ mod tests {
         run(args).await.unwrap();
     }
 
-    #[test]
-    fn sanitize_strips_controls_bidi_and_caps_length() {
-        // C0 (ESC/BEL) and the Cf bidi override (U+202E) are both removed; the
-        // printable text survives. (Note: a stripped ESC leaves any following
-        // "[31m" as inert literal text — that is the point, so the input here
-        // avoids that residue to keep the expectation unambiguous.)
-        let out = sanitize_node_msg("a\u{1b}\u{07}b\u{202e}c");
-        assert!(
-            !out.chars().any(|c| c.is_control()),
-            "control char leaked: {out:?}"
-        );
-        assert!(
-            !out.contains('\u{202e}'),
-            "RLO bidi override leaked: {out:?}"
-        );
-        assert_eq!(out, "abc");
-        // Length is capped at 200 chars regardless of input size.
-        let long = "x".repeat(250);
-        assert_eq!(sanitize_node_msg(&long).chars().count(), 200);
-    }
-
-    #[test]
-    fn sanitize_preserves_legitimate_and_rtl_text() {
-        // Must not over-strip: a plain word, a genuine RTL SCRIPT letter (Arabic
-        // U+0627, category Lo — NOT a format char), and ZWJ (U+200D, a legitimate
-        // Cf char, e.g. emoji sequences) all survive. Guards the shared predicate
-        // against being widened into a blanket Cf stripper.
-        let out = sanitize_node_msg("ok \u{0627}\u{200D}b");
-        assert_eq!(out, "ok \u{0627}\u{200D}b");
-    }
-
     #[tokio::test]
     async fn trigger_handles_oversized_error_body_without_unbounded_output() {
         // A hostile/broken node returns a 2 MB error body. The command must still

crates/icaptcha-client/src/lib.rs

@@ -720,4 +720,45 @@ mod tests {
 
         assert!(failures.is_empty(), "\n{}", failures.join("\n"));
     }
+
+    #[test]
+    fn new_normalizes_empty_api_key_to_none_on_trusted_origin() {
+        let guard = ICAPTCHA_ENV_LOCK.lock().unwrap();
+        let prev_key = std::env::var_os("GITLAWB_ICAPTCHA_API_KEY");
+        let prev_op = std::env::var_os("GITLAWB_ICAPTCHA_URL");
+
+        // Operator origin configured and resolved as trusted (no advert), so
+        // api_key reaches the env read and the emptiness filter is the only
+        // thing standing between a blank var and an empty bearer token.
+        std::env::set_var("GITLAWB_ICAPTCHA_URL", "https://icap.mynode.example");
+
+        // "Operator set the var but left it blank" must stay keyless: a
+        // Some("") would attach `Authorization: Bearer ` (empty token) to the
+        // challenge and answer requests instead of omitting the header.
+        std::env::set_var("GITLAWB_ICAPTCHA_API_KEY", "");
+        let empty = IcaptchaCfg::new("did:key:zTEST", None, None);
+
+        // Contrast arm: a real key on the same trusted path must survive the
+        // filter, so the filter can't regress to dropping every key.
+        std::env::set_var("GITLAWB_ICAPTCHA_API_KEY", "secret-bearer");
+        let non_empty = IcaptchaCfg::new("did:key:zTEST", None, None);
+
+        // Restore env and release the lock BEFORE asserting, so a failing
+        // assertion can't poison the shared lock or cascade into a sibling.
+        match prev_key {
+            Some(v) => std::env::set_var("GITLAWB_ICAPTCHA_API_KEY", v),
+            None => std::env::remove_var("GITLAWB_ICAPTCHA_API_KEY"),
+        }
+        match prev_op {
+            Some(v) => std::env::set_var("GITLAWB_ICAPTCHA_URL", v),
+            None => std::env::remove_var("GITLAWB_ICAPTCHA_URL"),
+        }
+        drop(guard);
+
+        assert_eq!(
+            empty.api_key, None,
+            "empty GITLAWB_ICAPTCHA_API_KEY must normalize to None"
+        );
+        assert_eq!(non_empty.api_key.as_deref(), Some("secret-bearer"));
+    }
 }

crates/icaptcha-client/tests/icaptcha_blackhole_tripwire.rs

@@ -0,0 +1,146 @@
+//! Tripwire: a committed negative case that locks the blackhole mechanism.
+//!
+//! The guard against non-loopback egress works because `obtain_proof` builds a
+//! stock `reqwest::blocking::Client` that inherits the process's proxy env vars.
+//! If the builder later gains `.no_proxy()` or a custom connector, the guard
+//! disarms silently and every existing test stays green (no live call is made
+//! during the normal mock-consumed run because the mock is on loopback and
+//! `NO_PROXY` covers it — the blackhole isn't even exercised).
+//!
+//! This test asserts that a destination the blackhole's `NO_PROXY` does NOT
+//! cover fails *while the blackhole is armed*.  The destination is a local HTTP
+//! server on `[::1]` (IPv6 loopback), which `NO_PROXY` (`127.0.0.1, localhost`)
+//! does not list.  With the blackhole active the proxy intercepts the
+//! connection and blocks it; without the blackhole the request would reach the
+//! server directly and succeed, turning this test RED.
+//!
+//! A positive control (disarmed blackhole) runs first, proving the fixture is
+//! valid and `[::1]` is reachable.
+//!
+//! Design constraints (see issue #211):
+//!   - An unresolvable host would keep the request failing even when the guard
+//!     is disarmed (DNS failure masquerading as the blackhole), so we must use
+//!     a reachable address.
+//!   - A real external host would make a live network call the moment the guard
+//!     disarms, and on any runner that cannot reach that host the connect error
+//!     again masquerades as the blackhole.  A local loopback address avoids both
+//!     problems — it is always reachable when unblocked and never reaches the
+//!     real network.
+//!   - The address must NOT be covered by `NO_PROXY`, yet must exist on every
+//!     platform.  An arbitrary `127/8` alias is not portable: macOS only binds
+//!     `127.0.0.1` by default.  `[::1]` (IPv6 loopback) is present by default
+//!     on Linux, macOS, and Windows, and `NO_PROXY` only lists `127.0.0.1` and
+//!     `localhost`, so the blackhole still intercepts it.
+//!   - This depends on hyper-util's proxy matcher having no implicit loopback
+//!     bypass — a host is only proxied-around when literally listed in
+//!     `NO_PROXY` (verified in the pinned hyper-util; recheck on upgrade).
+
+use std::io::{Read, Write};
+use std::net::TcpListener;
+use std::thread;
+
+use icaptcha_client::{obtain_proof, Challenge, IcaptchaCfg};
+
+mod support;
+
+/// A minimal HTTP server that responds to iCaptcha challenge and answer
+/// requests on the IPv6 loopback address NOT covered by NO_PROXY.
+///
+/// When the blackhole is working, the proxy should intercept these requests
+/// and `obtain_proof` should fail.  When the blackhole is disarmed, the
+/// requests reach this server and the flow succeeds.
+fn serve_icaptcha(listener: TcpListener) {
+    thread::spawn(move || {
+        for stream in listener.incoming() {
+            let Ok(mut stream) = stream else { continue };
+            // Read until the first \n (end of request line) so TCP
+            // segmentation cannot split the path out of a single read.
+            let mut buf = [0u8; 4096];
+            let mut n = 0usize;
+            while n < buf.len() {
+                match stream.read(&mut buf[n..]) {
+                    Ok(0) | Err(_) => break,
+                    Ok(read) => {
+                        n += read;
+                        if buf[..n].contains(&b'\n') {
+                            break;
+                        }
+                    }
+                }
+            }
+            if n == 0 {
+                continue;
+            }
+            let request = String::from_utf8_lossy(&buf[..n]);
+            let body = if request.contains("/v1/answer") {
+                r#"{"status":"passed","proof":"PROOF-TRIP"}"#
+            } else {
+                r#"{"challengeId":"c1","type":"anagram","difficulty":1,"prompt":"listen","token":"tok-1"}"#
+            };
+            let response = format!(
+                "HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}",
+                body.len(),
+            );
+            let _ = stream.write_all(response.as_bytes());
+        }
+    });
+}
+
+fn make_cfg(url: &str) -> IcaptchaCfg {
+    IcaptchaCfg {
+        url: url.to_string(),
+        did: "did:key:zTEST".to_string(),
+        level: 1,
+        api_key: None,
+    }
+}
+
+#[test]
+fn obtain_proof_blackhole_tripwire() {
+    // Bind to [::1], IPv6 loopback, which NO_PROXY (127.0.0.1, localhost)
+    // does not cover.  Unlike an arbitrary 127/8 alias, IPv6 loopback is
+    // present by default on Linux, macOS, and Windows, so the fixture is
+    // portable across platforms.  Fail loudly if it cannot be bound: a
+    // silent skip would report this tripwire as green while exercising
+    // none of the negative control, recreating the very gap it exists to
+    // close.
+    let listener = TcpListener::bind(("::1", 0)).expect(
+        "cannot bind [::1] for the blackhole tripwire. IPv6 loopback (::1) \
+         is present by default on Linux, macOS, and Windows. This test fails \
+         rather than silently skipping so a platform without it cannot count \
+         the negative control as passed.",
+    );
+    let port = listener.local_addr().unwrap().port();
+    let url = format!("http://[::1]:{port}");
+    serve_icaptcha(listener);
+
+    // ── Positive control: disarmed blackhole → obtain_proof succeeds ──────
+    let _disarmed_guard = support::disarm_proxy_env();
+
+    let solve: &dyn Fn(&Challenge) -> Option<String> = &|_c| Some("silent".to_string());
+    let cfg = make_cfg(&url);
+    let proof = obtain_proof(&cfg, Some(solve))
+        .expect("positive control: obtain_proof should succeed when the proxy is disarmed");
+    assert_eq!(
+        proof, "PROOF-TRIP",
+        "positive control: unexpected proof value"
+    );
+    drop(_disarmed_guard);
+
+    // ── Negative control: armed blackhole → obtain_proof fails with connect error ──
+    let _armed_guard = support::arm_blackhole("http://127.0.0.1:1");
+
+    let result = obtain_proof(&cfg, Some(solve));
+
+    let err = result.expect_err(
+        "blackhole tripwire: obtain_proof succeeded against [::1], \
+         meaning the proxy blackhole did not intercept the request; \
+         the no-live-call guard is disarmed",
+    );
+    assert!(
+        err.chain().any(|c| c
+            .downcast_ref::<reqwest::Error>()
+            .is_some_and(|e| e.is_connect())),
+        "expected a connect/proxy error, got: {err:#}",
+    );
+}

crates/icaptcha-client/tests/icaptcha_mock_consumed.rs

@@ -1,4 +1,4 @@
-//! INV-19 guard: the icaptcha flow must actually call the service (consume the
+//! INV-19 guard: the icaptcha flow must actually call the service (consuming the
 //! mock), not short-circuit or make a live call. If a future change let
 //! `obtain_proof` skip the network (e.g. a stray `cfg(test)` relaxation, which
 //! INV-19/INV-20 warn is inert across crates), the `.assert()` calls below go
@@ -8,50 +8,144 @@
 //! see a request that ALSO leaks the DID / answer / API key to `DEFAULT_URL` or
 //! any other origin (a different host the mock never observes). To make the
 //! "no live call" half of the guard load-bearing, the test blackholes every
-//! non-loopback destination: `NO_PROXY` lets the loopback mock through while a
-//! closed proxy port routes any other host nowhere, so the client contacting
-//! anything but the injected mock fails the request instead of silently
-//! succeeding. Point `cfg.url` at `DEFAULT_URL` and this test goes RED.
+//! non-loopback destination via a proxy observer: `NO_PROXY` lets the loopback
+//! mock through while every proxy variable routes any other host through a TCP
+//! listener that counts connections.  Zero observed connections proves no leak
+//! reached the network on the exercised path.
+//!
+//! The observer design counts every accepted connection regardless of whether
+//! the caller propagates the transport error, so it catches leaks that a
+//! closed-port blackhole (which only surfaces propagating errors) would miss.
+//! To close the timing race inherent in a detached accept loop, the count is
+//! read only after a bounded drain: the test opens a flush connection and
+//! blocks until the accept thread has accepted *that specific connection*
+//! (tagged by its source port), not merely until any next counter tick.
+//! Because `accept()` hands out connections FIFO, every leak connection that
+//! completed its TCP handshake before the flush is counted before the flush —
+//! the assertion therefore covers all egress in flight when `obtain_proof`
+//! returned.  A leak that starts its handshake after the drain is outside the
+//! window; that is the irreducible limit of observing a detached accept loop,
+//! and it is the remaining, well-defined gap this guard accepts.
+//!
+//! SCOPE: The observer only witnesses leaks issued on the path this test drives
+//! (a single passing round, 200 on both endpoints, no PoW, no Continue/Failed,
+//! no non-2xx response).  A leak living on an error or retry branch makes no
+//! connection during the run and the zero-count assertion stays green.  The
+//! guarantee covers only the exercised happy path and proxy-honoring transports;
+//! a future `.no_proxy()` or raw `TcpStream` bypasses the observer entirely.
 //!
 //! `ALL_PROXY` alone is NOT enough: reqwest honors the scheme-specific
 //! `HTTPS_PROXY` / `https_proxy` (and the http equivalents) OVER `ALL_PROXY`, so
 //! a runner with a working `HTTPS_PROXY` in its environment would route an https
 //! leak to `DEFAULT_URL` (which is https) through that proxy while the loopback
-//! mock is still consumed and this test stayed green. So we blackhole the
-//! scheme-specific variables too. No restore is needed: this file has a single
-//! `#[test]`, so it runs in its own process and the override never races a
-//! sibling test.
+//! mock is still consumed and this test stayed green.  So we blackhole the
+//! scheme-specific variables too.
+
+use std::net::{TcpListener, TcpStream};
+use std::sync::{Arc, Condvar, Mutex};
 
 use icaptcha_client::{obtain_proof, Challenge, IcaptchaCfg};
 
+mod support;
+
+/// A TCP listener that counts every accepted connection.
+///
+/// Acts as the proxy target: any leaked connection to a non-loopback
+/// destination will be routed through this listener and counted.  Every
+/// accepted connection is recorded by its source port so the test's own
+/// flush connection ([`ProxyObserver::drain`]) can be recognised and
+/// excluded from the leak count.
+struct ProxyObserver {
+    _listener: Arc<TcpListener>,
+    port: u16,
+    /// Source ports of every accepted connection, in accept order.
+    accepted: Arc<Mutex<Vec<u16>>>,
+    /// Source ports of the test's own flush connections (never counted).
+    flush_ports: Arc<Mutex<Vec<u16>>>,
+    /// Signalled after each accept so `drain` can wait on the flush.
+    ack: Arc<Condvar>,
+}
+
+impl ProxyObserver {
+    fn bind() -> Self {
+        let listener = Arc::new(TcpListener::bind("127.0.0.1:0").expect("bind proxy observer"));
+        let port = listener.local_addr().unwrap().port();
+        let accepted = Arc::new(Mutex::new(Vec::new()));
+        let flush_ports = Arc::new(Mutex::new(Vec::new()));
+        let ack = Arc::new(Condvar::new());
+        let a = Arc::clone(&accepted);
+        let c = Arc::clone(&ack);
+        let l = Arc::clone(&listener);
+        std::thread::spawn(move || {
+            for stream in l.incoming() {
+                let Ok(stream) = stream else { continue };
+                a.lock()
+                    .unwrap()
+                    .push(stream.peer_addr().map(|a| a.port()).unwrap_or(0));
+                c.notify_all();
+            }
+        });
+        ProxyObserver {
+            _listener: listener,
+            port,
+            accepted,
+            flush_ports,
+            ack,
+        }
+    }
+
+    fn port(&self) -> u16 {
+        self.port
+    }
+
+    /// Number of accepted connections that are not the test's own flush
+    /// connections — i.e. the leak count.
+    fn count(&self) -> usize {
+        let flush = self.flush_ports.lock().unwrap();
+        let accepted = self.accepted.lock().unwrap();
+        accepted.iter().filter(|p| !flush.contains(p)).count()
+    }
+
+    /// Bounded acknowledgement barrier for the accept loop.
+    ///
+    /// Opens a flush connection and blocks until the accept thread has
+    /// accepted *that connection* (identified by its source port), bounded by
+    /// a timeout.  Because `accept()` hands out connections FIFO, once the
+    /// flush is accepted every connection that completed its handshake before
+    /// it has been accepted and recorded too — so counting on afterwards
+    /// cannot miss a leak that was already in flight.  The flush connection
+    /// itself is never counted.
+    ///
+    /// A counter-tick barrier would be unsound here: sampling "current + 1"
+    /// and waiting for any increment lets a leak accepted after the sample
+    /// satisfy the wait, and the flush is then miscounted as that leak.
+    fn drain(&self) {
+        let flush =
+            TcpStream::connect(("127.0.0.1", self.port)).expect("observer flush connection");
+        let flush_port = flush.local_addr().unwrap().port();
+        self.flush_ports.lock().unwrap().push(flush_port);
+        let mut accepted = self.accepted.lock().unwrap();
+        while !accepted.contains(&flush_port) {
+            let (guard, timed_out) = self
+                .ack
+                .wait_timeout(accepted, std::time::Duration::from_secs(5))
+                .unwrap();
+            accepted = guard;
+            assert!(
+                !timed_out.timed_out(),
+                "proxy observer drain timed out; accept loop stalled"
+            );
+        }
+    }
+}
+
 #[test]
 fn obtain_proof_consumes_the_mocked_service_and_makes_no_live_call() {
-    // Blackhole every non-loopback origin: the loopback mock bypasses the proxy
-    // (NO_PROXY); any other host is forced through a closed port and fails.
-    // reqwest reads these at client-build time, and obtain_proof builds its
-    // client fresh, so this bounds the transport for the whole flow.
-    //
-    // Set the scheme-specific vars too (both cases), not just ALL_PROXY: reqwest
-    // gives HTTPS_PROXY/https_proxy precedence over ALL_PROXY for https URLs, so
-    // an ALL_PROXY-only blackhole leaves an https leak to DEFAULT_URL open on a
-    // runner whose environment already has a working HTTPS_PROXY.
-    let blackhole = "http://127.0.0.1:1";
-    std::env::set_var("NO_PROXY", "127.0.0.1,localhost");
-    std::env::set_var("no_proxy", "127.0.0.1,localhost");
-    for var in [
-        "ALL_PROXY",
-        "all_proxy",
-        "HTTPS_PROXY",
-        "https_proxy",
-        "HTTP_PROXY",
-        "http_proxy",
-    ] {
-        std::env::set_var(var, blackhole);
-    }
+    let observer = ProxyObserver::bind();
+    let _guard = support::arm_blackhole(&format!("http://127.0.0.1:{}", observer.port()));
 
     let mut server = mockito::Server::new();
 
-    // The two endpoints the flow hits, each expected exactly once.
     let challenge = server
         .mock("POST", "/v1/challenge")
         .with_status(200)
@@ -77,18 +171,29 @@ fn obtain_proof_consumes_the_mocked_service_and_makes_no_live_call() {
         api_key: None,
     };
 
-    // "anagram" is not a built-in solvable type, so the flow consults this
-    // solver callback. The answer body itself does not matter: the mocked
-    // /v1/answer returns "passed" regardless of what is submitted.
     let solve = |_c: &Challenge| Some("silent".to_string());
     let solver: &dyn Fn(&Challenge) -> Option<String> = &solve;
 
+    let count_before = observer.count();
+
     let proof = obtain_proof(&cfg, Some(solver))
         .expect("obtain_proof should complete against the mocked service");
     assert_eq!(proof, "PROOF-XYZ");
 
-    // INV-19: prove the client actually called the mocked endpoints. Had it made
-    // a live call or skipped the network, these would fail (mock never hit).
     challenge.assert();
     answer.assert();
+
+    // Drain the accept loop before asserting: the flush connection is not
+    // counted, and because accept() is FIFO every leak connection that
+    // completed its handshake before the flush is recorded before the flush
+    // is — so the count after drain reflects all egress in flight during the
+    // call.
+    observer.drain();
+    let leak_count = observer.count() - count_before;
+
+    assert_eq!(
+        leak_count, 0,
+        "proxy observer caught leaked connections; \
+         the blackhole failed to contain egress"
+    );
 }

crates/icaptcha-client/tests/support/mod.rs

@@ -0,0 +1,93 @@
+//! Shared helpers for the icaptcha-client integration tests.
+//!
+//! CONCURRENCY CONSTRAINT: [`arm_blackhole`] and [`disarm_proxy_env`] mutate
+//! process-wide proxy env vars and restore them on drop.  Each test binary
+//! that consumes this module currently has exactly one `#[test]`, so there is
+//! no concurrent use.  `cargo test` runs tests within a binary in parallel by
+//! default, so the NEXT test added to either file MUST be serialized against
+//! these helpers (e.g. a shared `Mutex` in this module, or the `serial_test`
+//! crate) or it will race on the proxy vars.
+
+use std::ffi::OsString;
+
+const PROXY_VARS: &[&str] = &[
+    "NO_PROXY",
+    "no_proxy",
+    "ALL_PROXY",
+    "all_proxy",
+    "HTTPS_PROXY",
+    "https_proxy",
+    "HTTP_PROXY",
+    "http_proxy",
+    "REQUEST_METHOD",
+];
+
+/// Captures the current values of a set of env vars and restores them on drop.
+pub struct EnvSnapshot(Vec<(String, Option<OsString>)>);
+
+impl EnvSnapshot {
+    pub fn capture(vars: &[&str]) -> Self {
+        EnvSnapshot(
+            vars.iter()
+                .map(|v| (v.to_string(), std::env::var_os(v)))
+                .collect(),
+        )
+    }
+}
+
+impl Drop for EnvSnapshot {
+    fn drop(&mut self) {
+        for (var, val) in &self.0 {
+            match val {
+                Some(v) => std::env::set_var(var, v),
+                None => std::env::remove_var(var),
+            }
+        }
+    }
+}
+
+/// Guard that restores env vars captured at construction time.
+pub struct EnvGuard {
+    _prev: EnvSnapshot,
+}
+
+/// Override every proxy-related env var so that non-loopback destinations are
+/// forced through `proxy_url`, with NO_PROXY covering loopback.  Also clears
+/// REQUEST_METHOD, which causes hyper-util to ignore all proxy variables when
+/// set.  Restores prior values on drop.
+///
+/// Not safe to call from concurrent tests (see module docs).
+pub fn arm_blackhole(proxy_url: &str) -> EnvGuard {
+    let prev = EnvSnapshot::capture(PROXY_VARS);
+
+    std::env::set_var("NO_PROXY", "127.0.0.1,localhost");
+    std::env::set_var("no_proxy", "127.0.0.1,localhost");
+    for var in [
+        "ALL_PROXY",
+        "all_proxy",
+        "HTTPS_PROXY",
+        "https_proxy",
+        "HTTP_PROXY",
+        "http_proxy",
+    ] {
+        std::env::set_var(var, proxy_url);
+    }
+    std::env::remove_var("REQUEST_METHOD");
+
+    EnvGuard { _prev: prev }
+}
+
+/// Clear every proxy-related env var so connections go direct.  Restores
+/// prior values on drop.
+///
+/// Not safe to call from concurrent tests (see module docs).
+#[allow(dead_code)]
+pub fn disarm_proxy_env() -> EnvGuard {
+    let prev = EnvSnapshot::capture(PROXY_VARS);
+
+    for var in PROXY_VARS {
+        std::env::remove_var(var);
+    }
+
+    EnvGuard { _prev: prev }
+}

docs/RUN-A-NODE.md

@@ -177,7 +177,7 @@ GITLAWB_ENFORCE_OWNER_PUSH=true
 | Missed heartbeats | After 3 days without one, you're excluded from rewards until you beat again |
 | Operator key | Dedicated wallet, small ETH balance, not your main treasury |
 | Monitoring | Watch `lastHeartbeat` on-chain; alert if > 22h since last beat |
-| Public URL | Must resolve and serve `/health` — peers will ping it |
+| Public URL | Must resolve and serve `/health` for liveness and DB-aware `/ready` for peer readiness |
 
 ---
 
@@ -187,6 +187,8 @@ GITLAWB_ENFORCE_OWNER_PUSH=true
 
 **Node refuses to start with "strict-mode operator check failed"** — either `gl node register` first, or unset `GITLAWB_OPERATOR_STRICT_MODE`.
 
+**Node refuses to start with "GITLAWB_DB_MAX_CONNECTIONS (20) must be at least max_concurrent_git_pushes (32) + 8 headroom"**: raise `GITLAWB_DB_MAX_CONNECTIONS` to at least the push cap plus 8 (40 with the default cap of 32; 48 is the shipped default and the recommended value), or lower `GITLAWB_MAX_CONCURRENT_GIT_PUSHES`. This bites a node upgraded in place that still sets the old pool size of 20. The check is deliberate: each concurrent push pins one pooled connection for its whole receive-pack, so a pool that does not clear the push cap lets a burst of slow pushes starve every other database path.
+
 **Rewards are 0 after a week** — run `gl node onchain-status`. If `currentlyActive: false`, check your heartbeat loop (node logs for `operator heartbeat sent`).
 
 **Want to rotate operator wallet** — requires unstake → re-register with new wallet. No in-place rotation in v1.

release-please-config.json

@@ -12,7 +12,8 @@
         { "type": "generic", "path": "crates/gitlawb-node/Cargo.toml" },
         { "type": "generic", "path": "crates/gl/Cargo.toml" },
         { "type": "generic", "path": "crates/git-remote-gitlawb/Cargo.toml" },
-        { "type": "generic", "path": "crates/gitlawb-attest/Cargo.toml" }
+        { "type": "generic", "path": "crates/gitlawb-attest/Cargo.toml" },
+        { "type": "generic", "path": "crates/icaptcha-client/Cargo.toml" }
       ]
     }
   }

scripts/check-release-versioning.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+#
+# Release-versioning coverage gate for the workspace crates.
+#
+# release-please owns every crate's version. It rewrites a version line only
+# when BOTH halves hold: the line carries an `# x-release-please-version`
+# annotation, and the crate's manifest is listed under `extra-files` in
+# release-please-config.json. A crate missing either half is silently skipped
+# at release time and freezes at whatever version it was created with, which
+# is exactly what happened to icaptcha-client (added as a workspace member
+# after the config was last written, so it sat at 0.4.0 while the rest of the
+# workspace walked to 0.7.1 across four releases).
+#
+# Exhaustive-by-construction: the required set is DERIVED from the workspace
+# member list via `cargo metadata`, never from a hand-maintained list here. A
+# newly added crate reds CI whether or not anyone remembered this gate exists,
+# which is the property a hand list cannot have.
+#
+# Hard-fail directions, all three release-silent:
+#   1. a workspace member absent from extra-files
+#   2. a workspace member whose version line lacks the annotation
+#   3. an extra-files entry pointing at a manifest that no longer exists
+#
+# Runnable from anywhere in the repo.
+set -euo pipefail
+
+ROOT="$(git rev-parse --show-toplevel)"
+CONFIG="$ROOT/release-please-config.json"
+
+if [ ! -f "$CONFIG" ]; then
+  echo "ERROR: release-please config not found at $CONFIG" >&2
+  exit 1
+fi
+
+# Resolving can refresh Cargo.lock as a side effect, so snapshot and restore it:
+# this check must never leave the working tree dirty when run locally. Same
+# reasoning as scripts/check-gitlawb-core-deps.sh.
+lock_backup="$(mktemp)"
+cp "$ROOT/Cargo.lock" "$lock_backup"
+restore_lock() { cp "$lock_backup" "$ROOT/Cargo.lock"; rm -f "$lock_backup"; }
+trap restore_lock EXIT
+
+# Workspace members as repo-relative manifest paths, one per line. This is the
+# derived required set: whatever cargo considers a member must be release-managed.
+members="$(
+  cargo metadata --no-deps --format-version 1 --manifest-path "$ROOT/Cargo.toml" \
+    | jq -r '.packages[].manifest_path' \
+    | sed "s#^$ROOT/##" \
+    | sort -u
+)"
+
+# Manifest paths release-please is configured to rewrite.
+listed="$(jq -r '.packages["."]["extra-files"][] | .path' "$CONFIG" | sort -u)"
+
+unlisted="$(comm -23 <(printf '%s\n' "$members") <(printf '%s\n' "$listed"))"
+orphaned="$(comm -13 <(printf '%s\n' "$members") <(printf '%s\n' "$listed"))"
+
+# Second half of the invariant: being listed does nothing without the marker,
+# because the generic updater keys on the annotation to find the line.
+#
+# Scoped to the [package] table on purpose. A manifest-wide match is satisfied by
+# an annotated `version` under any other table, so a crate could leave the version
+# cargo actually reads unannotated, pass this gate, and still freeze at release
+# time while release-please rewrote the decoy line instead.
+unmarked=""
+while IFS= read -r manifest; do
+  [ -n "$manifest" ] || continue
+  if ! awk '
+    /^[[:space:]]*\[/ { in_package = ($0 ~ /^[[:space:]]*\[package\][[:space:]]*$/); next }
+    in_package && /^version = ".*" # x-release-please-version/ { found = 1 }
+    END { exit(found ? 0 : 1) }
+  ' "$ROOT/$manifest"; then
+    unmarked="$unmarked$manifest"$'\n'
+  fi
+done <<< "$members"
+
+failed=0
+
+if [ -n "$unlisted" ]; then
+  {
+    echo "ERROR: workspace members missing from extra-files in release-please-config.json:"
+    printf '  %s\n' $unlisted
+    echo
+    echo "release-please will never bump these crates, so they freeze at their"
+    echo "current version while the rest of the workspace moves. Add each one as"
+    echo '  { "type": "generic", "path": "<manifest path>" }'
+  } >&2
+  failed=1
+fi
+
+if [ -n "$unmarked" ]; then
+  {
+    echo "ERROR: workspace members whose version line lacks the release-please annotation:"
+    printf '  %s\n' $unmarked
+    echo
+    echo 'The generic updater finds the line by its trailing `# x-release-please-version`'
+    echo "comment. Without it the crate is listed but never rewritten."
+  } >&2
+  failed=1
+fi
+
+if [ -n "$orphaned" ]; then
+  {
+    echo "ERROR: extra-files entries pointing at manifests that are not workspace members:"
+    printf '  %s\n' $orphaned
+    echo
+    echo "release-please fails the release when an extra-file path does not exist."
+    echo "Drop the stale entry, or restore the crate to the workspace."
+  } >&2
+  failed=1
+fi
+
+if [ "$failed" -ne 0 ]; then
+  exit 1
+fi
+
+echo "release versioning coverage: OK ($(printf '%s\n' "$members" | wc -l | tr -d ' ') workspace members, all annotated and listed)."

scripts/resolve-release-tag.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+tag="${1-}"
+: "${GITHUB_OUTPUT:?GITHUB_OUTPUT must be set}"
+
+case "$tag" in
+  ""|*[!A-Za-z0-9._-]*)
+    printf '%s\n' "::error::release tag is empty or contains invalid characters"
+    exit 1
+    ;;
+esac
+
+case "$tag" in
+  v[0-9]*) ;;
+  *)
+    printf '%s\n' "::error::'$tag' does not look like a release tag (vX.Y.Z)"
+    exit 1
+    ;;
+esac
+
+printf '%s\n' "tag=$tag" >> "$GITHUB_OUTPUT"
+printf '%s\n' "version=${tag#v}" >> "$GITHUB_OUTPUT"

scripts/test-resolve-release-tag.sh

@@ -0,0 +1,163 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+resolver="$repo_root/scripts/resolve-release-tag.sh"
+test_tmp="$(mktemp -d)"
+trap 'rm -r -- "$test_tmp"' EXIT
+
+valid_output="$test_tmp/valid-output"
+GITHUB_OUTPUT="$valid_output" "$resolver" "v1.2.3"
+
+expected_output="$test_tmp/expected-output"
+printf '%s\n' "tag=v1.2.3" "version=1.2.3" > "$expected_output"
+cmp "$expected_output" "$valid_output"
+
+newline_output="$test_tmp/newline-output"
+newline_stdout="$test_tmp/newline-stdout"
+newline_stderr="$test_tmp/newline-stderr"
+if GITHUB_OUTPUT="$newline_output" "$resolver" $'v1.2.3\nname=owned' \
+  > "$newline_stdout" 2> "$newline_stderr"
+then
+  printf '%s\n' "newline-containing release tag unexpectedly passed" >&2
+  exit 1
+fi
+test ! -s "$newline_output"
+grep -qxF "::error::release tag is empty or contains invalid characters" "$newline_stdout"
+test ! -s "$newline_stderr"
+
+empty_output="$test_tmp/empty-output"
+if GITHUB_OUTPUT="$empty_output" "$resolver" ""; then
+  printf '%s\n' "empty release tag unexpectedly passed" >&2
+  exit 1
+fi
+test ! -s "$empty_output"
+
+invalid_output="$test_tmp/invalid-output"
+for invalid_tag in \
+  "v1.2.3 tag" \
+  "v1.2.3;name=owned" \
+  "v1.2.3+build.5" \
+  "release-1.2.3" \
+  "v-1" \
+  "vlatest" \
+  "v" \
+  "v1.2.3/../../x" \
+  "V1.2.3"
+do
+  : > "$invalid_output"
+  if GITHUB_OUTPUT="$invalid_output" "$resolver" "$invalid_tag"; then
+    printf '%s\n' "invalid release tag unexpectedly passed: $invalid_tag" >&2
+    exit 1
+  fi
+  test ! -s "$invalid_output"
+done
+
+release_workflow="$repo_root/.github/workflows/release.yml"
+actual_resolver_steps="$test_tmp/actual-resolver-steps"
+expected_resolver_steps="$test_tmp/expected-resolver-steps"
+
+# Pin each resolver step and the checkout step that supplies its script. Any
+# change to one of these reviewed blocks must be reflected here deliberately.
+awk '
+  function emit_step() {
+    if (in_step && (is_rel || is_workflow_scripts_checkout)) {
+      printf "job=%s\n%s", job, step
+    }
+    in_step = 0
+    is_rel = 0
+    is_workflow_scripts_checkout = 0
+    step = ""
+  }
+
+  /^  [A-Za-z0-9_-]+:[[:space:]]*$/ {
+    emit_step()
+    job = $0
+    sub(/^  /, "", job)
+    sub(/:[[:space:]]*$/, "", job)
+    next
+  }
+
+  /^      - / {
+    emit_step()
+    in_step = 1
+    is_workflow_scripts_checkout = ($0 ~ /^      - name:[[:space:]]*Check out workflow scripts[[:space:]]*$/)
+    step = $0 ORS
+    next
+  }
+
+  in_step {
+    step = step $0 ORS
+    if ($0 ~ /^        id:[[:space:]]*rel[[:space:]]*$/) {
+      is_rel = 1
+    }
+  }
+
+  END {
+    emit_step()
+  }
+' "$release_workflow" > "$actual_resolver_steps"
+
+cat > "$expected_resolver_steps" <<'EOF'
+job=docker
+      - name: Check out workflow scripts
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
+
+job=docker
+      - name: Resolve release tag
+        id: rel
+        env:
+          DISPATCH_TAG: ${{ inputs.docker_backfill_tag }}
+          RELEASE_TAG: ${{ needs.release-please.outputs.tag_name }}
+        run: |
+          set -euo pipefail
+          scripts/resolve-release-tag.sh "${DISPATCH_TAG:-$RELEASE_TAG}"
+          # ghcr requires a lowercase repository path, and unlike metadata-action,
+          # buildx's `--output name=` does no lowercasing — a mixed-case owner
+          # makes the digest push fail with "invalid reference format".
+          echo "image=ghcr.io/${GITHUB_REPOSITORY,,}" >> "$GITHUB_OUTPUT"
+
+job=docker-manifest
+      - name: Check out workflow scripts
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
+
+job=docker-manifest
+      - name: Resolve release tag
+        id: rel
+        env:
+          DISPATCH_TAG: ${{ inputs.docker_backfill_tag }}
+          RELEASE_TAG: ${{ needs.release-please.outputs.tag_name }}
+        run: |
+          set -euo pipefail
+          scripts/resolve-release-tag.sh "${DISPATCH_TAG:-$RELEASE_TAG}"
+
+job=npm-publish
+      - name: Check out workflow scripts
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
+
+job=npm-publish
+      - name: Resolve release tag
+        id: rel
+        env:
+          DISPATCH_TAG: ${{ inputs.npm_backfill_tag }}
+          RELEASE_TAG: ${{ needs.release-please.outputs.tag_name }}
+        run: |
+          set -euo pipefail
+          scripts/resolve-release-tag.sh "${DISPATCH_TAG:-$RELEASE_TAG}"
+
+EOF
+
+if ! cmp "$expected_resolver_steps" "$actual_resolver_steps"; then
+  printf '%s\n' \
+    "release workflow resolver steps differ from the three reviewed blocks" >&2
+  diff -u "$expected_resolver_steps" "$actual_resolver_steps" >&2 || true
+  exit 1
+fi
+
+printf '%s\n' "release tag validation tests passed"