PR #61236: fix(cache): order stable project context before heartbeat

• Repository: openclaw/openclaw
• Author: vincentkoc
• State: closed | merged: True
• Link: https://github.com/openclaw/openclaw/pull/61236

Description (problem / solution / changelog)

Summary

• Problem: workspace project-context files are injected in a fixed order that leaves frequently changing files like HEARTBEAT.md on the stable side of the system-prompt cache boundary.
• Why it matters: heartbeat churn invalidates the cached project-context prefix even when the stable workspace files did not change, which wastes prompt-cache reuse.
• What changed: sort known workspace context files in a stable-first order during system-prompt assembly, keep stable files above the existing cache boundary, and move HEARTBEAT.md below that boundary as dynamic project context.
• What did NOT change (scope boundary): this does not add new config, does not change bootstrap file loading/filtering, and does not try to solve arbitrary hook-injected dynamic context ordering.

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

• Fixes #58979
• Related #59054
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: loadWorkspaceBootstrapFiles() uses a deterministic but cache-unaware file order, and buildAgentSystemPrompt() injected every context file before the single system-prompt cache boundary.
• Missing detection / guardrail: prompt-shape tests checked that context files were present, but not that volatile workspace files stayed below the cache boundary.
• Contributing context (if known): the boundary rollout made this more visible because stable and dynamic prompt regions now matter more explicitly for Anthropic-family caching.

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/system-prompt.test.ts
• Scenario the test should lock in: stable workspace files render before SYSTEM_PROMPT_CACHE_BOUNDARY, while HEARTBEAT.md renders after it.
• Why this is the smallest reliable guardrail: the bug is in prompt assembly order, so prompt-shape unit coverage is the direct seam.
• Existing test that already covers this (if any): none specific to stable-vs-dynamic context ordering.
• If no new test is added, why not: N/A.

User-visible / Behavior Changes

Stable workspace project-context files keep a longer reusable cache prefix, while HEARTBEAT.md no longer invalidates that prefix every turn.

Diagram (if applicable)

Before:
[AGENTS][SOUL][TOOLS][IDENTITY][USER][HEARTBEAT][BOOTSTRAP][MEMORY][CACHE BOUNDARY][dynamic extras]

After:
[AGENTS][SOUL][IDENTITY][USER][TOOLS][BOOTSTRAP][MEMORY][CACHE BOUNDARY][HEARTBEAT][dynamic extras]

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)
• If any Yes, explain risk + mitigation:

Repro + Verification

Environment

• OS: macOS
• Runtime/container: local OpenClaw workspace
• Model/provider: prompt assembly only
• Integration/channel (if any): N/A
• Relevant config (redacted): default local test config

Steps

1. Build a system prompt with stable context files plus HEARTBEAT.md.
2. Inspect prompt ordering around SYSTEM_PROMPT_CACHE_BOUNDARY.
3. Confirm stable files stay above the boundary and HEARTBEAT.md lands below it.

Expected

• Stable project-context prefix remains reusable across heartbeat churn.

Actual

• This branch keeps stable files before the boundary and places HEARTBEAT.md after it.

Evidence

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

Human Verification (required)

• Verified scenarios: touched-file lint/format checks; direct prompt-shape sanity check confirming stable files precede the cache boundary and HEARTBEAT.md follows it.
• Edge cases checked: heartbeat-only context still renders correctly under the regular project-context heading.
• What you did not verify: a trustworthy local pnpm test -- src/agents/system-prompt.test.ts run, because the wrapper pulled in an unrelated current-main plugin-sdk-package-contract-guardrails failure.

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)
• Config/env changes? (No)
• Migration needed? (No)
• If yes, exact upgrade steps:

Risks and Mitigations

• Risk: some users may implicitly rely on the old project-context ordering.
  • Mitigation: the change is limited to stable-vs-dynamic ordering of known workspace files, and tests lock the new prompt shape.

Changed files

• CHANGELOG.md (modified, +1/-0)
• src/agents/system-prompt.test.ts (modified, +49/-0)
• src/agents/system-prompt.ts (modified, +94/-21)