Skip to content

fix: bound stalled real-SDK capture and runtime checks - #68

Merged
vincentkoc merged 3 commits into
openclaw:mainfrom
SebTardif:fix/register-timeout
Sep 9, 2026
Merged

vincentkoc merged 3 commits into
openclaw:mainfrom
SebTardif:fix/register-timeout

Conversation

@SebTardif

@SebTardif SebTardif commented Sep 2, 2026 •

Copy link
Copy Markdown
Contributor

What Problem This Solves

Fixes an issue where real-SDK capture or runtime checks could hang on plugin imports, busy registration, or retained timers. A rejected registration wait alone cannot stop plugin code running inside the inspector process.

Why This Change Was Made

CLI real-SDK capture now uses the existing owned-child process policy from #59. This covers capture, capture-cli, and runtime checks enabled by flags or plugin config. The child loads installed SDK dependencies with normal Node resolution, flushes complete JSON, and sheds retained plugin handles.

Programmatic real-SDK capture stays in-process to preserve caller runtime objects and retained handler identity. Its budget follows finite API option, environment, then 30-second default precedence. Timeout or caller cancellation stops later inspector-owned phases, aborts supported setup reads, and observes late rejection. Arbitrary in-process JavaScript, imports, and plugin side effects cannot be forcibly canceled.

The integration preserves #73 loader cleanup, CommonJS source scanning, and mock-only SDK error classification. Mock capture retains its existing symlink behavior. The contributor branch ancestry and @SebTardif credit are preserved.

User Impact

Real-SDK CLI imports and registration now fail within the configured process budget, including busy loops and active-handle hangs. Healthy plugins still return complete capture results. API consumers retain in-process identity semantics with an explicit bounded-wait contract. No package dependencies, public helper exports, report fields, or finding codes are added.

Evidence

Development proof used sanitized direct AWS with Node 22.19.0, isolated HOME/environment, no hydration, and a verified absent instance-role credential endpoint. Exact-head GitHub CI is recorded below.

  • Before repair: six selected public API and actual CLI regressions failed against original contributor head c5471d932e558f07a9c20b97c4e1fabca2a26a52: four CLI routes required the outer watchdog, and import/cancellation API checks missed the expected rejection.
  • Initial repaired candidate: 149/149 focused tests, 338/338 full tests, and npm run release:contents passed before the PR73 integration.
  • Linked-SDK regression: the unconditional mock symlink flag failed healthy real capture with ERR_MODULE_NOT_FOUND for a dependency beside the SDK's real path. Restricting the flag to mock capture repaired that boundary.
  • Integrated linked-SDK/PR73 candidate: node --test test/in-process-register-timeout.test.js test/sdk-mock.test.js passed 48/48. This covers linked-SDK success through all four CLI routes, busy/import/pending timeouts, retained-handle cleanup, complete JSON, unsuccessful partial output, API budgets/cancellation/late rejection, and inherited mock/CJS behavior.
  • Fresh read-only P2 found one cancellation-classification issue. The existing API cancellation assertion reproduced registration-execution-error instead of the isolated capture's capture-error. The one-value repair passed all six API boundary cases on the retained AWS lease; no unrelated changes or extra review cycle were needed.
  • Final head: 982e0570d83fd103fba3466bfe37b5a6cf816cdc; tree: 33d5d2dda5fb0ca86d561f055dc23553d43a4403. Both original contributor and current-main ancestry are retained. The dependency ancestry merge was tree-identical to the reviewed candidate.
  • Final patch SHA256 relative to the original contributor head: f24c2778125f9cdd94d1801dbb68910e81ec30202e119ba40c67b28334102c8a.
  • Exact-head Node 22 Check: https://github.com/openclaw/plugin-inspector/actions/runs/34372597945 passed 358/358 tests (no failures or skips) and package contents validation on 982e0570d83fd103fba3466bfe37b5a6cf816cdc.

Scope is capture and runtime-check execution. Synthetic probe execution remains a separate unit. Crabpot source/package smoke and release follow-through remain with the coordinated release integration lane; no package was published and no live Gateway proof is claimed. Final maintainer source review and the sole merge slot are granted for 982e0570d83fd103fba3466bfe37b5a6cf816cdc; the P2 cancellation finding is resolved with red/green proof and no accepted findings remain.

@SebTardif
SebTardif requested a review from a team as a code owner September 2, 2026 16:48
@clawsweeper

clawsweeper Bot commented Sep 2, 2026 •

Copy link
Copy Markdown

🦞👀
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 clawsweeper Bot added P2 Normal priority bug or improvement with limited blast radius. merge-risk: 🚨 availability 🚨 Merging this PR could cause crashes, hangs, restart loops, stalls, or process outages. merge-risk: 🚨 compatibility 🚨 Merging this PR could break existing users, config, migrations, defaults, or upgrades. proof: sufficient Contributor real behavior proof is sufficient. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. labels Sep 2, 2026
@clawsweeper

clawsweeper Bot commented Sep 2, 2026 •

Copy link
Copy Markdown

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

ClawSweeper review

What this changes

Adds a configurable 30-second deadline to in-process plugin registration, timeout exits in two capture CLIs, documentation, and regression tests.

Merge readiness

⛔ Blocked before merge - 5 items remain

The fix remains necessary on main and in v0.3.24. Direct capture has convincing runtime proof, but the prior timeout-termination blocker remains in other registration callers.

Priority: P2
Reviewed head: c5471d932e558f07a9c20b97c4e1fabca2a26a52

Review scores

Measure Result What it means
Overall readiness 🦐 gold shrimp (3/6) Useful, directly demonstrated work remains incomplete at shared caller boundaries.
Proof confidence 🦞 diamond lobster (5/6) Sufficient (terminal): The supplied macOS/Node terminal trace exercises production direct capture with an active-interval plugin and shows a 200ms timeout, exit 1 in 246ms, and successful normal registration. This supports the direct-capture behavior; other caller termination and required Crabpot validation remain separate blockers.
Patch quality 🦐 gold shrimp (3/6) 1 actionable review finding remain.

Verification

Check Result Evidence
Real behavior Verified Sufficient (terminal): The supplied macOS/Node terminal trace exercises production direct capture with an active-interval plugin and shows a 200ms timeout, exit 1 in 246ms, and successful normal registration. This supports the direct-capture behavior; other caller termination and required Crabpot validation remain separate blockers.
Evidence reviewed 9 items Policy and repository identity: Read the complete root AGENTS.md and verified origin. No nested AGENTS.md or maintainer notes were found. The policy requires Crabpot follow-through for behavior and CLI changes.
Verified introduced change: The local diff matches the complete host introduction evidence: six files, with the new registration deadline and two CLI exit guards. Raw head parentage identifies the pinned main SHA as its parent.
Still necessary on current main: Current main directly awaits register(api) without a deadline. The related open child-process and probe-invocation changes address different execution boundaries.
Findings 1 actionable finding [P1] Terminate every registration CLI caller after timeout
Security None None.

How this fits together

Plugin Inspector imports plugin entrypoints to record their registrations for compatibility reports and synthetic probes. This change bounds the registration wait; callers must then report the failure and terminate CLI processes containing lingering plugin handles.

flowchart TD
  A[Plugin entrypoint] --> B[In-process registration]
  C[Configured timeout budget] --> B
  B --> D{Registration settles?}
  D -->|Yes| E[Captured registrations]
  D -->|No| F[Classified timeout]
  E --> G[Reports and synthetic probes]
  F --> H[Caller error handling and CLI exit]
Loading

Before merge

  • Terminate every registration CLI caller after timeout (P1) - The new timeout comes from shared captureEntrypoint, but this exit guard only handles errors that retain failureClass. For check --runtime --real-sdk and equivalent CI execution, captureTarget converts it into a report result and runPluginCheck throws an unclassified error. The synthetic-probe CLI also only sets exitCode. A registration retaining an interval therefore still keeps those processes alive after the deadline. Preserve timeout classification through these callers and handle termination at their CLI boundaries, with active-handle regressions. This remains the prior review blocker.
  • Resolve merge risk (P2) - The timeout releases the shared registration wait without stopping plugin execution; report processing can continue while the expired registration retains active handles.
  • Resolve merge risk (P1) - Previously successful registrations taking over 30 seconds will now fail unless operators raise the budget; slow-but-successful override behavior has not been demonstrated.
  • Resolve merge risk (P1) - Required Crabpot source-mode and package-mode smoke results remain unestablished.
  • Complete next step (P2) - Repair timeout handling across runtime-check, CI, and synthetic CLI callers; add active-handle and slow-registration override coverage, and supply required Crabpot smoke results.

Findings

  • [P1] Terminate every registration CLI caller after timeout — src/cli.js:57-59
Agent review details

Security

None.

Review metrics

Metric Value Why it matters
Production and test growth Production +47/-2 lines; tests +111/-0 lines The production growth implements timeout resolution and CLI termination; the added tests currently cover direct capture only.

Merge-risk options

Maintainer options:

  1. Complete timeout handling across callers (recommended)
    Preserve timeout classification through reports and terminate affected CLI owners after flushing diagnostics, with active-handle regressions and slow-registration override coverage.
Copy recommended automerge instruction
@clawsweeper automerge

Special instructions:
Preserve capture-timeout through runtime reporting and runPluginCheck, handle it in the synthetic-probe CLI, and prove affected CLI processes exit with an active-interval registration fixture; preserve report fields and verify a slow registration succeeds with a larger configured budget.

Technical review

Best possible solution:

Provide bounded, classified failure across all registration CLI callers, verify the larger-budget path for slow plugins, and complete Crabpot consumer validation.

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

Yes, source identifies a concrete path: registration that retains an interval and never settles reaches the new deadline, but runtime-check/CI error wrapping and synthetic CLI handling do not terminate the process. No reviewer execution was performed.

Is this the best way to solve the issue?

Not yet: the timer is a focused repair and direct capture is demonstrated, but timeout handling must cover the shared callers and the configured escape path for slow registrations.

Full review comments:

  • [P1] Terminate every registration CLI caller after timeout — src/cli.js:57-59
    The new timeout comes from shared captureEntrypoint, but this exit guard only handles errors that retain failureClass. For check --runtime --real-sdk and equivalent CI execution, captureTarget converts it into a report result and runPluginCheck throws an unclassified error. The synthetic-probe CLI also only sets exitCode. A registration retaining an interval therefore still keeps those processes alive after the deadline. Preserve timeout classification through these callers and handle termination at their CLI boundaries, with active-handle regressions. This remains the prior review blocker.
    Confidence: 0.98

Overall correctness: patch is incorrect
Overall confidence: 0.96

AGENTS.md: found and applied where relevant.

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

Labels

Label justifications:

  • P2: This repairs a bounded, opt-in plugin inspection workflow rather than an urgent core-runtime regression.
  • merge-risk: 🚨 availability: The new deadline can return control while plugin handles remain alive, without reliable termination across affected CLI callers.
  • merge-risk: 🚨 compatibility: The new default rejects registrations exceeding 30 seconds, changing previously unbounded behavior for slow plugins.
  • rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦞 diamond lobster 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 macOS/Node terminal trace exercises production direct capture with an active-interval plugin and shows a 200ms timeout, exit 1 in 246ms, and successful normal registration. This supports the direct-capture behavior; other caller termination and required Crabpot validation remain separate blockers.
  • proof: sufficient: Contributor real behavior proof is sufficient. The supplied macOS/Node terminal trace exercises production direct capture with an active-interval plugin and shows a 200ms timeout, exit 1 in 246ms, and successful normal registration. This supports the direct-capture behavior; other caller termination and required Crabpot validation remain separate blockers.

Evidence

Acceptance criteria:

  • [P2] node --test test/in-process-register-timeout.test.js test/runtime-capture-report.test.js test/api.test.js test/synthetic-probes.test.js.
  • [P1] npm run check.
  • [P1] npm run release:crabpot -- --crabpot ../crabpot.
  • [P1] In Crabpot: CRABPOT_PLUGIN_INSPECTOR_CLI=source npm run plugin-inspector:smoke.
  • [P1] In Crabpot: npm run plugin-inspector:smoke.

What I checked:

  • Policy and repository identity: Read the complete root AGENTS.md and verified origin. No nested AGENTS.md or maintainer notes were found. The policy requires Crabpot follow-through for behavior and CLI changes. (AGENTS.md:12, c5471d932e55)
  • Verified introduced change: The local diff matches the complete host introduction evidence: six files, with the new registration deadline and two CLI exit guards. Raw head parentage identifies the pinned main SHA as its parent. (src/inspector.js:213, c5471d932e55)
  • Still necessary on current main: Current main directly awaits register(api) without a deadline. The related open child-process and probe-invocation changes address different execution boundaries. (src/inspector.js:213, 84ede904fd6e)
  • Latest release also lacks the deadline: The v0.3.24 source has the same unbounded registration await; its merged release preparation PR does not implement this fix. (src/inspector.js:213, 92db8c57e1d5)
  • Timeout classification is lost before runtime-check CLI exit: Runtime capture records capture-timeout in a result, then runPluginCheck throws a new Error without failureClass. Consequently the introduced conditional process.exit does not run for check or CI runtime capture. The synthetic-probe CLI likewise only sets exitCode. (src/api.js:237, c5471d932e55)
  • Positive direct-capture proof: The complete supplied body, captured under sourceRevision dd517c776326b80a52421e47a6b4134ed71103d06859c00985293a25d4beb821, records macOS/Node v24.15.0 CLI execution with a never-settling registration and active interval: the patched CLI printed the 200ms timeout and exited 1 in 246ms; a settling plugin captured successfully. These observations exercise the production capture entrypoint and exit guard. They do not demonstrate runtime-check, CI, synthetic CLI termination, or Crabpot smoke.

Likely related people:

  • vincentkoc: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rank-up moves

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

  • Preserve timeout termination through runtime-check, CI, and synthetic CLI paths, with active-handle regressions.
  • Demonstrate that a slow registration succeeds when its configured budget is increased.
  • Attach redacted Crabpot source-mode and package-mode smoke results and document any required consumer 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 (3 earlier review cycles)
  • reviewed 2026-09-02T16:51:22.078Z sha 82d05fc :: needs maintainer review before merge. :: none
  • reviewed 2026-09-03T09:04:01.373Z sha 82d05fc :: blocked before merge. :: [P1] Terminate all real-SDK runtime workflows after registration timeout
  • reviewed 2026-09-04T03:52:06.311Z sha 82d05fc :: blocked before merge. :: [P1] Terminate every real-SDK registration caller after timeout

@clawsweeper clawsweeper Bot added rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. and removed rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. merge-risk: 🚨 compatibility 🚨 Merging this PR could break existing users, config, migrations, defaults, or upgrades. labels Sep 3, 2026
Bound real-SDK captureEntrypoint register() with the same 30s
PLUGIN_INSPECTOR_CAPTURE_TIMEOUT_MS budget as the mock-SDK child path.
A plugin whose register() never settles now fails with capture-timeout
instead of hanging the inspector process.

Signed-off-by: Sebastien Tardif <sebtardif@ncf.ca>
@SebTardif
SebTardif force-pushed the fix/register-timeout branch from 82d05fc to c5471d9 Compare September 8, 2026 16:32
@clawsweeper clawsweeper Bot added the merge-risk: 🚨 compatibility 🚨 Merging this PR could break existing users, config, migrations, defaults, or upgrades. label Sep 8, 2026
Reuse the owned capture child for CLI execution while preserving in-process API runtime and retained handler identity. Bound API phases with cooperative cancellation and document the JavaScript preemption limit.

Integrate the landed child-process policy and preserve reviewed CommonJS loader behavior. Keep real SDK linked dependency resolution unchanged.
Record the landed PR73 ancestry without changing the reviewed and tested candidate tree.
@vincentkoc vincentkoc changed the title fix: time out hung in-process plugin register() fix: bound stalled real-SDK capture and runtime checks Sep 9, 2026
@vincentkoc
vincentkoc merged commit 7cbdafa into openclaw:main Sep 9, 2026
8 checks passed
@SebTardif
SebTardif deleted the fix/register-timeout branch October 16, 2026 23:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge-risk: 🚨 availability 🚨 Merging this PR could cause crashes, hangs, restart loops, stalls, or process outages. merge-risk: 🚨 compatibility 🚨 Merging this PR could break existing users, config, migrations, defaults, or upgrades. P2 Normal priority bug or improvement with limited blast radius. proof: sufficient Contributor real behavior proof is sufficient. rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants