#19826: fix: add in-prompt warnings and doctor check for bootstrap file truncation

## Summary Addresses silent truncation of bootstrap files (AGENTS.md, TOOLS.md, etc.) which led to unpredictable agent behavior. - **Problem**: Bootstrap files exceeding context budgets were silently truncated, causing agents to miss critical instructions/safety rules. - **Why it matters**: Users had no visibility into why an agent ignored instructions, and debugging was difficult without digging into logs. - **What changed**: - Injected a visible warning into the system prompt when files are truncated. - Added `openclaw doctor` check for bootstrap file health (size vs budget). - Updated [buildBootstrapContextFiles](cci:1://file:///home/akram/openclaw/src/agents/pi-embedded-helpers/bootstrap.ts:197:0-255:1) to return truncation metadata. - **What did NOT change**: Actual truncation logic remains the same (still strictly enforcing budgets); only visibility improved. ## Change Type (select all) - [ ] Bug fix - [x] Feature (Diagnostic/DX) - [ ] Refactor - [ ] Docs - [ ] Security hardening - [ ] Chore/infra ## Scope (select all touched areas) - [ ] Gateway / orchestration - [x] Skills / tool execution (System prompt construction) - [ ] Auth / tokens - [ ] Memory / storage - [ ] Integrations - [ ] API / contracts - [x] UI / DX (`openclaw doctor` output) - [ ] CI/CD / infra ## Linked Issue/PR - Closes #19123 ## User-visible / Behavior Changes 1. **System Prompt**: If bootstrap files are truncated, the agent now sees: Bootstrap files truncated (context budget limits): AGENTS.md: truncated from 20013 to 17000 chars Consider moving content to docs/reference/ files or increasing agents.defaults.bootstrapMaxChars. 2. **CLI**: `openclaw doctor` output now includes: Bootstrap files Total budget: 30000 chars ✓ TOOLS.md: 2,855 / 30,000 chars (10%) AGENTS.md: 20,013 / 30,000 chars (67%) - near limit! ## Security Impact (required) - New permissions/capabilities? (`No`) - Secrets/tokens handling changed? (`No`) - New/changed network calls? (`No`) - Command/tool execution surface changed? (`No`) - Data access scope changed? (`No`) ## Repro + Verification ### Steps 1. Create a large `AGENTS.md` file (e.g., >20k chars) in workspace. 2. Run `openclaw doctor`. 3. Start an agent session and check system prompt (or run e2e tests). ### Expected - `openclaw doctor` shows `⚠` or `✗` for the large file. - Agent system prompt contains the truncation warning block. ### Actual - Confirmed `openclaw doctor` output flags the file. - Confirmed system prompt warning injection via tests. ## Evidence - **Tests**: Added [pi-embedded-helpers.buildbootstrapcontextfiles.e2e.test.ts](cci:7://file:///home/akram/openclaw/src/agents/pi-embedded-helpers.buildbootstrapcontextfiles.e2e.test.ts:0:0-0:0) cases covering truncation metadata and warning generation. All 17 tests passed. - **Lint**: Fixed `no-unused-vars` error in [doctor-bootstrap.ts](cci:7://file:///home/akram/openclaw/src/commands/doctor-bootstrap.ts:0:0-0:0). - **Verify**: `tsc` build passed clean. ## Human Verification (required) - Verified scenarios: - Normal file sizes (no warning). - Single file truncation. - Total budget exhaustion (skipping subsequent files). - Edge cases checked: - Missing files (still handled correctly). - Empty files. ## Compatibility / Migration - Backward compatible? (`Yes`) - Config/env changes? (`No`) - Migration needed? (`No`) <!-- greptile_comment --> <h3>Greptile Summary</h3> This PR adds visibility into bootstrap file truncation by: 1. Modifying `buildBootstrapContextFiles` to return truncation metadata (`BootstrapTruncationInfo[]`) alongside the files array, tracking both partially truncated and fully skipped files. 2. Injecting a warning section into the agent system prompt when files are truncated or skipped. 3. Adding an `openclaw doctor` check (`noteBootstrapFileHealth`) that reports per-file and total budget utilization. The changes are well-structured and propagated consistently across all call sites (`cli-runner`, `compact`, `attempt`, `commands-system-prompt`). The new types are properly exported through the barrel file. Tests cover the new truncation metadata, including edge cases for skipped files. - The system prompt now correctly differentiates between "truncated" and "SKIPPED" files (addressing the budget-exhaustion case). - The doctor check shows both per-file percentage and cumulative total budget usage. - Import reordering across files (type imports before value imports) is a style-only change with no behavioral impact. <h3>Confidence Score: 4/5</h3> - This PR is safe to merge — it adds diagnostic visibility without changing truncation behavior. - The PR is well-structured with consistent propagation of the new truncation metadata across all call sites. Changes are additive (new types, new optional param, new doctor check) with no modifications to existing truncation logic. Tests cover the key scenarios. One minor style inconsistency found (trimEnd not applied in the skipped-files path). - src/agents/pi-embedded-helpers/bootstrap.ts has a minor `originalChars` inconsistency between truncated and skipped paths. src/commands/doctor-bootstrap.ts is a new file that should be verified with real workspace files. _{Last reviewed commit: a2e31dd} <!-- greptile_other_comments_section --> <!-- /greptile_comment -->