fix: flag cached auth failures needing manual renewal

docs/account-archive-history.md

@@ -143,6 +143,12 @@ cache read does not prove that Firstrade still accepts the session: an upstream
 endpoint returns the sanitized `readonly_client_unavailable` response and logs
 the fixed diagnostic, without retrying or starting a login.
 
+For a missing/expired cache or an upstream 401, the same log also carries
+`recovery_action=manual_session_renewal_required`. Storage read failures,
+upstream 403 and upstream 5xx do not imply that renewing authentication will fix
+the failure. The HTTP status and response body remain unchanged, and the
+account-facts route never calls `/session-renew` itself.
+
 `Inspect cached account history schema` reads one first page for the current
 serving runtime's exact account and at most 31 closed UTC dates within the past
 year. It uses the same configured deployment identity, the existing username

main.py

@@ -137,6 +137,10 @@ def _log_account_facts_failure(reason: object, stage: object = "unclassified", h
     status = http_status if type(http_status) is int and 100 <= http_status <= 599 else None
     entry = {"severity": "WARNING", "message": "account_facts_sync failed",
              "reason": reason, "stage": stage, "http_status": status}
+    if (reason in {"cache_missing", "cache_stale", "cache_missing_or_stale"}
+            or (reason == "read_http_error" and status == 401
+                and stage in {"userinfo", "account_list", "account_read"})):
+        entry["recovery_action"] = "manual_session_renewal_required"
     project = get_project_id()
     header = request.headers.get("X-Cloud-Trace-Context", "")
     trace = re.fullmatch(r"([0-9a-fA-F]{32})(?:/[0-9]+)?(?:;o=[01])?", header)

tests/test_account_facts_endpoint.py

@@ -31,6 +31,7 @@ def failed_client():
     assert response.json == {"ok": False, "error": "readonly_client_unavailable"}
     line = capsys.readouterr().out.strip()
     payload = json.loads(line)
+    assert payload["recovery_action"] == "manual_session_renewal_required"
     trace = payload.pop("logging.googleapis.com/trace")
     entry = {"resource": {"type": "cloud_run_revision", "labels": {
         "project_id": PROJECT, "location": "us-central1", "service_name": SERVICE}},
@@ -43,6 +44,36 @@ def failed_client():
     assert "synthetic-native-id" not in line
 
 
+@pytest.mark.parametrize("reason,stage,status,renewal", [
+    ("cache_stale", "cache", None, True),
+    ("cache_missing", "cache", None, True),
+    ("read_http_error", "userinfo", 401, True),
+    ("read_http_error", "userinfo", 403, False),
+    ("read_http_error", "userinfo", 503, False),
+    ("cache_read_failed", "cache", None, False),
+])
+def test_cached_failure_requires_separate_manual_auth_flow(
+    monkeypatch, capsys, reason, stage, status, renewal,
+):
+    _configure(monkeypatch)
+    calls = []
+    def fail_client():
+        calls.append("cached_read")
+        raise FirstradeCachedSessionError(reason, stage=stage, http_status=status)
+    def forbidden(*args, **kwargs):
+        pytest.fail("failed cached read must not renew or publish")
+    monkeypatch.setattr(main, "READ_ONLY_ACCOUNT_FACTS_CLIENT_BUILDER", fail_client)
+    monkeypatch.setattr(main, "run_forced_session_renewal", forbidden)
+    monkeypatch.setattr(main, "publish_firstrade_account_snapshot", forbidden)
+    response = main.app.test_client().post("/account-facts-sync", headers={
+        "Authorization": "Bearer synthetic-facts-token"})
+    assert response.status_code == 503
+    assert response.json == {"ok": False, "error": "readonly_client_unavailable"}
+    assert calls == ["cached_read"]
+    record = json.loads(capsys.readouterr().out)
+    assert (record.get("recovery_action") == "manual_session_renewal_required") is renewal
+
+
 @pytest.mark.parametrize("header,project", [(None, "example-project"), ("bad", "example-project"),
                                              ("a" * 32, None),
                                              ("a" * 32 + "/1;o=1", "bad/project")])