feat(ops): add bounded Worker health reader

[vincentkoc]

What Problem This Solves

Operators need a narrow, manual view of native Worker traffic and execution
health. Those metrics are separate from feature-recording outcomes and do not
prove telemetry delivery.

Changes

• Add npm run --silent worker:health for the fixed openclaw-telemetry Worker
  using existing CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID environment
  inputs.
• Read one lagged 24-hour UTC window through one fixed GraphQL POST, with a
  cumulative ten-second deadline, a 64 KiB response cap, and no retries or
  redirects.
• Require 24 complete hourly groups and valid counts; preserve adaptive
  estimates and report bounded available/unavailable results.
• Add an operator runbook and operational changelog entry.
• Integrate current main at bd314c2bab12db17263198257bb452fd081d30d1.
  The health module, CLI, tests, and runbook are unchanged from the previous
  reviewed head. Main's removed public dashboard and statistics endpoint stay
  removed; the obsolete stats-secret paragraph is not restored.

Scope And Limits

This is manual operator tooling, not a public dashboard or scheduled collector.
It changes no Worker runtime, client collection, logging, storage, or deployment
configuration. There is no credential discovery, OAuth refresh, credential
persistence, or grant change.

Worker metrics aggregate all routes and domains and exclude WAF-blocked
requests. Invocation statuses are not HTTP status codes. These estimates do
not establish feature validation, quota outcomes, durable Analytics Engine
acknowledgement, unique users, or delivery success.

Validation

• Fresh npm run check on Node.js 24.19.0: vocabulary validation,
  typechecking, and 401 tests across 12 files passed.
• Fresh Wrangler 4.129.0 deploy --dry-run: passed.
• The full suite includes workerd HTTP proof that /api/stats returns
  404 with Cache-Control: no-store, update checks still succeed, and the
  homepage contains privacy information without a dashboard.
• Health source equivalence, dependency pins, and the main-relative
  whitespace/privacy checks passed.
• Fresh independent P0-P2 review: scoped-clean, with no actionable findings.
• Exact-head hosted validation
  passed for 4242c1b6e2d4251c6be2f45a8a8976dc2e0e8b4d: Node.js 24
  clean install, full check, and Wrangler dry-run. CodeQL checks also passed.
  The PR deployment job was intentionally skipped.

Historical Live Proof

On 2026-09-09, one bounded CLI invocation returned available with
reason ok and validated 24 hourly rows for
[2026-09-08T00:00:00Z, 2026-09-09T00:00:00Z).
It exited successfully and its child was joined, without credential refresh
or retry.

The query, transport, credential handling, and CLI are unchanged. This is
historical response-contract evidence, not a claim of current authentication
or current production health. No raw metrics are published.

Release Note

Adds a manual, bounded Worker-health CLI for aggregate infrastructure metrics
without changing production telemetry collection.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: blocked before merge. Reviewed September 11, 2026, 3:14 AM ET / 07:14 UTC (Revision 3).

ClawSweeper review

What this changes

Adds a manual CLI that retrieves and validates 24 hourly Cloudflare Worker request and error estimates, with bounded networking, structured output, tests, and an operator runbook.

Merge readiness

⛔ Blocked before merge - 2 items remain

Keep open: this is useful, distinct operator tooling that current main does not implement. No actionable patch defect was found, and the maintainer-authored contribution is not eligible for automatic cleanup.

Priority: P2
Reviewed head: 4b6ca623d3811de4973668c578398936cee010f6

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused implementation with substantial boundary tests and reported live verification; draft and conflict status do not lower patch quality.
Proof confidence	🌊 off-meta tidepool	Not applicable: The MEMBER-authored PR is exempt from the external-contributor proof gate; its captured body nevertheless reports a real CLI query returning 24 validated hours, while local transport tests supplement cancellation and failure coverage.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: The MEMBER-authored PR is exempt from the external-contributor proof gate; its captured body nevertheless reports a real CLI query returning 24 validated hours, while local transport tests supplement cancellation and failure coverage.
Evidence reviewed	7 items	Complete introduced patch inspected: The pinned base-to-head delta adds seven files or file changes, totaling 942 added lines. The complete production implementation, runbook, CLI, and 532-line test file were read locally; no tests or target code were executed. Current main and related work remain distinct: Current main exposes telemetry:history for offline archived Analytics Engine queries, but has no Worker-health command or workersInvocationsAdaptive query. The merged #17 and open #18 concern archive export and aggregate capture, respectively. The GitHub releases endpoint returned no releases. Prior integration blocker remains current: A fresh GitHub read confirms the same reviewed head remains open, draft, and mergeable=false with mergeable_state=dirty. The previous review recorded no findings, and its reviewed SHA equals the current head. The captured body explicitly reserves merge approval for human review.
Findings	None	None.
Security	None	None.

How this fits together

The telemetry Worker serves update checks and public usage aggregates. This separate operator CLI reads Cloudflare infrastructure metrics and produces hourly JSON estimates without changing the Worker or its stored telemetry.

flowchart TD
  A[Operator invocation and existing credentials] --> B[Validate inputs and freeze UTC window]
  B --> C[One bounded Cloudflare query]
  C --> D[Validate response and 24 hourly groups]
  D --> E[Projected hourly JSON]
  D --> F[Bounded unavailable reason]

Loading

Before merge

• Resolve merge risk (P1) - GitHub still reports merge conflicts; the resolved integration with current main has not been inspected.
• Complete next step (P2) - Resolve the current merge conflicts, validate the integrated branch, and obtain the requested human approval before marking the draft ready to merge.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Production and test growth	Production +279 lines; tests +532 lines	The new transport and validation implementation has an explicit bounded-reader purpose and substantial boundary coverage.

Merge-risk options

Maintainer options:

1. Decide the mitigation before merge
   Retain a standalone, bounded operator reader that preserves adaptive estimates and clearly separates Worker execution metrics from telemetry delivery claims.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Technical review

Best possible solution:

Retain a standalone, bounded operator reader that preserves adaptive estimates and clearly separates Worker execution metrics from telemetry delivery claims.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this adds an operator capability rather than repairing a reported existing-behavior failure.

Is this the best way to solve the issue?

Yes: a separate manual CLI fits the infrastructure-metrics boundary, and the fixed query, bounded transport, and strict projection avoid expanding public telemetry behavior.

AGENTS.md: not found in the target repository.

Codex review notes: model internal, reasoning medium; reviewed against 5eff9fe714d9.

Labels

Label justifications:

• P2: This is a bounded operator improvement with no demonstrated urgent runtime regression.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The MEMBER-authored PR is exempt from the external-contributor proof gate; its captured body nevertheless reports a real CLI query returning 24 validated hours, while local transport tests supplement cancellation and failure coverage.

Evidence

What I checked:

• Complete introduced patch inspected: The pinned base-to-head delta adds seven files or file changes, totaling 942 added lines. The complete production implementation, runbook, CLI, and 532-line test file were read locally; no tests or target code were executed. (scripts/lib/worker-health.mjs:1, 4b6ca623d381)
• Current main and related work remain distinct: Current main exposes telemetry:history for offline archived Analytics Engine queries, but has no Worker-health command or workersInvocationsAdaptive query. The merged feat(telemetry): export archived hourly report history #17 and open feat(telemetry): add aggregate capture pilot #18 concern archive export and aggregate capture, respectively. The GitHub releases endpoint returned no releases. (package.json:15, 5eff9fe714d9)
• Prior integration blocker remains current: A fresh GitHub read confirms the same reviewed head remains open, draft, and mergeable=false with mergeable_state=dirty. The previous review recorded no findings, and its reviewed SHA equals the current head. The captured body explicitly reserves merge approval for human review. (4b6ca623d381)
• Captured live verification and supplemental tests: The complete supplied body at sourceRevision 54fa3183afa1589353eb262a5a90d255e22a55db895bf522772ac6c2b1fb2c3f reports a September 9 live CLI invocation returning available with 24 validated hourly rows, successful exit, and joined child without refresh or retry. It separately reports 15 focused tests after the late-header correction. This supports the query/projection path; raw runtime output was not supplied. (test/worker-health.test.mjs:1, 4b6ca623d381)
• Explicit dependency contract: The runbook identifies Cloudflare's pinned exporter schema as the query contract, establishing a concrete dependency signal. Production uses a fixed HTTPS destination, normal TLS verification, inherited credentials, no redirects or retries, bounded response reading, and projected diagnostics. (docs/worker-health.md:109, 4b6ca623d381)
• Pinned schema verified: The public commit resolves to the full SHA recorded here. Its schema defines the adaptive invocation query, nullable avg, hourly dimensions, time filters, and unsigned request/error sums used by the CLI. (src/cloudflare/gql/schema.gql:117944, c98fd6772a4f)

Likely related people:

• unknown: The claimed source-line change could not be verified from bounded local history. (role: source history unknown; confidence: low)
• steipete: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (2 earlier review cycles)

• reviewed 2026-09-09T01:18:28.010Z sha 4b6ca62 :: blocked before merge. :: none
• reviewed 2026-09-11T03:50:49.389Z sha 4b6ca62 :: blocked before merge. :: none