perf(cli): cache stable subcommand help by frankekn · Pull Request #84786 · openclaw/openclaw

frankekn · 2026-05-21T03:38:00Z

Summary

Problem: doctor --help, models --help, plugins --help, and gateway --help still built the full CLI path and used about 320MB RSS just to print parent help.
Solution: extend generated startup help metadata for stable parent help pages and route only those parent -h/--help invocations through a precomputed fast path.
What changed: startup metadata now stores help text/signatures for doctor, gateway, models, and plugins; run-main can emit those pages before full CLI registration; tests cover metadata determinism, routing, disable env, and version passthrough.
What did NOT change (scope boundary): nested command help and plugin/config-sensitive help stay on the live path; --version continues to use the live command path.

Motivation

Keeps common subcommand help from paying the full CLI import/registration cost while preserving live help for surfaces that may be dynamic.

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

Closes #
Related #
This PR fixes a bug or regression

Real behavior proof (required for external PRs)

Behavior or issue addressed: selected parent subcommand help no longer imports the full CLI just to print help.
Real environment tested: local macOS worktree, Node v24.14.0, built openclaw.mjs.
Exact steps or command run after this patch: pnpm test:startup:bench -- --case doctorHelp --case modelsHelp --case pluginsHelp --case gatewayHelp --runs 3 --warmup 1 --json --output .artifacts/perf-subcommand-help-after-rebase.json.
Evidence after fix: benchmark results below.
Observed result after fix: selected help cases are about 82-88ms and 94.6-94.8MB RSS.
What was not tested: dynamic nested subcommand/plugin-sensitive help is intentionally not precomputed.
Before evidence: local pre-change measurement reproduced about 344-369ms and 321-322MB RSS for the same cases.

Root Cause (if applicable)

Root cause: generated help metadata and the early startup help path covered only root/browser help, so other stable parent help pages imported run-main and built enough CLI state to cost hundreds of MB RSS.
Missing detection / guardrail: no metadata coverage or startup budget cases for these parent subcommand help paths.
Contributing context (if known): some CLI help is dynamic, so this PR intentionally allowlists only stable parent help pages.

Regression Test Plan (if applicable)

Coverage level that should have caught this:
- Unit test
- Seam / integration test
- End-to-end test
- Existing coverage already sufficient
Target test or file: src/cli/run-main.test.ts, src/cli/run-main.exit.test.ts, test/scripts/write-cli-startup-metadata.test.ts.
Scenario the test should lock in: selected parent help routes to precomputed metadata, disable env falls back, nested help is not precomputed, and version output does not get misrouted.
Why this is the smallest reliable guardrail: it locks the routing seam and generated metadata without expanding full CLI registration tests.
Existing test that already covers this (if any): root/browser fast path tests covered adjacent behavior only.
If no new test is added, why not: N/A.

User-visible / Behavior Changes

openclaw doctor --help, openclaw gateway --help, openclaw models --help, and openclaw plugins --help print materially faster with lower RSS.

Diagram (if applicable)

Before:
[parent help] -> run-main full CLI registration -> commander help

After:
[allowlisted parent help] -> startup metadata -> precomputed help text
[nested/dynamic help] -> run-main full CLI registration -> commander help

Security Impact (required)

New permissions/capabilities? (Yes/No) No
Secrets/tokens handling changed? (Yes/No) No
New/changed network calls? (Yes/No) No
Command/tool execution surface changed? (Yes/No) No
Data access scope changed? (Yes/No) No
If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

OS: macOS local worktree
Runtime/container: Node v24.14.0
Model/provider: N/A
Integration/channel (if any): CLI startup path
Relevant config (redacted): N/A

Steps

Run selected parent help before/after or with OPENCLAW_DISABLE_CLI_STARTUP_HELP_FAST_PATH=1 to compare live output.
Run the startup benchmark for doctorHelp, modelsHelp, pluginsHelp, and gatewayHelp.
Run changed-scope tests/gates.

Expected

Selected parent help output matches live help and stays under startup budget.

Actual

Fast/live help output matched for selected commands.
Fast/live version output matched for selected commands.
Startup budget check passed.

Evidence

Failing test/log before + passing after
Trace/log snippets
Screenshot/recording
Perf numbers (if relevant)

After rebase benchmark (runs=3, warmup=1):

doctor --help: avg 84.1ms, p95 85.0ms, RSS avg 94.6MB
models --help: avg 87.9ms, p95 92.0ms, RSS avg 94.8MB
plugins --help: avg 82.3ms, p95 84.3ms, RSS avg 94.8MB
gateway --help: avg 82.7ms, p95 82.8ms, RSS avg 94.7MB

Verification run:

pnpm test src/cli/run-main.test.ts src/cli/run-main.exit.test.ts src/entry.test.ts src/cli/startup-metadata.test.ts test/scripts/write-cli-startup-metadata.test.ts -- --reporter=default
pnpm build
Fast/live help and version equivalence loop for doctor, gateway, models, plugins
pnpm test:startup:bench -- --case doctorHelp --case modelsHelp --case pluginsHelp --case gatewayHelp --runs 3 --warmup 1 --json --output .artifacts/perf-subcommand-help-after-rebase.json
pnpm test:startup:bench:check --report .artifacts/perf-subcommand-help-after-rebase.json --skip-baseline
pnpm check:changed

Human Verification (required)

Verified scenarios: selected parent help fast path, disable-env live fallback, version passthrough, metadata generation determinism, changed-scope gate.
Edge cases checked: nested gateway status --help remains live; doctor --version and gateway -V do not use precomputed help.
What you did not verify: every dynamic/plugin-sensitive nested help page, because those are intentionally outside this PR.

Review Conversations

I replied to or resolved every bot review conversation I addressed in this PR.
I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

Backward compatible? (Yes/No) Yes
Config/env changes? (Yes/No) No
Migration needed? (Yes/No) No
If yes, exact upgrade steps: N/A

Risks and Mitigations

Risk: generated precomputed help can become stale when command definitions change.
- Mitigation: metadata signatures include command source files, startup metadata tests cover deterministic output, and only stable parent help pages are allowlisted.
Risk: version/help routing could overlap.
- Mitigation: new precomputed subcommand path requires explicit -h/--help; version equivalence was verified.

clawsweeper · 2026-05-21T03:39:27Z

Codex review: needs maintainer review before merge.

Workflow note: Future ClawSweeper reviews update this same comment in place.

How this review workflow works

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.

Summary
This PR adds generated startup metadata and an early CLI fast path for doctor, gateway, models, and plugins parent --help output, plus tests, startup benchmark coverage, and a changelog entry.

Reproducibility: yes. at source level: current main only precomputes adjacent root/parent help paths while these four parent commands still fall through to the live CLI registration path. I did not independently run the RSS benchmark in this read-only review.

PR rating
Overall: 🦞 diamond lobster
Proof: 🌊 off-meta tidepool
Patch quality: 🦞 diamond lobster
Summary: Focused scope, addressed review feedback, targeted regression coverage, and reported benchmark evidence make this above-average and ready for maintainer handling.

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

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.

Real behavior proof
Not applicable: The external-contributor proof gate does not apply to this MEMBER, maintainer-labeled PR; the body includes local benchmark numbers and verification commands.

Risk before merge

I did not run the build, tests, or RSS benchmark in this read-only review, so merge should rely on CI or maintainer verification for fast/live help equivalence and startup budget.
Precomputed help can drift if future help-affecting source files are missed by the metadata signature list; the current diff narrows this by hashing the obvious selected-command sources and keeping the allowlist small.

Maintainer options:

Land after startup-help gates (recommended)
Merge once maintainer review and required checks confirm regenerated metadata, fast/live help equivalence, and startup benchmark budgets for the four parent commands.
Pause if help staleness is unacceptable
Hold or close the PR if maintainers do not want additional precomputed parent help surfaces without a broader metadata invalidation policy.

Next step before merge
No automated repair is needed; the protected maintainer-labeled PR should proceed through normal maintainer review and required gate verification.

Security
Cleared: No concrete security or supply-chain concern was found in the CLI metadata, routing, test, and changelog diff.

Review details

Best possible solution:

Land the allowlisted metadata-backed help path after maintainer review and required gates confirm generated metadata, fast/live help equivalence, and startup budget for the four parent commands.

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

Yes, at source level: current main only precomputes adjacent root/parent help paths while these four parent commands still fall through to the live CLI registration path. I did not independently run the RSS benchmark in this read-only review.

Is this the best way to solve the issue?

Yes, the allowlist plus live fallback is the narrow maintainable shape: stable parent help is cached while nested, plugin-sensitive, invalid-argv, disable-env, and version paths stay live.

Label changes:

add merge-risk: 🚨 compatibility: The PR changes the help-rendering path for existing CLI invocations, so stale metadata or routing mistakes could change user-visible help behavior despite green unit tests.

Label justifications:

P2: This is a focused user-facing CLI performance improvement with limited blast radius and targeted routing/metadata coverage.
merge-risk: 🚨 compatibility: The PR changes the help-rendering path for existing CLI invocations, so stale metadata or routing mistakes could change user-visible help behavior despite green unit tests.
rating: 🦞 diamond lobster: Current PR rating is 🦞 diamond lobster because proof is 🌊 off-meta tidepool, patch quality is 🦞 diamond lobster, and Focused scope, addressed review feedback, targeted regression coverage, and reported benchmark evidence make this above-average and ready for maintainer handling.
status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The external-contributor proof gate does not apply to this MEMBER, maintainer-labeled PR; the body includes local benchmark numbers and verification commands.

Acceptance criteria:

pnpm test src/cli/run-main.test.ts src/cli/run-main.exit.test.ts src/entry.test.ts src/cli/startup-metadata.test.ts test/scripts/write-cli-startup-metadata.test.ts -- --reporter=default
pnpm build
pnpm test:startup:bench -- --case doctorHelp --case modelsHelp --case pluginsHelp --case gatewayHelp --runs 3 --warmup 1 --json --output .artifacts/perf-subcommand-help-after-rebase.json
pnpm test:startup:bench:check --report .artifacts/perf-subcommand-help-after-rebase.json --skip-baseline
pnpm check:changed

What I checked:

Working tree status: Read-only review started from a clean checkout on the target repository.
Protected PR metadata: Provided GitHub context marks the author association as MEMBER and the labels include maintainer, so this workflow must keep the item open for explicit maintainer handling.
Current main baseline: Current main has root/browser/setup/secrets/nodes startup help fast paths, but no precomputed fast path for the four selected parent subcommands. (src/cli/run-main.ts:531, 8a8f9dc8cb77)
Fast-path routing: The PR routes only resolved allowlisted parent subcommand help through precomputed metadata and falls back to the live path when metadata is unavailable. (src/cli/run-main.ts:572, 3e63c84ffd6c)
Strict argv guard: The branch rejects terminators, unknown flags, nested args, and version flags before allowing the precomputed subcommand help route, addressing earlier review concerns about invalid argv and version precedence. (src/cli/run-main-policy.ts:38, 3e63c84ffd6c)
Metadata staleness guard: The branch hashes the shared help formatting/context/banner files plus the selected subcommand source files, including gateway service command registration, before generating subcommand help metadata. (scripts/write-cli-startup-metadata.ts:149, 3e63c84ffd6c)

Likely related people:

frankekn: The same contributor owns the current PR and recent merged/current-main CLI startup-help fast-path work for setup/onboard/configure plus secrets/nodes. (role: recent area contributor; confidence: high; commits: 2c0c9c92f485, 233765b36105, 3e63c84ffd6c; files: src/cli/run-main.ts, src/cli/run-main-policy.ts, scripts/write-cli-startup-metadata.ts)
Dallin Romney: Git blame shows the base CLI startup metadata files and initial root/browser help fast-path structure came from their nearby performance commit, so they are an adjacent history owner for architecture fit. (role: introduced adjacent behavior; confidence: medium; commits: b79effefee92; files: src/cli/run-main.ts, src/cli/run-main-policy.ts, scripts/write-cli-startup-metadata.ts)

Codex review notes: model gpt-5.5, reasoning high; reviewed against 8a8f9dc8cb77.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a7c72af714

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-05-21T03:46:28Z

+    path.join(rootDir, "src/cli/gateway-cli.ts"),
+    path.join(rootDir, "src/cli/gateway-cli/register.ts"),
+    path.join(rootDir, "src/cli/gateway-cli/run-command.ts"),


Hash all gateway help sources in startup metadata signature

resolveSubcommandHelpSourceSignature only hashes src/cli/gateway-cli.ts, src/cli/gateway-cli/register.ts, and src/cli/gateway-cli/run-command.ts, but gateway --help output also depends on service subcommands added by addGatewayServiceCommands in src/cli/daemon-cli/register-service-commands.ts (imported and invoked from registerGatewayCli). If that service-command file changes, the signature here will stay unchanged, writeCliStartupMetadata can skip regeneration, and shipped precomputed gateway help can go stale until another hashed file changes.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-05-21T03:46:29Z

+    invocation.commandPath.length !== 1 ||
+    !hasHelpFlag(argv) ||
+    invocation.isRootHelpInvocation


Validate argv before taking subcommand help fast path

resolvePrecomputedSubcommandHelpFastPath relies on commandPath + --help presence, but commandPath is built by skipping option tokens, including unknown root flags. That means inputs like openclaw --bogus doctor --help can still resolve to doctor and short-circuit to precomputed help in run-main, bypassing normal CLI parsing/validation and turning an invalid invocation into a successful help response.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-05-21T03:46:29Z

+    !hasHelpFlag(argv) ||
+    invocation.isRootHelpInvocation


Preserve version precedence for help+version subcommand invocations

The new fast path triggers for any allowlisted subcommand with -h/--help, but it does not exclude argv that also contain -V/--version. On the live path, configureProgramHelp in src/cli/program/help.ts checks version flags first and exits with version output, so invocations like openclaw doctor --help --version now return help instead of version only when this fast path is taken. This is a behavior regression introduced by the routing condition.

Useful? React with 👍 / 👎.

clawsweeper · 2026-05-21T03:51:03Z

ClawSweeper PR egg

✨ Hatched: 🥚 common Gilded Lint Imp

Hatch command

Comment @clawsweeper hatch when this PR is hatchable.

Hatchability rules:

Merged PRs are hatchable.
Open PRs are hatchable when they are status: 👀 ready for maintainer look, status: 🚀 automerge armed, or labeled clawsweeper:automerge.
Closed unmerged PRs are hatchable only when one of those hatchable labels is still present in the durable record.

Rarity: 🥚 common.
Trait: keeps receipts.
Image traits: location artifact grotto; accessory tiny test log scroll; palette seafoam, black, and opal; mood sleepy but ready; pose guarding a tiny green check; shell smooth pearl shell; lighting subtle sparkle highlights; background smooth stones and checkmarks.
Share on X: post this hatch
Copy: My PR egg hatched a 🥚 common Gilded Lint Imp in ClawSweeper.

What is this egg doing here?

Eggs appear after the PR passes real-behavior proof. It is here for vibes, not verdicts: it does not change labels, ratings, merge decisions, or automation.
The shell reacts to review momentum: open follow-up work warms it up, re-review makes it wobble, and a clean final review lets it hatch.
Hatchability usually comes from sufficient real-behavior proof, no blocking P0/P1/P2 findings, no security attention needed, and clean correctness. A merged PR is already final, so merge makes the egg hatchable independently.
The hatch is seeded from this repository and PR number, so the same PR keeps the same creature; the reviewed head SHA can only change safe visual details.
Rarity is just collectible sparkle: 🥚 common, 🌱 uncommon, 💎 rare, ✨ glimmer, and 🌈 legendary.

Serve stable doctor, gateway, models, and plugins parent help from startup metadata while preserving strict argv validation and version precedence. Verification: - pnpm test src/cli/run-main.test.ts src/cli/run-main.exit.test.ts test/scripts/write-cli-startup-metadata.test.ts -- --reporter=default - pnpm check:changed - GitHub required checks passed

openclaw-barnacle Bot added cli CLI command changes scripts Repository scripts size: M maintainer Maintainer-authored PR labels May 21, 2026

frankekn self-assigned this May 21, 2026

chatgpt-codex-connector Bot reviewed May 21, 2026

View reviewed changes

clawsweeper Bot added rating: 🦞 diamond lobster Very strong PR readiness with only minor maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. labels May 21, 2026

clawsweeper Bot added the P2 Normal backlog priority with limited blast radius. label May 21, 2026

frankekn force-pushed the perf-04-context-general-help-budget branch 3 times, most recently from f31e12b to 4e25ef0 Compare May 21, 2026 09:40

clawsweeper Bot added the merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. label May 21, 2026

frankekn added 5 commits May 21, 2026 17:55

perf: cache stable subcommand help

ab4e753

fix: validate subcommand help fast path argv

8861fac

docs: credit subcommand help changelog

2932ab6

docs: move subcommand help changelog entry

a91fa7d

docs: move subcommand help changelog to unreleased

1111d0f

frankekn force-pushed the perf-04-context-general-help-budget branch from 3e63c84 to 1111d0f Compare May 21, 2026 09:55

frankekn merged commit f39f56a into main May 21, 2026
98 checks passed

frankekn deleted the perf-04-context-general-help-budget branch May 21, 2026 10:01

github-actions Bot mentioned this pull request May 21, 2026

📡 Upstream Digest — 2026-05-21 10:59 UTC curtismercier/openclaw-mods#907

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

perf(cli): cache stable subcommand help#84786

perf(cli): cache stable subcommand help#84786
frankekn merged 5 commits into
mainfrom
perf-04-context-general-help-budget

frankekn commented May 21, 2026

Uh oh!

clawsweeper Bot commented May 21, 2026 •

edited

Loading

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot May 21, 2026

Uh oh!

chatgpt-codex-connector Bot May 21, 2026

Uh oh!

chatgpt-codex-connector Bot May 21, 2026

Uh oh!

clawsweeper Bot commented May 21, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

frankekn commented May 21, 2026

Summary

Motivation

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

Real behavior proof (required for external PRs)

Root Cause (if applicable)

Regression Test Plan (if applicable)

User-visible / Behavior Changes

Diagram (if applicable)

Security Impact (required)

Repro + Verification

Environment

Steps

Expected

Actual

Evidence

Human Verification (required)

Review Conversations

Compatibility / Migration

Risks and Mitigations

Uh oh!

clawsweeper Bot commented May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot May 21, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot May 21, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot May 21, 2026

Choose a reason for hiding this comment

Uh oh!

clawsweeper Bot commented May 21, 2026

Hatch command

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

clawsweeper Bot commented May 21, 2026 •

edited

Loading