@biffo/cli 0.252.1 → 0.252.3

package/_skeletons/sibling-template/services/api/src/api/config.py

@@ -23,6 +23,14 @@ class Settings(BaseSettings):
     # get or persist data (ADR-0002). Never add a database client here.
     core_api_url: str = ""
 
+    # NOT a free choice: this Lambda sits behind an HTTP API whose integration
+    # timeout is 29s, and `core_client` retries once, so the ceiling is
+    # 2 x this value < 29s. Twelve leaves comfortable room above core's measured
+    # ~7.8s cold start (tabsii-platform#567) and still lands at 24s worst case.
+    # Raising it past ~14 makes the gateway time out first, which returns a 504
+    # with no message rather than the explained one core_client produces.
+    core_api_timeout_seconds: float = 12.0
+
     environment: str = "dev"
     log_level: str = "INFO"
     cors_origins: list[str] = ["http://localhost:3000"]

package/_skeletons/sibling-template/services/api/src/api/core_client.py

@@ -1,3 +1,32 @@
+"""The only route from this sibling to the core project's API (ADR-0002/0007).
+
+## The timeout budget, and why it is not a free choice (tabsii-crm#221)
+
+Every call here runs inside a Lambda behind an HTTP API whose **integration
+timeout is 29s** (`aws apigatewayv2 get-integrations` — the Lambda itself is
+configured for 30s, so the gateway is the binding constraint). Anything this
+client waits for is spent from that 29s. Exceed it and the caller gets a
+gateway 504 with no message at all, which is strictly worse than a slow answer.
+
+So the numbers below are derived, not picked:
+
+    first attempt   CORE_API_TIMEOUT_SECONDS   12s
+    one retry       CORE_API_TIMEOUT_SECONDS   12s
+                                             ----
+    worst case                                24s   <  29s gateway ceiling
+
+The previous value was a hardcoded `timeout=10`, copied into every call site.
+Against core's measured **~7.8s cold start** (tabsii-platform#567) that left
+roughly two seconds for the actual work, and a cold core produced
+`httpx.ReadTimeout` -> an unhandled exception -> a 500 Internal Server Error on
+whichever surface a session happened to hit first. Reloading fixed it, because
+the second request found the Lambda warm — which is precisely what the retry
+now does automatically.
+
+Worth knowing which way the risk runs in a quiet app: a surface hit *less*
+often than a busy landing page makes a cold core **more** likely, not less.
+"""
+
 import httpx
 from fastapi import HTTPException, Security, status
 from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
@@ -6,6 +35,39 @@ from .config import settings
 
 _security = HTTPBearer()
 
+#: What a caller is told when core does not answer in time. A timeout is a
+#: transient condition with an obvious user action, so it says so — unlike the
+#: bare "Internal Server Error" this replaces, which described the symptom to
+#: the one person who could do nothing about it.
+_TIMEOUT_DETAIL = (
+    "The service took too long to respond. This usually clears on a retry — "
+    "please try again in a moment."
+)
+
+
+def _may_retry(method: str, exc: httpx.TimeoutException) -> bool:
+    """Whether re-sending ``method`` after ``exc`` is safe.
+
+    **This is a correctness question, not a tuning one.** A blanket retry would
+    be a data-integrity bug: `ReadTimeout` means the request *was* delivered and
+    we simply never saw the answer, so core may well have processed it. Re-sending
+    a POST in that state creates the row twice, and the user sees one success.
+
+    * ``ConnectTimeout`` — the connection was never established, so core cannot
+      have seen the request. Safe for **any** verb.
+    * ``ReadTimeout`` and everything else — sent, outcome unknown. Safe only for
+      ``GET``, which changes nothing by definition.
+
+    PUT and DELETE are idempotent in HTTP's sense and are still excluded
+    deliberately: core's DELETE is a soft delete, so a retry that lands after a
+    first attempt succeeded would answer 404 and turn a success into an error the
+    caller cannot distinguish from a real one. The cold-start case this exists for
+    is a page load — a GET — so nothing is lost by being strict here.
+    """
+    if isinstance(exc, httpx.ConnectTimeout):
+        return True
+    return method == "GET"
+
 
 class CoreApiError(Exception):
     def __init__(self, status_code: int, detail: str) -> None:
@@ -17,29 +79,48 @@ class CoreApiError(Exception):
 def _extract_detail(response: httpx.Response) -> str:
     """The message a caller should see for an upstream error, not the whole body.
 
-    The core's own error responses are JSON like ``{"detail": "..."}`` --
+    The core's own error responses are JSON like ``{"detail": "..."}`` —
     ``response.text`` is that ENTIRE body, so raising it as-is and then handing
-    it to FastAPI's ``HTTPException(detail=...)`` serialises it a second time.
+    it to FastAPI's `HTTPException(detail=...)` serialises it a second time.
     The client then receives ``{"detail": "{\\"detail\\": \\"<message>\\"}"}``:
     valid JSON, but a JSON *string* rather than the message inside it, and any
-    component that renders ``detail`` shows that raw escaped blob to a user
-    (tabsii-crm#137).
+    component that renders `detail` shows that raw escaped blob to a user
+    (tabsii-crm#137, and independently tabsii-lms — see the note at the foot).
 
-    Parsed rather than assumed: a non-JSON or JSON-without-``detail`` upstream
+    Parsed rather than assumed: a non-JSON or JSON-without-`detail` upstream
     body (a proxy timeout page, a differently-shaped error) falls back to the
     raw text unchanged, so this never hides information the caller had before.
 
-    Fixed in two siblings independently before it was ever fixed HERE, which is
-    why three more were still shipping ``response.text`` months later. The
-    browser-side twin is ``extractErrorMessage`` in
-    ``apps/frontend/src/lib/api-client.ts``; keep the two in step.
+    **`detail` is not always a string, and a dict one is the same bug.** Core's
+    generic CRUD layer answers an integrity error with
+    ``{"detail": {"message": "...", "constraint": "..."}}``
+    (`routing/crud_handlers._integrity_error_response`), which the `isinstance`
+    check above rejects — so it fell to `response.text` and rebuilt
+    tabsii-crm#137 exactly, one shape further in. The visible cost there was a
+    delete refusal (tabsii-crm#272): the schema had written the user a sentence
+    naming what still depends on the record and prescribing the remedy, and the
+    browser showed the escaped JSON blob wrapped around it instead.
+
+    So a dict `detail` carrying a **string `message`** is unwrapped to that
+    message. `constraint` is deliberately dropped rather than appended — it is
+    a database object name, which is the schema reconnaissance
+    tabsii-platform#473 exists to keep out of a browser, and it says nothing to
+    the person reading the sentence.
+
+    Only the message key is trusted: a dict `detail` **without** one still falls
+    back to the raw text, because inventing a summary from a shape nobody has
+    declared would hide information rather than surface it.
     """
     try:
         body = response.json()
     except ValueError:
         return response.text
-    if isinstance(body, dict) and isinstance(body.get("detail"), str):
-        return body["detail"]
+    if isinstance(body, dict):
+        detail = body.get("detail")
+        if isinstance(detail, str):
+            return detail
+        if isinstance(detail, dict) and isinstance(detail.get("message"), str):
+            return detail["message"]
     return response.text
 
 
@@ -60,27 +141,59 @@ class CoreApiClient:
     def __init__(self, bearer_token: str) -> None:
         self._bearer_token = bearer_token
 
+    async def _send(self, method: str, path: str, body: dict | None = None) -> httpx.Response:
+        """Issue one core request, retrying once where that is provably safe.
+
+        Every verb goes through here so the timeout is stated **once**. It was
+        previously copied into every method, which is how it stayed at 10s while
+        core's cold start grew past it — a literal repeated once per verb is one
+        place to forget per verb (tabsii-crm#221).
+        """
+        headers = {"Authorization": f"Bearer {self._bearer_token}"}
+        attempts = 2
+        for attempt in range(1, attempts + 1):
+            try:
+                async with httpx.AsyncClient(
+                    base_url=settings.core_api_url,
+                    timeout=settings.core_api_timeout_seconds,
+                ) as client:
+                    return await client.request(method, path, json=body, headers=headers)
+            except httpx.TimeoutException as exc:
+                if attempt == attempts or not _may_retry(method, exc):
+                    raise CoreApiError(status.HTTP_504_GATEWAY_TIMEOUT, _TIMEOUT_DETAIL) from exc
+        raise AssertionError("unreachable: the loop either returns or raises")
+
     async def get(self, path: str) -> dict:
-        async with httpx.AsyncClient(base_url=settings.core_api_url, timeout=10) as client:
-            response = await client.get(
-                path,
-                headers={"Authorization": f"Bearer {self._bearer_token}"},
-            )
+        response = await self._send("GET", path)
         if response.is_error:
             raise CoreApiError(response.status_code, _extract_detail(response))
         return response.json()  # type: ignore[no-any-return]
 
     async def post(self, path: str, body: dict) -> dict:
-        async with httpx.AsyncClient(base_url=settings.core_api_url, timeout=10) as client:
-            response = await client.post(
-                path,
-                json=body,
-                headers={"Authorization": f"Bearer {self._bearer_token}"},
-            )
+        response = await self._send("POST", path, body)
         if response.is_error:
             raise CoreApiError(response.status_code, _extract_detail(response))
         return response.json()  # type: ignore[no-any-return]
 
+    async def put(self, path: str, body: dict) -> dict:
+        response = await self._send("PUT", path, body)
+        if response.is_error:
+            raise CoreApiError(response.status_code, _extract_detail(response))
+        return response.json()  # type: ignore[no-any-return]
+
+    async def patch(self, path: str, body: dict) -> dict:
+        response = await self._send("PATCH", path, body)
+        if response.is_error:
+            raise CoreApiError(response.status_code, _extract_detail(response))
+        return response.json()  # type: ignore[no-any-return]
+
+    async def delete(self, path: str) -> dict:
+        response = await self._send("DELETE", path)
+        if response.is_error:
+            raise CoreApiError(response.status_code, _extract_detail(response))
+        # DELETE may return an empty body; tolerate that.
+        return response.json() if response.content else {}  # type: ignore[no-any-return]
+
 
 def get_core_client(
     credentials: HTTPAuthorizationCredentials = Security(_security),
@@ -91,3 +204,22 @@ def get_core_client(
             detail="core_api_url is not configured",
         )
     return CoreApiClient(credentials.credentials)
+
+
+# ── Why this file is shared, and what it cost to learn ──────────────────────
+#
+# Every sibling talks to core through a copy of this module. That copy used to
+# drift, and the drift was expensive twice over:
+#
+#   • `_extract_detail` was written TWICE, independently, in two siblings
+#     fixing the same user-visible bug, because neither author could discover
+#     the other had already solved it (biffo-template#1107/#1108).
+#   • The retry-and-timeout work was then ported a second time the same way
+#     (tabsii-crm#221 -> tabsii-lms#65/#66), and the dict-`detail` fix
+#     (tabsii-crm#272) reached only the repo that found it.
+#
+# So this file is declared in `shared-files.json` under `mustBeUniform`: the
+# sync measures its variants and fails when they exceed the recorded baseline,
+# rather than overwriting anybody. If you fix something here, fix it UPSTREAM in
+# the skeleton and let it reach the others — a fix that lives in one sibling is
+# a fix the next author will write again from scratch.

package/_skeletons/sibling-template/services/api/tests/test_core_client.py

@@ -1,29 +1,27 @@
-"""A proxied error must reach a caller as a plain message, not a JSON string
-re-serialised from an already-JSON upstream body.
-
-`CoreApiClient` raises `CoreApiError(status_code, detail)` on every verb, and a
-router turns that into `HTTPException(status_code=exc.status_code,
-detail=exc.detail)`. When `detail` was `response.text` — the WHOLE upstream
-body — a core error like `{"detail": "Method Not Allowed"}` became, once
-FastAPI serialised it a second time, `{"detail": "{\\"detail\\": \\"Method Not
-Allowed\\"}"}`: valid JSON, but a JSON *string* rather than the message inside
-it. Any component that renders `detail` showed that raw escaped blob to a user.
+"""tabsii-crm#137 — a proxied error must reach a caller as a plain message, not a
+JSON string re-serialised from an already-JSON upstream body.
 
-Found and fixed independently in two siblings (tabsii-crm#137, tabsii-lms#13)
-before it was ever fixed in this skeleton, so three more siblings were still
-shipping the bug months later. The test lives here now so a sibling is born
-with it.
+`CoreApiClient` raises `CoreApiError(status_code, detail)` on every verb, and
+every router does `HTTPException(status_code=exc.status_code, detail=exc.detail)`.
+Before this fix, `detail` was `response.text` — the WHOLE upstream body — so a
+core error like `{"detail": "Method Not Allowed"}` became, once FastAPI
+serialised it a second time, `{"detail": "{\\"detail\\": \\"Method Not
+Allowed\\"}"}`: valid JSON, but a JSON *string* rather than the message inside
+it. Any component that renders `detail` showed that raw escaped blob.
 """
 
+from pathlib import Path
+
 import httpx
 import pytest
 
+from api import core_client as core_client_module
 from api.config import settings
 from api.core_client import CoreApiClient, CoreApiError, _extract_detail
 
 
 class TestExtractDetail:
-    """The parsing rule alone, with no network involved."""
+    """Unit-level: the parsing rule alone, with no network involved."""
 
     def test_unwraps_a_json_detail_body(self) -> None:
         response = httpx.Response(422, json={"detail": "Method Not Allowed"})
@@ -46,28 +44,243 @@ class TestExtractDetail:
         assert _extract_detail(response) == response.text
 
 
+class TestIntegrityRefusalDetail:
+    """tabsii-crm#272 — the same bug as tabsii-crm#137, one shape further in.
+
+    Core's generic CRUD layer answers an integrity error with a **dict**
+    `detail` (`{"message": ..., "constraint": ...}`), which the original
+    string-only check rejected. So it fell through to `response.text` and
+    rebuilt the exact defect this module was written to fix.
+
+    It was not hypothetical. A delete refused because other records still
+    depend on the row came back from the schema as a sentence written FOR THE
+    USER, naming what depends on it and prescribing the remedy — and the user
+    saw the escaped JSON blob wrapped around that sentence instead.
+    """
+
+    #: A real refusal of that shape, trimmed. The remedy clause is the
+    #: load-bearing part — it is the only thing telling the user what to do
+    #: instead, and it is exactly what the escaped blob buried.
+    _REFUSAL = (
+        "record 0c0de102 cannot be deleted: 3 dependent record(s) reference it. "
+        "Set status to 'archived' instead — an archived record leaves the "
+        "active list while every reference stays intact."
+    )
+
+    def test_a_dict_detail_is_unwrapped_to_its_message(self) -> None:
+        response = httpx.Response(
+            409, json={"detail": {"message": self._REFUSAL, "constraint": None}}
+        )
+        assert _extract_detail(response) == self._REFUSAL
+
+    def test_the_raw_body_does_not_reach_the_caller(self) -> None:
+        """The failure mode stated positively: no JSON punctuation, because a
+        blob starting `{"detail":{"message":` is what the author actually saw."""
+        response = httpx.Response(
+            409, json={"detail": {"message": self._REFUSAL, "constraint": None}}
+        )
+        extracted = _extract_detail(response)
+        assert not extracted.startswith("{")
+        assert '"detail"' not in extracted
+
+    def test_the_constraint_name_is_dropped_not_appended(self) -> None:
+        """A constraint name is a database object name — schema reconnaissance
+        (tabsii-platform#473), and meaningless to whoever reads the sentence."""
+        response = httpx.Response(
+            409,
+            json={"detail": {"message": "That name is already taken.", "constraint": "uq_x_name"}},
+        )
+        assert _extract_detail(response) == "That name is already taken."
+
+    def test_a_dict_detail_with_no_message_still_falls_back(self) -> None:
+        """Only the declared key is trusted. Summarising a shape nobody has
+        declared would hide information rather than surface it — the same
+        principle as the non-JSON fallback above."""
+        response = httpx.Response(500, json={"detail": {"code": "E17", "constraint": None}})
+        assert _extract_detail(response) == response.text
+
+
 class TestCoreApiClientErrorPassthrough:
-    """A mocked upstream error reaches `CoreApiError.detail` flat."""
+    """End-to-end: a mocked upstream error reaches `CoreApiError.detail` flat."""
 
     async def test_get_surfaces_the_inner_message_not_the_whole_body(
         self, monkeypatch: pytest.MonkeyPatch
     ) -> None:
-        monkeypatch.setattr(settings, "core_api_url", "https://core.example.com")
+        def handler(request: httpx.Request) -> httpx.Response:
+            return httpx.Response(404, json={"detail": "Brand not found"})
+
+        _install_mock_transport(monkeypatch, handler)
+
+        client = CoreApiClient("a-token")
+        with pytest.raises(CoreApiError) as exc_info:
+            await client.get("/api/v1/brands/does-not-exist")
+
+        assert exc_info.value.status_code == 404
+        # The regression this guards: NOT '{"detail": "Brand not found"}'.
+        assert exc_info.value.detail == "Brand not found"
 
+    async def test_post_surfaces_the_inner_message_not_the_whole_body(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
         def handler(request: httpx.Request) -> httpx.Response:
-            return httpx.Response(403, json={"detail": "Administrator access required"})
+            return httpx.Response(405, json={"detail": "Method Not Allowed"})
+
+        _install_mock_transport(monkeypatch, handler)
+
+        client = CoreApiClient("a-token")
+        with pytest.raises(CoreApiError) as exc_info:
+            await client.post("/api/v1/fdds", {})
+
+        assert exc_info.value.status_code == 405
+        assert exc_info.value.detail == "Method Not Allowed"
+
+
+def _install_mock_transport(monkeypatch: pytest.MonkeyPatch, handler) -> None:
+    """Make `CoreApiClient`'s internal `httpx.AsyncClient(...)` use a
+    `MockTransport` instead of a real connection, while leaving every other
+    constructor argument (`base_url`, `timeout`) exactly as production passes
+    them.
+
+    `settings.core_api_url` also needs a real-looking base URL here: it
+    defaults to `""` outside a deployed environment, and httpx's cookie
+    handling chokes on a scheme-less, host-less request URL before the mock
+    transport is ever reached.
+    """
+    monkeypatch.setattr(settings, "core_api_url", "https://core.example.test")
+
+    real_async_client = httpx.AsyncClient
+
+    def fake_async_client(*args: object, **kwargs: object) -> httpx.AsyncClient:
+        kwargs["transport"] = httpx.MockTransport(handler)
+        return real_async_client(*args, **kwargs)
+
+    monkeypatch.setattr("api.core_client.httpx.AsyncClient", fake_async_client)
+
+
+class TestTimeoutHandling:
+    """tabsii-crm#221 — a cold core must not surface as "Internal Server Error".
+
+    The reported failure: a landing page rendered *"Signed in, but could
+    not reach the API: Internal Server Error"* whenever core had gone cold. The
+    BFF's hardcoded 10s budget was shorter than core's ~7.8s cold start plus the
+    work itself, so `httpx.ReadTimeout` escaped as an unhandled exception.
+    """
+
+    async def test_a_timeout_becomes_a_504_with_an_explained_message(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Not a 500, and not the raw exception.
+
+        A 504 is what actually happened — an upstream did not answer — and the
+        detail tells the reader the one thing they can act on. The old behaviour
+        told them the platform was broken when it was merely asleep.
+        """
+
+        def handler(request: httpx.Request) -> httpx.Response:
+            raise httpx.ReadTimeout("core is cold", request=request)
+
+        _install_mock_transport(monkeypatch, handler)
+
+        client = CoreApiClient("a-token")
+        with pytest.raises(CoreApiError) as exc_info:
+            await client.get("/api/v1/whoami")
+
+        assert exc_info.value.status_code == 504
+        assert "try again" in exc_info.value.detail.lower()
+        assert "internal server error" not in exc_info.value.detail.lower()
+
+    async def test_a_get_is_retried_once_and_a_warm_second_attempt_succeeds(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """The actual repair for the reported bug.
+
+        The user's own workaround was to reload the page, which worked because
+        the second request found the Lambda warm. This does that for them.
+        """
+        calls: list[str] = []
+
+        def handler(request: httpx.Request) -> httpx.Response:
+            calls.append(request.method)
+            if len(calls) == 1:
+                raise httpx.ReadTimeout("core is cold", request=request)
+            return httpx.Response(200, json={"ok": True})
+
+        _install_mock_transport(monkeypatch, handler)
+
+        assert await CoreApiClient("a-token").get("/api/v1/whoami") == {"ok": True}
+        assert calls == ["GET", "GET"], "the first attempt must be retried exactly once"
+
+    async def test_a_post_is_never_retried_after_a_read_timeout(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """**The data-integrity half, and the reason `_may_retry` exists.**
+
+        A `ReadTimeout` means the request reached core and the answer was lost —
+        core may have processed it. Re-sending a POST in that state creates the
+        row twice and the caller sees a single success. So a write times out
+        once and stops.
+
+        If a later change makes this fail, the fix is never "retry everything":
+        it is to give the write an idempotency key so a retry can be recognised.
+        """
+        calls: list[str] = []
+
+        def handler(request: httpx.Request) -> httpx.Response:
+            calls.append(request.method)
+            raise httpx.ReadTimeout("core is cold", request=request)
+
+        _install_mock_transport(monkeypatch, handler)
+
+        with pytest.raises(CoreApiError) as exc_info:
+            await CoreApiClient("a-token").post("/api/v1/leads", {"name": "x"})
+
+        assert exc_info.value.status_code == 504
+        assert calls == ["POST"], "a write must NOT be re-sent — it may have been applied"
+
+    async def test_a_post_is_retried_after_a_connect_timeout(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """The distinction the test above depends on.
+
+        A `ConnectTimeout` never established a connection, so core provably did
+        not see the request and re-sending cannot duplicate anything. Without
+        this case the previous test would pass just as well against a client that
+        never retried writes for the *wrong* reason.
+        """
+        calls: list[str] = []
+
+        def handler(request: httpx.Request) -> httpx.Response:
+            calls.append(request.method)
+            if len(calls) == 1:
+                raise httpx.ConnectTimeout("no connection", request=request)
+            return httpx.Response(200, json={"created": True})
+
+        _install_mock_transport(monkeypatch, handler)
 
-        transport = httpx.MockTransport(handler)
-        original = httpx.AsyncClient
+        assert await CoreApiClient("a-token").post("/api/v1/leads", {"n": 1}) == {"created": True}
+        assert calls == ["POST", "POST"]
 
-        def patched(*args, **kwargs):  # type: ignore[no-untyped-def]
-            kwargs["transport"] = transport
-            return original(*args, **kwargs)
+    async def test_the_retry_budget_fits_inside_the_gateway_ceiling(self) -> None:
+        """The arithmetic, asserted rather than left in a comment.
 
-        monkeypatch.setattr(httpx, "AsyncClient", patched)
+        The HTTP API integration times out at 29s. Two attempts at the configured
+        timeout must finish inside that, or the gateway answers first and the
+        caller gets a bare 504 with none of the explanation above. Someone raising
+        the timeout to "be safe" would silently reintroduce the original bug in a
+        new form; this stops them.
+        """
+        gateway_ceiling_seconds = 29
+        assert settings.core_api_timeout_seconds * 2 < gateway_ceiling_seconds
 
-        with pytest.raises(CoreApiError) as excinfo:
-            await CoreApiClient("token").get("/api/v1/admin/users")
+    async def test_every_verb_shares_one_timeout(self) -> None:
+        """The duplication that let the value go stale is gone.
 
-        assert excinfo.value.detail == "Administrator access required"
-        assert excinfo.value.status_code == 403
+        The timeout was copied into all five methods, so it stayed at 10 while
+        core's cold start grew past it. Any reappearance of a literal here means
+        the next person has five places to update again.
+        """
+        source = Path(core_client_module.__file__).read_text()
+        code = "\n".join(line for line in source.splitlines() if not line.strip().startswith("#"))
+        body = code.split('"""', 2)[-1]  # drop the module docstring
+        assert "timeout=10" not in body
+        assert body.count("settings.core_api_timeout_seconds") == 1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biffo/cli",
-  "version": "0.252.1",
+  "version": "0.252.3",
   "description": "Biffo project scaffolding CLI",
   "license": "MIT",
   "type": "module",

package/scripts/verify.sh

@@ -242,6 +242,14 @@ SKIPPED=""
 # repo demonstrably has -- absence and blindness reading identically is the
 # defect, not a formatting nit.
 NOT_RUN=""
+# Checks that DID run but could not produce a verdict -- kept apart from
+# FAILED because "cannot tell" and "found something wrong" are different
+# facts, and #703 recorded the cost of rendering them the same: a killed
+# pg-test lane printed `verify failed: pg-test` naming no failing test, and
+# sent the reader hunting a bug that was never there. Same convention
+# `wait-for-checks.sh` and `branch-health.sh` already use: a distinct bucket,
+# a distinct exit code (2), and it is NEVER treated as a pass.
+INCONCLUSIVE=""
 # Defined up here, not inside run_check. `run_check` returns EARLY in --list
 # mode, before it would set this -- so `pytest_record "$d" "$LAST_CHECK_SECONDS"`
 # read an unset variable and `set -u` killed the script silently, mid-list.
@@ -657,14 +665,23 @@ fi
 # assertion failure on a feature branch that a local run would have caught. The
 # gate simply did not run it: `verify.sh` had no reference to Postgres in any
 # form, so a required check that costs a full CI round trip had no local
-# counterpart. Measured on tabsii-platform: schema build ~2s, 310 tests ~28s.
+# counterpart.
 #
 # The budget is deliberately its own, and larger than pytest's. `pytest_is_fast`
 # excludes a suite over 15s because a slow unit suite slows every push for a
 # class of failure the fast checks mostly catch first; this lane is the opposite
-# trade -- it is the ONLY local sight of a required check, and 30s against a
-# ~7-minute CI round trip pays for itself the first time it fires.
-PG_TEST_BUDGET_SECONDS="${BIFFO_VERIFY_PG_BUDGET:-120}"
+# trade -- it is the ONLY local sight of a required check, and paying tens of
+# seconds against a ~7-minute CI round trip pays for itself the first time it
+# fires.
+#
+# Re-measured 2026-08-06 (#703): tabsii-platform's lane had grown from the
+# 310 tests / ~28s this number was originally chosen against to 791-805 tests
+# in one day, and six consecutive runs came in at 93, 101, 105, 107, 107, 108s
+# -- against the 120s budget that left as little as 12s of margin, and
+# shrinking with every test the suite gains. Doubled to 240s, the same
+# doubling this file already suggests as the retry (below) -- comfortable
+# headroom today, and re-measure this comment again once it stops being so.
+PG_TEST_BUDGET_SECONDS="${BIFFO_VERIFY_PG_BUDGET:-240}"
 PG_TEST_DSN="${BIFFO_TEST_PG_DSN:-${TABSII_TEST_PG_DSN:-}}"
 
 # `.claude/worktrees` is excluded alongside `.worktrees`, and finding out why
@@ -702,7 +719,17 @@ pg_test_run() {
   # tabsii-platform (#703) -- the same push succeeded on retry, unchanged.
   #
   # Same discipline as `wait-for-checks` and the dependency audits: "could not
-  # determine" must never wear the clothes of "found something wrong".
+  # determine" must never wear the clothes of "found something wrong" -- and
+  # since that discipline is a distinct EXIT STATUS everywhere else in this
+  # estate (2 = cannot tell, never a pass), not just a distinct message, this
+  # returns 2 rather than 1. The message alone was #1346's fix; it left the
+  # exit code lumped in with a real failure because `run_check`'s generic
+  # caller only sees pass/fail -- the pg-test call site below now reads this
+  # return value directly instead of going through it, precisely so a timeout
+  # can carry its own status without teaching every OTHER check (ruff, pyright,
+  # bandit, pytest, terraform fmt, ...) that exit 2 means something different
+  # from a real failure, when several of those tools already use 2 for their
+  # OWN internal errors.
   if [ "$_pg_rc" -eq 124 ] || [ "$_pg_rc" -eq 137 ]; then
     echo "TIMED OUT after ${_pg_elapsed}s (budget ${PG_TEST_BUDGET_SECONDS}s)."
     echo ""
@@ -720,7 +747,7 @@ pg_test_run() {
     echo "Partial output before the kill (NOT a result):"
     tail -15 "$_out"
     rm -f "$_out"
-    return 1
+    return 2
   fi
 
   if [ "$_pg_rc" -ne 0 ]; then
@@ -847,8 +874,42 @@ else
     skip pg-test "no pyproject.toml above the Postgres modules"
   else
     _pg_rel=$(echo "$_pg_modules" | sed "s|^$_pg_dir/||" | tr '\n' ' ')
-    # shellcheck disable=SC2086
-    run_check pg-test pg_test_run "$_pg_dir" "$_pg_rel"
+    # Not a plain `run_check` call: `pg_test_run` returns THREE states (0 pass,
+    # 1 real failure, 2 timed out/inconclusive -- see its own comment), and
+    # `run_check` only ever sees pass/fail, so routing through it would collapse
+    # a timeout back into FAILED and reproduce the exact #703 defect this whole
+    # change exists to fix. This reads the return code directly instead.
+    if [ -n "$LIST" ]; then
+      # shellcheck disable=SC2086
+      echo pg_test_run "$_pg_dir" "$_pg_rel"
+    else
+      _pg_check_start=$(date +%s)
+      # shellcheck disable=SC2086
+      pg_test_run "$_pg_dir" "$_pg_rel" >"/tmp/biffo-verify-pg-check.$$" 2>&1
+      _pg_check_rc=$?
+      _pg_check_elapsed=$(($(date +%s) - _pg_check_start))
+      case "$_pg_check_rc" in
+        0)
+          PASSED="$PASSED pg-test"
+          printf '  \033[32mOK\033[0m   %-16s %ss\n' "pg-test" "$_pg_check_elapsed"
+          ;;
+        2)
+          # Cannot tell -- never a pass, and deliberately never FAILED either.
+          # pg_test_run's own output already explains why and how to re-run,
+          # so it is printed in full here rather than truncated the way a
+          # genuine failure's output is below.
+          INCONCLUSIVE="$INCONCLUSIVE pg-test"
+          printf '  \033[33mINCONCLUSIVE\033[0m %-16s %ss\n' "pg-test" "$_pg_check_elapsed"
+          sed 's/^/      /' "/tmp/biffo-verify-pg-check.$$"
+          ;;
+        *)
+          FAILED="$FAILED pg-test"
+          printf '  \033[31mFAIL\033[0m %-16s %ss\n' "pg-test" "$_pg_check_elapsed"
+          sed 's/^/      /' "/tmp/biffo-verify-pg-check.$$" | tail -25
+          ;;
+      esac
+      rm -f "/tmp/biffo-verify-pg-check.$$"
+    fi
   fi
 fi
 
@@ -1106,6 +1167,22 @@ if [ -n "$FAILED" ]; then
   printf 'Most format failures are one command: pnpm run format\n\n'
   exit 1
 fi
+if [ -n "$INCONCLUSIVE" ]; then
+  # A real FAILED above always wins this race -- it is the more actionable
+  # fact and must not be buried under a lane that merely ran out of time. Only
+  # once nothing genuinely failed does "could not tell" get to speak for the
+  # whole run, and even then it is never a pass: same three-valued contract as
+  # `wait-for-checks.sh` and `branch-health.sh` (0 green, 1 failed, 2 cannot
+  # tell), and `cli/src/lib/packaged-script-command.ts` already promises every
+  # script reached through `scripts/biffo.sh` passes its exit code through
+  # unchanged -- so this is not a new contract, it is this file finally
+  # keeping the one that already existed.
+  printf '\033[33mverify inconclusive:\033[0m%s\n' "$INCONCLUSIVE"
+  printf 'Not a failure -- the lane above could not produce a verdict (see its own\n'
+  printf 'output, printed above, for why and what to do about it). Do not go\n'
+  printf 'looking for a bug on this evidence; re-run once the cause is addressed.\n\n'
+  exit 2
+fi
 if [ -z "$PASSED" ]; then
   # "Nothing applicable ran" is a different outcome from "checks passed", and
   # conflating them is the exact failure this gate exists to remove -- the