Skip to content

fix: preserve AGENTS policy during bootstrap truncation#82921

Merged
galiniliev merged 3 commits into
openclaw:mainfrom
galiniliev:bug-012-agents-bootstrap-truncation
May 20, 2026
Merged

fix: preserve AGENTS policy during bootstrap truncation#82921
galiniliev merged 3 commits into
openclaw:mainfrom
galiniliev:bug-012-agents-bootstrap-truncation

Conversation

@galiniliev

@galiniliev galiniliev commented May 17, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Problem: oversized workspace AGENTS.md files can lose required scoped policy when bootstrap injection truncates the raw file.
  • Why it matters: subagents may review or edit without rules that appear after the default 12,000-character cap.
  • What changed: AGENTS.md truncation now injects a compact policy digest of markdown headings and high-priority instruction lines alongside the bounded head/tail content.
  • What did NOT change (scope boundary): non-AGENTS.md bootstrap truncation keeps the existing head/tail behavior and size caps.

Change Type (select all)

  • Bug fix
  • Feature
  • Refactor required for the fix
  • Docs
  • Security hardening
  • Chore/infra

Scope (select all touched areas)

  • Gateway / orchestration
  • Skills / tool execution
  • Auth / tokens
  • Memory / storage
  • Integrations
  • API / contracts
  • UI / DX
  • CI/CD / infra

Linked Issue/PR

Real behavior proof (required for external PRs)

Behavior addressed: Oversized workspace AGENTS.md bootstrap context can omit scoped policy in the truncated middle of the file.

Real environment tested: Local Windows OpenClaw worktree for patch hygiene and command execution. Focused Vitest/Testbox execution was attempted but blocked by local process-spawn and Crabbox CLI availability errors.

Exact steps or command run after this patch: git diff --check HEAD~1..HEAD; attempted node scripts/run-vitest.mjs src/agents/pi-embedded-helpers.buildbootstrapcontextfiles.test.ts; attempted direct node node_modules\vitest\vitest.mjs run src/agents/pi-embedded-helpers.buildbootstrapcontextfiles.test.ts --reporter=verbose; attempted codex review --uncommitted; attempted node scripts/crabbox-wrapper.mjs --help and a Blacksmith Testbox wrapper run.

Evidence after fix: Terminal capture and copied console output:

git diff --check HEAD~1..HEAD
exit code: 0; no whitespace output

node scripts/run-vitest.mjs src/agents/pi-embedded-helpers.buildbootstrapcontextfiles.test.ts
Error: spawn EPERM

node node_modules\vitest\vitest.mjs run src/agents/pi-embedded-helpers.buildbootstrapcontextfiles.test.ts --reporter=verbose
timed out after 124s without test output

codex review --uncommitted
ERROR: unexpected status 401 Unauthorized: Missing bearer or basic authentication in header

node scripts/crabbox-wrapper.mjs --help
[crabbox] selected binary failed basic --version/--help sanity checks

Observed result after fix: Patch hygiene passes, and the committed regression test asserts that a required scoped AGENTS.md instruction in oversized middle content is present in the injected policy digest while staying under the configured budget.

What was not tested: Live/provider/session behavior was not run. Focused Vitest did not complete locally because Node child-process spawning failed with EPERM; remote Testbox proof did not start because the local Crabbox wrapper could not pass its binary sanity check.

Before evidence: Redacted source logs showed workspace bootstrap file AGENTS.md is 17198 chars (limit 12000); truncating in injected context (sessionKey=[redacted agent session key]) and workspace bootstrap file AGENTS.md is 21498 chars (limit 12000); truncating in injected context (sessionKey=[redacted agent session key]).

Root Cause (if applicable)

  • Root cause: buildBootstrapContextFiles used a generic bounded head/tail truncation path for all bootstrap files, including policy-heavy AGENTS.md files.
  • Missing detection / guardrail: There was no regression covering a required scoped instruction located in the middle of oversized AGENTS.md content.
  • Contributing context (if known): The default per-file bootstrap cap is 12,000 characters, while observed AGENTS.md inputs exceeded that size.

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/agents/pi-embedded-helpers.buildbootstrapcontextfiles.test.ts
  • Scenario the test should lock in: Required scoped policy in the middle of oversized AGENTS.md content remains visible through the policy digest after truncation.
  • Why this is the smallest reliable guardrail: The bug is in the pure bootstrap-context construction helper before provider/model execution.
  • Existing test that already covers this (if any): None found.
  • If no new test is added, why not: N/A

User-visible / Behavior Changes

Subagents receive a compact AGENTS.md policy digest when raw AGENTS.md bootstrap content must be truncated.

Diagram (if applicable)

Before:
oversized AGENTS.md -> head/tail truncation -> middle scoped policy may be omitted

After:
oversized AGENTS.md -> head + policy digest + tail -> scoped policy remains visible within budget

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: Windows local worktree
  • Runtime/container: Node 24.15.0 local command environment
  • Model/provider: N/A; pure bootstrap context builder
  • Integration/channel (if any): Embedded agent/subagent bootstrap context
  • Relevant config (redacted): Default bootstrap cap behavior

Steps

  1. Build oversized AGENTS.md content with a required scoped instruction in the middle.
  2. Call buildBootstrapContextFiles with a small maxChars budget.
  3. Inspect the injected content.

Expected

  • The required scoped instruction appears in the policy digest and the injected content stays within budget.

Actual

  • Before this patch, generic head/tail truncation could omit the middle instruction. This patch adds the digest path and regression assertion.

Evidence

Attach at least one:

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

Human Verification (required)

What you personally verified (not just CI), and how:

  • Verified scenarios: Reviewed the bootstrap truncation code path, added the focused regression test, verified patch hygiene with git diff --check HEAD~1..HEAD.
  • Edge cases checked: Non-AGENTS.md files continue using the existing truncation path; the new digest path remains bounded by maxChars.
  • What you did not verify: Focused Vitest, Codex review, remote Testbox, and live agent/session behavior were blocked as detailed above.

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.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

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: The policy digest may not include every line from very large AGENTS.md files.
    • Mitigation: The injected content still tells agents to read the full file, and high-priority policy lines are prioritized inside the existing budget.

@openclaw-barnacle openclaw-barnacle Bot added agents Agent runtime and tooling size: S maintainer Maintainer-authored PR labels May 17, 2026
@clawsweeper

clawsweeper Bot commented May 17, 2026

Copy link
Copy Markdown
Contributor

Codex review: needs real behavior proof 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
The PR adds an AGENTS.md-specific bootstrap truncation digest, an explicit AGENTS truncation warning, and focused regression coverage.

Reproducibility: yes. at source level: current main and v2026.5.18 use generic head/tail truncation for AGENTS.md, so a required policy line placed in the omitted middle can be absent from injected context. I did not run a test in this read-only review.

PR rating
Overall: 🧂 unranked krab
Proof: 🧂 unranked krab
Patch quality: 🦐 gold shrimp
Summary: The branch is a plausible focused fix, but the missing successful proof and the budget-allocation correctness issue make it not quality-ready yet.

Rank-up moves:

  • Reallocate unused digest budget to raw head/tail content or fall back to generic trimming when the digest is sparse.
  • Add successful after-fix proof, such as focused test output, helper output, or redacted runtime logs showing middle AGENTS.md policy preserved.
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
Needs stronger real behavior proof before merge: The PR body includes terminal text for patch hygiene and blocked/failed test attempts, but no successful after-fix helper output, focused test run, runtime log, screenshot, recording, or redacted live output showing the new digest behavior. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Risk before merge

  • Large AGENTS.md files with sparse or empty digest candidates can receive much less raw head/tail content than current main because unused digest allocation is not returned to raw content.
  • Contributor proof is insufficient: the PR body shows patch hygiene and blocked/failed test attempts, but no successful after-fix run of the changed behavior.
  • The protected maintainer label means merge or cleanup needs explicit maintainer handling even after the code finding is fixed.

Maintainer options:

  1. Fix budget allocation before merge (recommended)
    Update the AGENTS trim path to reclaim unused digest space for raw head/tail content, or fall back to the generic splitter when the digest is sparse, then prove the focused behavior.
  2. Explicitly accept reduced raw context
    Maintainers could intentionally accept less raw AGENTS.md context when the digest is sparse, but that should be an explicit context-quality decision before merge.

Next step before merge
Human PR handling is needed because the contributor proof is insufficient and the protected maintainer label plus the budget-allocation finding must be resolved on this branch before merge.

Security
Cleared: The diff changes in-process TypeScript bootstrap formatting and colocated tests only, with no new dependencies, workflows, network calls, secret handling, or command-execution surface.

Review findings

  • [P2] Reallocate unused digest budget — src/agents/pi-embedded-helpers/bootstrap.ts:229-232
Review details

Best possible solution:

Keep the AGENTS.md digest approach, preserve the per-file budget by reallocating unused digest capacity to raw head/tail or falling back to generic trimming, and land it with successful focused proof for the linked bug.

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

Yes at source level: current main and v2026.5.18 use generic head/tail truncation for AGENTS.md, so a required policy line placed in the omitted middle can be absent from injected context. I did not run a test in this read-only review.

Is this the best way to solve the issue?

No, not as written: the AGENTS.md digest is a maintainable direction, but the implementation should preserve the existing per-file budget by reallocating unused digest space or falling back to generic trimming before merge.

Label changes:

  • add merge-risk: 🚨 session-state: Merging as written can change injected AGENTS.md context for existing large files and drop raw policy bytes from subagent sessions.
  • add rating: 🧂 unranked krab: Current PR rating is 🧂 unranked krab because proof is 🧂 unranked krab, patch quality is 🦐 gold shrimp, and The branch is a plausible focused fix, but the missing successful proof and the budget-allocation correctness issue make it not quality-ready yet.
  • add status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs stronger real behavior proof before merge: The PR body includes terminal text for patch hygiene and blocked/failed test attempts, but no successful after-fix helper output, focused test run, runtime log, screenshot, recording, or redacted live output showing the new digest behavior. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
  • remove impact:session-state: Current review selected no impact labels.

Full review comments:

  • [P2] Reallocate unused digest budget — src/agents/pi-embedded-helpers/bootstrap.ts:229-232
    In the AGENTS-specific path, head/tail are fixed at 45%/15% of maxChars and the digest is built from a separate 35% allocation. When the digest is short or empty, the rendered result can sit far under the per-file budget, so large AGENTS.md files lose raw head/tail content that current main would still include. Reallocate unused digest capacity to raw content, or fall back to the generic splitter when there is no useful digest.
    Confidence: 0.86

Overall correctness: patch is incorrect
Overall confidence: 0.84

What I checked:

Likely related people:

  • steipete: git shortlog shows Peter Steinberger as the highest-count contributor across the central bootstrap helper/test files, and commit bcbfb35 split the current helper and colocated tests into this area. (role: primary area contributor; confidence: high; commits: bcbfb357bec7, 4267fc859303; files: src/agents/pi-embedded-helpers/bootstrap.ts, src/agents/pi-embedded-helpers.buildbootstrapcontextfiles.test.ts)
  • gumadeiras: Gustavo Madeira Santana authored recent bootstrap budget and truncation-warning work, including e4b4486 and 8a67016, which directly shape this PR's affected behavior. (role: adjacent truncation owner; confidence: high; commits: e4b4486a96a9, 8a67016646a0; files: src/agents/bootstrap-budget.ts, src/agents/bootstrap-budget.test.ts, src/agents/pi-embedded-helpers/bootstrap.ts)

Codex review notes: model gpt-5.5, reasoning high; reviewed against 0556ac0291a8.

@clawsweeper clawsweeper Bot added P1 High-priority user-facing bug, regression, or broken workflow. impact:session-state Session, memory, transcript, context, or agent state can drift or corrupt. labels May 17, 2026
@galiniliev galiniliev self-assigned this May 20, 2026
@clawsweeper clawsweeper Bot added rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. merge-risk: 🚨 session-state 🚨 May lose, corrupt, stale, or mis-associate session, agent, or context state. and removed impact:session-state Session, memory, transcript, context, or agent state can drift or corrupt. labels May 20, 2026
@clawsweeper

clawsweeper Bot commented May 20, 2026

Copy link
Copy Markdown
Contributor

ClawSweeper PR egg

🎁 Pass real behavior proof to wake the egg and unlock a hatchable treat.

Where did the egg go?
  • The egg game starts only after the PR passes the real-behavior proof check.
  • Before that, no creature or rarity is rolled. The treat waits for real proof.
  • This is still just collectible flavor: proof affects review readiness, not creature quality.

@galiniliev galiniliev force-pushed the bug-012-agents-bootstrap-truncation branch from f6d54fe to 5984afe Compare May 20, 2026 03:18
@galiniliev

Copy link
Copy Markdown
Contributor Author

Verification for landing head 5984afe:

Behavior addressed: AGENTS.md bootstrap truncation now preserves high-priority policy content and surfaces a UX warning when AGENTS.md content is trimmed.
Real environment tested: GitHub CI on openclaw/openclaw PR #82921, head 5984afe.
Exact steps or command run after this patch:

  • git diff --check origin/main..HEAD
  • node scripts/run-oxlint.mjs src/agents/pi-embedded-helpers/bootstrap.ts src/agents/bootstrap-budget.ts src/agents/bootstrap-budget.test.ts CHANGELOG.md
  • env -u GH_HOST gh pr checks 82921 --repo openclaw/openclaw --watch --interval 15
    Evidence after fix: local diff whitespace check passed; local oxlint passed; GitHub CI passed including Real behavior proof, check-lint, check-prod-types, check-test-types, build-artifacts, CodeQL Security High shards, and Critical Quality (network-runtime-boundary).
    Observed result after fix: PR head is CLEAN/MERGEABLE with all visible required checks green.
    What was not tested: local Vitest was not rerun after the rebase because an earlier local run hung during bundler startup; the PR's regression tests ran through CI as the authoritative proof.

@galiniliev galiniliev merged commit ad925bd into openclaw:main May 20, 2026
98 checks passed
frankhli843 added a commit to gemmaclaw/gemmaclaw that referenced this pull request May 21, 2026
* fix(errors): dedupe identical messages when traversing error .cause chain (openclaw#84556)

Merged via squash.

Prepared head SHA: 46aa27f
Co-authored-by: RomneyDa <6581799+RomneyDa@users.noreply.github.com>
Co-authored-by: altaywtf <9790196+altaywtf@users.noreply.github.com>
Reviewed-by: @altaywtf

* fix(cli): gate exported subcli descriptors (openclaw#84519)

Summary:
- This PR filters exported sub-CLI descriptors through the private-QA gate, centralizes that filter, adds regr ... ge, and carries small validation repairs in workspace glob and tunnel-timeout tests plus a changelog entry.
- Reproducibility: yes. Current-main source shows the raw SUB_CLI_DESCRIPTORS export can include qa while the helper surfaces filter it, and src/cli/argv.ts consumes that export for root command policy.

Automerge notes:
- PR branch already contained follow-up commit before automerge: fix(cli): gate exported subcli descriptors
- PR branch already contained follow-up commit before automerge: fix(clawsweeper): address review for automerge-openclaw-openclaw-8451…

Validation:
- ClawSweeper review passed for head ba197a6.
- Required merge gates passed before the squash merge.

Prepared head SHA: ba197a6
Review: openclaw#84519 (comment)

Co-authored-by: Zhaocun <zhaocunsun@gmail.com>
Co-authored-by: clawsweeper <274271284+clawsweeper[bot]@users.noreply.github.com>
Co-authored-by: clawsweeper[bot] <274271284+clawsweeper[bot]@users.noreply.github.com>
Approved-by: takhoffman
Co-authored-by: takhoffman <781889+takhoffman@users.noreply.github.com>

* fix(doctor): migrate invalid thinking formats (openclaw#84626)

* fix(cron-cli): bound loadCronJobForShow pagination (openclaw#83856) (openclaw#83989)

Summary:
- Adds a 50-page and advancing-`nextOffset` guard to `loadCronJobForShow`, exports that helper for regression tests, and adds an unreleased changelog entry.
- Reproducibility: yes. Current main is source-reproducible because `loadCronJobForShow` loops while `hasMore` ... ed numeric `nextOffset`; the PR discussion also includes terminal before/after proof for the same CLI path.

Automerge notes:
- No ClawSweeper repair was needed after automerge opt-in.

Validation:
- ClawSweeper review passed for head 7828b4b.
- Required merge gates passed before the squash merge.

Prepared head SHA: 7828b4b
Review: openclaw#83989 (comment)

Co-authored-by: clawsweeper <274271284+clawsweeper[bot]@users.noreply.github.com>
Co-authored-by: clawsweeper[bot] <274271284+clawsweeper[bot]@users.noreply.github.com>
Approved-by: takhoffman
Co-authored-by: takhoffman <781889+takhoffman@users.noreply.github.com>

* fix(config): accept execApprovals.enabled="auto" in zod schema

* fix: honour tool error suppression for mutating tools (openclaw#81561)

Merged via squash.

Prepared head SHA: 7462a86
Co-authored-by: moeedahmed <5780040+moeedahmed@users.noreply.github.com>
Co-authored-by: jalehman <550978+jalehman@users.noreply.github.com>
Reviewed-by: @jalehman

* Add OpenRouter provider routing params (openclaw#84579)

Co-authored-by: Alex Knight <15041791+amknight@users.noreply.github.com>

* Preserve AGENTS.md policy during bootstrap truncation (openclaw#82921)

Fixes openclaw#82920

* chore: regenerate base config schema

Updated after MODEL_THINKING_FORMATS changed from z.union literals to
z.enum, and session/session.agentToAgent gained detailed help text.

* Revert "Add OpenRouter provider routing params (openclaw#84579)"

This reverts commit 53254dc.

---------

Co-authored-by: Dallin Romney <dallinromney@gmail.com>
Co-authored-by: RomneyDa <6581799+RomneyDa@users.noreply.github.com>
Co-authored-by: altaywtf <9790196+altaywtf@users.noreply.github.com>
Co-authored-by: Zhaocun Sun <zhaocunsun@gmail.com>
Co-authored-by: clawsweeper <274271284+clawsweeper[bot]@users.noreply.github.com>
Co-authored-by: takhoffman <781889+takhoffman@users.noreply.github.com>
Co-authored-by: Gio Della-Libera <giodl73@gmail.com>
Co-authored-by: yaoyi1222 <yaoyi_1222@163.com>
Co-authored-by: Sarah Fortune <sarah.fortune@gmail.com>
Co-authored-by: Moeed Ahmed <drmoeedahmed@gmail.com>
Co-authored-by: moeedahmed <5780040+moeedahmed@users.noreply.github.com>
Co-authored-by: jalehman <550978+jalehman@users.noreply.github.com>
Co-authored-by: Alex Knight <aknight@atlassian.com>
Co-authored-by: Alex Knight <15041791+amknight@users.noreply.github.com>
Co-authored-by: Galin Iliev <iliev@galcho.com>
SebTardif pushed a commit to SebTardif/openclaw that referenced this pull request May 24, 2026
SebTardif pushed a commit to SebTardif/openclaw that referenced this pull request May 24, 2026
SebTardif pushed a commit to SebTardif/openclaw that referenced this pull request May 24, 2026
github-actions Bot pushed a commit to Desicool/openclaw that referenced this pull request May 24, 2026
galiniliev added a commit to galiniliev/openclaw that referenced this pull request May 25, 2026
SebTardif pushed a commit to SebTardif/openclaw that referenced this pull request May 26, 2026
SebTardif pushed a commit to SebTardif/openclaw that referenced this pull request May 26, 2026
SebTardif pushed a commit to SebTardif/openclaw that referenced this pull request May 26, 2026
jameslcowan pushed a commit to jameslcowan/openclaw that referenced this pull request Jun 2, 2026
SYU8384 pushed a commit to SYU8384/openclaw that referenced this pull request Jun 3, 2026
sablehead pushed a commit to sablehead/openclaw that referenced this pull request Jun 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

agents Agent runtime and tooling maintainer Maintainer-authored PR merge-risk: 🚨 session-state 🚨 May lose, corrupt, stale, or mis-associate session, agent, or context state. P1 High-priority user-facing bug, regression, or broken workflow. rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. size: S status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug]: AGENTS.md bootstrap truncation may omit scoped instructions

1 participant