fix: abort hung OpenClaw target version fetches

[SebTardif]

What Problem This Solves

Fixes an issue where users selecting an npm OpenClaw target could wait indefinitely for stalled registry or archive responses, or buffer an unbounded download. A metadata limit alone also breaks healthy latest and beta resolution when the full package history exceeds that limit.

Why This Change Was Made

Each metadata or archive request uses a 30-second default deadline covering its headers and body reads, not a single deadline for the entire resolution and preparation operation. Invalid, nonpositive, fractional, nonfinite, or overflowing timeout values fall back to that default. Operators can override the budgets with PLUGIN_INSPECTOR_TARGET_FETCH_TIMEOUT_MS, PLUGIN_INSPECTOR_TARGET_METADATA_MAX_BYTES, and PLUGIN_INSPECTOR_TARGET_ARCHIVE_MAX_BYTES.

Tag resolution reads the official flat /-/package/openclaw/dist-tags response, then fetches metadata for the resolved exact version. The metadata and archive limits remain 16 MiB and 256 MiB respectively; the full packument is not downloaded.

Declared and streamed oversized bodies are rejected, HTTP-error bodies are cancelled, and acquired readers are released on success and failure. Integrity verification, failed-extraction cleanup, cache behavior, and the requirement to prepare the original resolved target object are preserved.

This follow-up builds directly on SebTardif's original commit 4f1a06ca249c6d49d71d7f259571a11bb1eb879c; contributor ancestry and authorship are retained. Capture, registration, and synthetic-probe timeout paths are outside this PR.

User Impact

Healthy tag-based target selection stays within the metadata budget. Stalled or oversized downloads fail with target-download-timeout or target-download-too-large, without retaining response readers or preparing a failed target.

Evidence

• Red checkpoint 11b0e89f8d0a33888009b01bc90f2d0700f35f87: https://github.com/openclaw/plugin-inspector/actions/runs/34367312677. Node 22 CI recorded 12 expected failures covering the packument limit, response cleanup, and timeout overflow; 259 tests passed.
• Green candidate 55bff71c0b5fee15b2e1405253ed7f04f0391433: https://github.com/openclaw/plugin-inspector/actions/runs/34367826440. Node 22 npm run check passed all 272 tests with no skips or cancellations, followed by package contents: pass.
• Fresh independent review of the complete staged candidate against base 84ede904fd6e766a9fc4de002f39af87d90c1916 was P2-clean, with no accepted or actionable P0-P2 findings.
• Real HTTP fixtures cover stalled headers and bodies, declared and chunked oversized responses, HTTP-error cancellation, peer disconnects, successful tag resolution and verified archive preparation, cache reuse, integrity mismatch, failed-extraction cleanup, and the public CLI timeout.
• Credential-free live contract read on September 9, 2026, separate from the offline default suite: /-/package/openclaw/dist-tags returned HTTP 200, 69 bytes, and a flat object with latest: "2026.9.3" and beta: "2026.9.1". /openclaw/2026.9.3 returned HTTP 200, 108,241 bytes, the matching version, a string tarball URL, and SHA-512 integrity metadata. No full packument or live archive was downloaded.
• Contributor code was executed only in the reviewed secretless fork CI workflow, not locally. The earlier action_required run was superseded by approved runs for the updated PR head.

Source-owner review has accepted candidate 55bff71c0b5fee15b2e1405253ed7f04f0391433 and its per-request bounded defaults for merge. No release is included. Downstream Crabpot smoke remains deferred to its separately authorized stage. A real registry outage and a slow-WAN full archive transfer were not tested.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

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

ClawSweeper review in progress

ClawSweeper is reviewing this revision. This supersedes any previous blocked status.

View the workflow run.

[clawsweeper]

Codex review: blocked before merge. Reviewed September 8, 2026, 12:37 PM ET / 16:37 UTC.

ClawSweeper review

What this changes

Adds configurable deadlines and size limits to OpenClaw npm downloads, classified errors, regression tests, and a changelog entry.

Regression provenance

Possible regression — suspected (reviewed change). No predecessor PR is attributed.

Merge readiness

⛔ Blocked before merge - 5 items remain

This fix remains necessary, but the new metadata limit rejects the healthy npm registry response used by latest and beta resolution. The supplied timeout proof is useful; the patch needs correction before merge.

Priority: P2
Reviewed head: 4f1a06ca249c6d49d71d7f259571a11bb1eb879c
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	Useful production-path proof supports the repair, but the metadata cap currently breaks normal tag resolution.
Proof confidence	🐚 platinum hermit (4/6)	Sufficient (terminal): The supplied Windows terminal trace exercises the real resolver and public CLI against a hung HTTP server, showing bounded failure and CLI exit; it also records early oversized-archive rejection. This proves the cancellation path, while default-budget compatibility remains a separate merge concern.
Patch quality	🦐 gold shrimp (3/6)	1 actionable review finding remain.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (terminal): The supplied Windows terminal trace exercises the real resolver and public CLI against a hung HTTP server, showing bounded failure and CLI exit; it also records early oversized-archive rejection. This proves the cancellation path, while default-budget compatibility remains a separate merge concern.
Evidence reviewed	9 items	Introduced rejection of normal registry metadata: The PR sets a 16,777,216-byte metadata limit. Both supported tags still request the complete /openclaw metadata document, and fetchJson now enforces this limit before parsing. This happens before prepared-package cache lookup. Healthy npm response exceeds the introduced cap: A read-only GET of https://registry.npmjs.org/openclaw on September 8 returned valid JSON containing 17,073,832 bytes, exceeding the cap by 296,616 bytes. SHA-256: d963aec209cca332e9f4c91f314192a2846d5ed15170b7f2c84bf5309eee7288. Its latest tag was 2026.9.3 and beta was 2026.9.1. No target code was executed. Bounded tag lookup alternative: The registry's /openclaw/latest endpoint returned 108,241 bytes with version 2026.9.3, tarball metadata, and integrity metadata. A separate /openclaw/beta read returned 105,475 bytes with the corresponding fields, supporting a narrower lookup instead of downloading every published version's metadata.
Findings	1 actionable finding	[P1] Resolve tags without rejecting the healthy registry response
Security	None	None.

How this fits together

Plugin Inspector downloads an explicitly selected OpenClaw release to compare its public plugin contracts with a plugin. Registry metadata selects the version, then an integrity-checked archive supplies a cached compatibility target.

flowchart TD
  A[Requested OpenClaw version] --> B[Resolve npm metadata]
  B --> C[Apply download limits]
  C --> D{Prepared target cached?}
  D -->|Yes| F[Read public plugin contracts]
  D -->|No| E[Download and verify archive]
  E --> F
  F --> G[Plugin compatibility report]

Loading

Decision needed

Question	Recommendation
After repairing tag resolution, should the new 30-second and archive-size limits apply to existing users by default?	Retain bounded defaults with compatibility evidence: Approve finite defaults after documenting overrides and demonstrating successful cold-cache, cache-reuse, and slow-transfer behavior.

Why: The timeout demonstration proves cancellation but does not establish that the chosen defaults preserve healthy slow downloads; selecting that upgrade tradeoff requires owner intent.

Before merge

• Resolve tags without rejecting the healthy registry response (P1) - The new 16 MiB cap is already smaller than the official /openclaw JSON response: a read-only GET returned 17,073,832 bytes, versus the 16,777,216-byte limit. Both latest and beta fetch that document, so normal version-targeted commands now throw target-download-too-large, including before cache reuse. Use a bounded tag-specific lookup or another approach that accepts valid registry metadata without removing download protection. The registry's /openclaw/latest and /openclaw/beta responses contain the needed version and integrity fields in approximately 108 KB and 105 KB.
• Resolve merge risk (P1) - After the metadata defect is repaired, the unconditional 30-second deadline and 256 MiB archive cap can still terminate previously successful downloads after upgrade; compatibility evidence and documentation for the overrides remain outstanding.
• Resolve merge risk (P1) - The supplied evidence does not establish the repository-required Crabpot source-mode and package-mode smoke results or necessary downstream follow-through.
• Complete next step (P2) - Repair latest/beta metadata resolution, settle and document the default budget policy with compatibility evidence, and provide the required Crabpot smoke results.
• Resolve maintainer decision - Resolve the maintainer decision shown above before merge.

Findings

• [P1] Resolve tags without rejecting the healthy registry response — src/openclaw-version.js:13

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Registry metadata versus cap	17,073,832 bytes observed; 16,777,216 bytes allowed	The normal registry response already exceeds the new default limit.
Production and test LOC delta	Production +96 net; tests +105 net	Production growth implements the stated cancellation, bounded streaming, and error-classification behavior.

Merge-risk options

Maintainer options:

1. Repair tag resolution before approving defaults (recommended)
   Avoid the full package metadata document, retain bounded reads, and establish the upgrade behavior before landing.
2. Pause pending budget policy
   Keep the branch open until the area owner selects the default compatibility policy and downstream smoke evidence is available.

Technical review

Best possible solution:

Use bounded tag-specific metadata lookup, preserve integrity and cache semantics, and ship documented, compatibility-tested download budgets approved by the area owner.

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

Yes: the measured healthy registry response exceeds the introduced cap, and source tracing proves latest/beta resolution rejects it before cache lookup. The patched CLI was not executed during this read-only review.

Is this the best way to solve the issue?

No, as written: the full metadata request is incompatible with its new cap; tag-specific registry endpoints provide the needed version metadata in substantially smaller responses.

Full review comments:

• [P1] Resolve tags without rejecting the healthy registry response — src/openclaw-version.js:13
  The new 16 MiB cap is already smaller than the official /openclaw JSON response: a read-only GET returned 17,073,832 bytes, versus the 16,777,216-byte limit. Both latest and beta fetch that document, so normal version-targeted commands now throw target-download-too-large, including before cache reuse. Use a bounded tag-specific lookup or another approach that accepts valid registry metadata without removing download protection. The registry's /openclaw/latest and /openclaw/beta responses contain the needed version and integrity fields in approximately 108 KB and 105 KB.
  Confidence: 0.99

Overall correctness: patch is incorrect
Overall confidence: 0.99

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 84ede904fd6e.

Labels

Label justifications:

• P2: This is a bounded reliability improvement to optional npm version targeting; the newly identified regression is on the proposed branch.
• merge-risk: 🚨 compatibility: Merging the new metadata cap would break latest and beta lookups against the current healthy registry response.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🐚 platinum hermit and patch quality is 🦐 gold shrimp.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Sufficient (terminal): The supplied Windows terminal trace exercises the real resolver and public CLI against a hung HTTP server, showing bounded failure and CLI exit; it also records early oversized-archive rejection. This proves the cancellation path, while default-budget compatibility remains a separate merge concern.
• proof: sufficient: Contributor real behavior proof is sufficient. The supplied Windows terminal trace exercises the real resolver and public CLI against a hung HTTP server, showing bounded failure and CLI exit; it also records early oversized-archive rejection. This proves the cancellation path, while default-budget compatibility remains a separate merge concern.

Evidence

What I checked:

• Introduced rejection of normal registry metadata: The PR sets a 16,777,216-byte metadata limit. Both supported tags still request the complete /openclaw metadata document, and fetchJson now enforces this limit before parsing. This happens before prepared-package cache lookup. (src/openclaw-version.js:13, 4f1a06ca249c)
• Healthy npm response exceeds the introduced cap: A read-only GET of https://registry.npmjs.org/openclaw on September 8 returned valid JSON containing 17,073,832 bytes, exceeding the cap by 296,616 bytes. SHA-256: d963aec209cca332e9f4c91f314192a2846d5ed15170b7f2c84bf5309eee7288. Its latest tag was 2026.9.3 and beta was 2026.9.1. No target code was executed.
• Bounded tag lookup alternative: The registry's /openclaw/latest endpoint returned 108,241 bytes with version 2026.9.3, tarball metadata, and integrity metadata. A separate /openclaw/beta read returned 105,475 bytes with the corresponding fields, supporting a narrower lookup instead of downloading every published version's metadata.
• Current main still needs download bounds: Current main directly awaits fetch and buffers the archive with arrayBuffer without the PR's deadline or size bounds. Inspector and batch callers resolve metadata before consulting the prepared-package cache. (src/openclaw-version.js:139, 84ede904fd6e)
• Latest release also lacks the proposed bounds: The v0.3.24 source retains the unbounded metadata and archive fetches. The supplied related PRs concern capture children, synthetic probes, and in-process registration, rather than this download path. (src/openclaw-version.js:194, 92db8c57e1d5)
• Real production-path timeout evidence: The complete supplied PR body, captured under sourceRevision 413a3b8dd8dd0c441ab06de99eec91dd790b6ba5c0b8cf24eb872a8bd8b9c5a7, records Windows Node v24.19.0 using a real local HTTP server and the patched resolver and CLI. Resolution timed out in 98ms, the CLI exited 1, and an oversized advertised archive was rejected before arrayBuffer. The small injected budget demonstrates cancellation, not compatibility of the production defaults. (src/openclaw-version.js:210, 4f1a06ca249c)

Likely related people:

• unknown: The claimed source-line change could not be verified from bounded local history. (role: source history unknown; confidence: low)
• unknown: The claimed source-line change could not be verified from bounded local history. (role: source history unknown; confidence: low)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Repair tag lookup and cover normal latest/beta resolution without downloading the full package metadata history.
• Document all three overrides and establish successful cold-cache, cache-reuse, and slow-transfer behavior for the approved defaults.
• Record Crabpot source-mode and package-mode smoke results and any required downstream follow-through.

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 (1 earlier review cycle)

• reviewed 2026-09-05T05:31:00.276Z sha 000214a :: blocked before merge. :: none