[anth-volk]

Fixes #37

The third review of #34 found two kinds of failure that stop a workstation emitter's telemetry module, and a token exchange that accepts a collector token it cannot send. Each behaviour change has its own failing test, committed first.

Changes

1. A saved login that cannot be read

• huggingface_token() raises UnreadableLoginError when neither HF_TOKEN nor HUGGINGFACE_TOKEN is set and reading the login saved by hf auth login fails: a PermissionError, a UnicodeDecodeError (the file is not text), or another OSError that names a file, such as IsADirectoryError. The error keeps only the original error's type name. It is raised outside the except block, so it does not keep the original error as its context either: that error's text names the file, and a UnicodeDecodeError holds the file's bytes.
• Every other error of huggingface_hub's get_token() propagates unchanged, as on main. While HF_OIDC_RESOURCE is set, huggingface_hub exchanges a CI OIDC token instead of reading the saved login, so none of its errors count: for example the HfHubHTTPError (an OSError that names no file) of a 503 from the Hub.
• The runs stay pending. CollectorDelivery records the pending reason huggingface_login_unreadable for each run it tries, and prints one warning per module that names only the error's type: Microcosm telemetry is waiting: the Hugging Face login saved by `hf auth login` could not be read (PermissionError), and neither HF_TOKEN nor HUGGINGFACE_TOKEN is set. Queued events stay pending, and are delivered once the login can be read. The dataset build will continue.
  • It reads the login again after the same backoff as after a collector outage (_defer_retry, 1 second doubling to 60).
  • Meanwhile waiting_for_credential is true, so the shutdown drain ends at once instead of waiting 15 seconds, as for a given token that can no longer be used. It is now a property: the given token can no longer be used, or the set of runs waiting for the login is not empty.
  • As soon as the session answers without UnreadableLoginError, whatever the exchange answered, this emitter clears the reason of every run in that set, including runs it had already registered, and empties the set. So a collector outage afterwards gets the usual shutdown retries, and a delivered run does not keep the reason.
  • A later emitter with a readable login delivers the runs too, and clears the reason when it registers each one.
• telemetry-token catches the same error for its exit 3, so the errors that mean "the saved login cannot be read" are listed in one function.

Why pending, not local-only. The issue allows either. Local-only cannot be undone, and flush_once would apply it to every pending run in the user's event queue file, including earlier builds' runs. On main those runs stayed in the file. A login file that exists can be repaired, for example a token file owned by another user, and the next emitter with a readable login should then deliver them.

UnreadableLoginError is an OSError, so the other modules that read the login behave as on main: the Orrery module (which shares the telemetry module's session through shared_session) still catches it in except (OSError, ValueError, KeyError, TypeError), and the collector submission worker (which has its own session) still catches it in except Exception.

2. A malformed collector answer

core.auth.NETWORK_FAILURES (OSError, TimeoutError, http.client.HTTPException) lists what _http_post raises when it gets no usable answer. The token exchange, run registration and the event upload in flush_once all use this one tuple. An answer that is not valid HTTP (BadStatusLine) or ends early, such as a truncated chunked answer (IncompleteRead), is therefore retried with backoff, as the README says network failures are. The run's state and its queued events do not change.

3. A collector token that cannot be sent

exchange_huggingface_credential applies _SENDABLE_CREDENTIAL to the collector's access_token, as it does to the Hugging Face credential. A token with a space, a line break or a non-ASCII character is an answer without a usable token: unavailable. telemetry-token then exits 5, and a workstation's telemetry module retries the exchange after the backoff instead of keeping a token that its next request would refuse with ValueError.

Documentation

• README, "Delivery and persistence": how an unreadable saved login is handled, which other errors do not count as one, and that an answer that is not valid HTTP or ends early counts as a network failure.
• README, telemetry-token exit codes: row 5 names the visible-ASCII rule for access_token, and row 7 says a failed OIDC token exchange exits 7 and why.
• CollectorSession's docstring and the comment on TelemetryRunRecord.local_only_reason describe the new pending reason.
• changelog.d/telemetry-keeps-running.fixed.md: merging publishes a patch release (0.11.1).

Not in scope

The issue's parts about deliver --spool and #36: #36 was closed unmerged, so that command does not exist.

Behaviour that differs from main outside the three fixes

telemetry-token with HF_OIDC_RESOURCE set, when the OIDC exchange fails with an OSError such as HfHubHTTPError, now exits 7 ("an unexpected HfHubHTTPError occurred") instead of 3. On main its own except (OSError, UnicodeDecodeError) reported that failure as a saved login that could not be read. It is not 5 either: that code means the collector, and the OIDC exchange fails at the CI provider or the Hub before the collector is contacted. Every OIDC failure now exits 7; on main, OIDCError and httpx errors already did.

Tests

Test	Before its fix	After
test_an_unreadable_saved_login_keeps_runs_pending_until_it_can_be_read (not readable by this user, not text): runs TelemetryModule.tick() with this run and an earlier one in the event queue file	On main: raised out of tick(). At round 1's local-only fix: both runs local-only	2 passed
test_delivery_resumes_once_the_saved_login_can_be_read	Failed: the run was local-only	Passed
test_a_registered_run_loses_the_unreadable_login_reason_once_it_can_be_read: the login cannot be read when the exchanged token is renewed	Failed at review round 2: the delivered run kept huggingface_login_unreadable	Passed
test_a_collector_outage_after_the_login_can_be_read_is_retried_at_shutdown: the login can be read again, the exchange answers 503	Failed at review round 2: waiting_for_credential stayed true	Passed
test_a_saved_login_that_cannot_be_read_raises_an_error_without_its_details (PermissionError, IsADirectoryError, an OSError for a symbolic link loop, UnicodeDecodeError)	Existing behaviour. Without the branch for an OSError that names a file, the two OSError cases fail; with the error raised inside the except block, all four fail (context kept)	4 passed
test_only_a_saved_login_that_cannot_be_read_counts_as_unreadable (Hub outage during the OIDC exchange, OIDC answer that is not text, Hub outage without OIDC)	3 failed: each became UnreadableLoginError	3 passed
telemetry-token exit codes, new case "OIDC token exchange that fails"	Exit 3	Exit 7
test_a_malformed_collector_answer_is_retried_like_a_network_failure (registration or events, each with a truncated chunked answer or one that is not HTTP, from a loopback collector): runs TelemetryModule.tick()	4 failed: IncompleteRead and BadStatusLine raised out of tick()	4 passed
test_a_token_answer_without_a_usable_token_and_a_lifetime_is_unusable, new cases: a token with a space, a line break, a non-ASCII character	3 failed: exit 0 instead of 5	Passed
test_a_collector_token_that_cannot_be_sent_is_retried_like_an_outage: runs TelemetryModule.tick()	With the exchange's token check removed: ValueError raised out of tick()	Passed

Locally, at 8ea9c54: uv run --no-sync pytest -m "not collector": 830 passed. tools/check-quality.sh and tools/check-changelog.sh pass.

🤖 Generated with Claude Code