Skip to content

fix(runtime): bound hook output under constrained memory - #10

Merged
vincentkoc merged 3 commits into
mainfrom
test/low-memory-runtime
Jul 30, 2026
Merged

vincentkoc merged 3 commits into
mainfrom
test/low-memory-runtime

Conversation

@vincentkoc

@vincentkoc vincentkoc commented Jul 30, 2026 •

Copy link
Copy Markdown
Member

Summary

  • What changed: cap imported command-hook stdout and stderr at 1 MiB per stream, terminate noisy process trees, and add a reusable Docker low-memory matrix.
  • Why: unbounded hook output could exhaust OpenClaw memory before the existing timeout fired; the new matrix exercises Raspberry Pi / potato-class resource limits.
  • Related issue: none

Compatibility

  • Source app(s): Claude Code, Codex, Hermes Agent
  • Affected surface(s): imported command hooks; build/test/package gates; CLI install/list/uninstall; generated native tools; MCP stdio
  • Trust-boundary or execution impact: noisy imported hooks are terminated and reported as failed after exceeding the output cap; existing hook-failure handling remains unchanged.

Verification

  • Added or updated focused tests.
  • Ran npm run check (63 tests).
  • Ran npm run pack:check.
  • Ran NODE_OPTIONS=--max-old-space-size=64 npm run test:low-memory:e2e (Hermes, Claude Code, Codex lifecycle plus MCP stdio).
  • Updated the README compatibility table when behavior changed. (No mapping change required.)
  • Updated CHANGELOG.md for user-visible or operational changes.
  • Removed secrets, private paths, and generated artifacts from the diff.
  • Docker constrained-memory CI passed the 1 GiB full gate, 512 MiB runtime gate, and 256 MiB E2E gate with zero OOM kills.

@vincentkoc vincentkoc self-assigned this Jul 30, 2026
@vincentkoc
vincentkoc marked this pull request as ready for review July 30, 2026 15:12
@vincentkoc

Copy link
Copy Markdown
Member Author

@clawsweeper review

@clawsweeper

clawsweeper Bot commented Jul 30, 2026 •

Copy link
Copy Markdown

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

@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. P2 Normal priority bug or improvement with limited blast radius. merge-risk: 🚨 compatibility 🚨 Merging this PR could break existing users, config, migrations, defaults, or upgrades. labels Jul 30, 2026
@clawsweeper

clawsweeper Bot commented Jul 30, 2026 •

Copy link
Copy Markdown

Codex review: needs maintainer review before merge. Reviewed July 30, 2026, 11:22 AM ET / 15:22 UTC.

ClawSweeper review

What this changes

This PR limits stdout and stderr from imported Codex and Claude Code command hooks to 1 MiB per stream, terminates overflowing hook processes, documents the compatibility contract, and adds constrained-memory Docker validation.

Merge readiness

⚠️ Ready for maintainer review - 2 items remain

Keep this PR open for normal maintainer merge review. The previous documentation blocker is resolved: the current head adds the requested compatibility-table row for the 1 MiB per-stream hook-output contract, and the reported checks—including the constrained-memory workflow—are green; no new line-level correctness defect is evident from the available diff and review context.

Priority: P2
Reviewed head: 179189be85ba6da0b0c059632ad4cca62a3468a6

Review scores

Measure Result What it means
Overall readiness 🐚 platinum hermit (4/6) The patch is focused, resolves the prior documentation finding, includes a direct overflow regression test, and is supported by successful constrained-memory CI.
Proof confidence 🐚 platinum hermit (4/6) Not applicable: This repository-MEMBER PR is not subject to the external-contributor real-behavior-proof gate; its body reports a real Docker constrained-memory run and the corresponding CI check is successful.
Patch quality 🐚 platinum hermit (4/6) No actionable review findings were identified.

Verification

Check Result Evidence
Real behavior Not applicable Not applicable: This repository-MEMBER PR is not subject to the external-contributor real-behavior-proof gate; its body reports a real Docker constrained-memory run and the corresponding CI check is successful.
Evidence reviewed 4 items Prior review blocker resolved: The earlier P2 finding asked for the new hook-output contract to appear in the README compatibility table. The current head adds a compatibility row stating that Codex and Claude Code hooks are terminated and reported failed above 1 MiB on stdout or stderr.
Focused regression coverage: The branch adds a noisy-hook fixture that emits 2 MiB and asserts the hook invocation resolves through existing failure handling while warning about the 1048576-byte cap.
Runtime behavior: The proposed hook runner counts stdout and stderr independently, terminates the process tree after either exceeds the cap, and reports a descriptive hook error; the existing timeout follows the same termination path.
Findings None None.
Security None None.

How this fits together

Babelfish translates source-plugin command hooks into OpenClaw runtime hooks. The runtime starts a hook process, captures its stdout and stderr for hook handling, and reports process failures back to the calling OpenClaw flow.

flowchart LR
  A[Source plugin manifest] --> B[Imported command hook]
  B --> C[Hook process runtime]
  C --> D[Per-stream output and timeout checks]
  D --> E[Hook result or reported failure]
  E --> F[OpenClaw plugin flow]
Loading

Before merge

  • Resolve merge risk (P1) - Existing imported hooks that legitimately emit more than 1 MiB on either stdout or stderr will now be terminated and treated as failed; the behavior is documented, but maintainers should accept this compatibility contract before merge.
  • Complete next step (P2) - The prior concrete P2 documentation finding is addressed and no narrow mechanical repair remains; this repository-MEMBER PR should proceed through normal maintainer merge review.
Agent review details

Security

None.

Review metrics

Metric Value Why it matters
Patch surface 11 files affected; 427 added, 3 removed The runtime hardening is accompanied by documentation, focused coverage, low-memory end-to-end validation, and one CI workflow.
Memory tiers 3 Docker tiers: 1 GiB, 512 MiB, 256 MiB The new matrix checks the behavior under progressively constrained runtime limits rather than only the default development environment.

Merge-risk options

Maintainer options:

  1. Land the documented hook limit (recommended)
    Accept the explicit 1 MiB per-stream hook contract, which the PR now documents in the compatibility table and exercises with a focused overflow test.

Technical review

Best possible solution:

Merge the narrowly documented per-stream cap if maintainers accept 1 MiB as the supported hook-output contract, preserving the existing hook-failure behavior and constrained-memory regression coverage.

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

Yes, source-reproducible: the focused test creates an imported command hook that emits 2 MiB, and the proposed runtime path explicitly detects and terminates that overflow. The available review environment did not permit independently running the test.

Is this the best way to solve the issue?

Yes: independently capping each captured stream, terminating the process tree, and routing the failure through existing hook-failure handling is a narrow solution that addresses the stated memory-exhaustion path without changing hook result formats.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 807a7c54e76f.

Labels

Label changes:

  • add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
  • add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: This repository-MEMBER PR is not subject to the external-contributor real-behavior-proof gate; its body reports a real Docker constrained-memory run and the corresponding CI check is successful.
  • remove rating: 🦐 gold shrimp: Current PR rating is rating: 🐚 platinum hermit, so this older rating label is no longer current.
  • remove status: ⏳ waiting on author: Current PR status label is status: 👀 ready for maintainer look.

Label justifications:

  • P2: This is a bounded runtime reliability fix with compatibility-sensitive behavior for imported hooks, not an active emergency.
  • merge-risk: 🚨 compatibility: The new cap intentionally makes existing hooks fail when either output stream exceeds 1 MiB.
  • rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
  • status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: This repository-MEMBER PR is not subject to the external-contributor real-behavior-proof gate; its body reports a real Docker constrained-memory run and the corresponding CI check is successful.

Evidence

What I checked:

  • Prior review blocker resolved: The earlier P2 finding asked for the new hook-output contract to appear in the README compatibility table. The current head adds a compatibility row stating that Codex and Claude Code hooks are terminated and reported failed above 1 MiB on stdout or stderr. (README.md:94, 179189be85ba)
  • Focused regression coverage: The branch adds a noisy-hook fixture that emits 2 MiB and asserts the hook invocation resolves through existing failure handling while warning about the 1048576-byte cap. (src/bundle-plugins.test.ts:57, 179189be85ba)
  • Runtime behavior: The proposed hook runner counts stdout and stderr independently, terminates the process tree after either exceeds the cap, and reports a descriptive hook error; the existing timeout follows the same termination path. (src/bundle-plugins.ts:803, 71e2e49d2680)
  • Observed validation status: The PR context reports successful cross-platform check jobs, CodeQL, and the Docker constrained-memory matrix; the branch also adds the Docker workflow with read-only contents permission and pinned checkout action reference. (.github/workflows/low-memory.yml:1, 7efd86ad7731)

Likely related people:

  • vincentkoc: The available PR history attributes the hook limit, low-memory validation, and compatibility-table follow-up to this repository MEMBER; no broader current-main ownership trail was available from the read-only inspection environment. (role: recent runtime contributor; confidence: low; commits: 71e2e49d2680, 7efd86ad7731, 179189be85ba; files: src/bundle-plugins.ts, src/bundle-plugins.test.ts, README.md)

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-07-30T15:16:47.628Z sha 7efd86a :: needs changes before merge. :: [P2] Document the hook output cap in the compatibility table

@vincentkoc

Copy link
Copy Markdown
Member Author

@clawsweeper re-review

@clawsweeper

clawsweeper Bot commented Jul 30, 2026 •

Copy link
Copy Markdown

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

@clawsweeper clawsweeper Bot added 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. and removed 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. labels Jul 30, 2026
@vincentkoc

Copy link
Copy Markdown
Member Author

Maintainer decision: accepting the documented 1 MiB per-stream limit for imported Codex and Claude Code command hooks. The change is narrowly scoped, preserves existing hook-failure handling, and the exact head passed cross-platform CI, CodeQL, and the 1 GiB / 512 MiB / 256 MiB Docker matrix with zero OOM kills.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

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. 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.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant