PR #59344: fix(agents): dedupe bootstrap context files by path

• Repository: openclaw/openclaw
• Author: koen666
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/59344

Description (problem / solution / changelog)

PR Draft: Fix #59319

Summary

Describe the problem and fix in 2–5 bullets:

If this PR fixes a plugin beta-release blocker, title it fix(<plugin-id>): beta blocker - <summary> and link the matching Beta blocker: <plugin-name> - <summary> issue labeled beta-blocker. Contributors cannot label PRs, so the title is the PR-side signal for maintainers and automation.

• Problem: bootstrap context assembly could inject the same file multiple times when hook-adjusted entries repeated an existing file path.
• Why it matters: duplicate bootstrap content wastes prompt budget/tokens and can dilute important context.
• What changed: added path-based deduplication in bootstrap-file sanitization and added a targeted unit test for duplicate-path behavior.
• What did NOT change (scope boundary): no change to bootstrap file discovery order, session filtering policy, or hook execution semantics.

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

• Closes #59319
• Related #N/A
• This PR fixes a bug or regression

Root Cause / Regression History (if applicable)

For bug fixes or regressions, explain why this happened, not just what changed. Otherwise write N/A. If the cause is unclear, write Unknown.

• Root cause: resolveBootstrapFilesForRun sanitized invalid paths but did not deduplicate normalized file paths after hook overrides, so duplicates could survive into context injection.
• Missing detection / guardrail: no unit assertion guaranteed uniqueness of bootstrap entries by resolved path.
• Prior context (git blame, prior PR, issue, or refactor if known): Unknown from this change set; behavior existed before this fix and was reported in #59319.
• Why this regressed now: not necessarily a new regression; likely surfaced by real-world hook/config combinations that add overlapping bootstrap entries.
• If unknown, what was ruled out: ruled out malformed-path-only failure mode (that path already had tests and filtering).

Regression Test Plan (if applicable)

For bug fixes or regressions, name the smallest reliable test coverage that should have caught this. Otherwise write N/A.

• 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/bootstrap-files.test.ts
• Scenario the test should lock in: when a hook appends a bootstrap file with a path that already exists in base bootstrap files, the final list contains exactly one entry for that resolved path.
• Why this is the smallest reliable guardrail: deduplication happens inside bootstrap-file sanitization, so unit-level coverage at that seam is direct and stable.
• Existing test that already covers this (if any): none before this PR.
• If no new test is added, why not: N/A (new test added).

User-visible / Behavior Changes

• Bootstrap context no longer includes duplicate copies of the same file path when duplicates are introduced by hook-adjusted bootstrap entries.

Diagram (if applicable)

Before:
[base bootstrap files + hook extras] -> [sanitize only invalid paths] -> [duplicate file paths remain] -> [context includes repeated file]

After:
[base bootstrap files + hook extras] -> [sanitize invalid paths + dedupe by resolved path] -> [unique file paths] -> [context includes file once]

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 (darwin)
• Runtime/container: Node 22 + pnpm workspace (local dev environment)
• Model/provider: N/A
• Integration/channel (if any): N/A
• Relevant config (redacted): default test config (no special secrets)

Steps

1. Add or simulate a bootstrap hook that appends MEMORY.md with a path already present in bootstrap files.
2. Run resolveBootstrapFilesForRun with a warning collector.
3. Inspect returned files and warnings.

Expected

• Only one entry remains for the duplicated resolved path.
• A duplicate-skip warning is emitted.

Actual

• Matches expected after the fix.

Evidence

Attach at least one:

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

Notes:

• Added/ran src/agents/bootstrap-files.test.ts case: deduplicates bootstrap files by resolved path.
• Verification commands:
  • pnpm test -- src/agents/bootstrap-files.test.ts
  • pnpm check

Human Verification (required)

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

• Verified scenarios: duplicate path from hook override is dropped; warning message emitted; malformed path filtering still works.
• Edge cases checked: duplicate exact absolute path; preserved behavior for valid non-duplicate files.
• What you did not verify: full end-to-end prompt token accounting in a live gateway run.

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

List only real risks for this PR. Add/remove entries as needed. If none, write None.

• Risk: path normalization (path.resolve) might collapse distinct textual paths that intentionally referred to the same file via different relative forms.
  • Mitigation: this is intended; dedupe key is file path identity at injection boundary, and behavior is covered by unit test.

Changed files

• src/agents/bootstrap-files.test.ts (modified, +31/-0)
• src/agents/bootstrap-files.ts (modified, +8/-0)