Summary

• Problem: sessions.list can become CPU- and memory-heavy on large session stores because it repeatedly deep-clones large cached session data, returns oversized compaction checkpoint summaries, repeatedly scans transcripts for usage fallback data, and performs repeated subagent child/link lookups per row.
• Why it matters: The Control UI and local list-sessions paths poll sessions.list; large transcripts/checkpoints can make polling expensive enough to spike CPU or exhaust memory.
• What changed: Added a sessions.list-specific session-store loader that can reuse a validated cached store object without full deep cloning, returns a minimal latest compaction checkpoint preview, caches transcript usage snapshots by transcript stat, and builds request-local subagent/store indexes for list row construction.
• What did NOT change (scope boundary): No session mutation behavior, transcript format, compaction behavior, model routing, or external API behavior was changed.

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 #
• Related #
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: sessions.list used general-purpose session-store and subagent lookup paths optimized for correctness and defensive isolation, but not for repeated high-volume list rendering. Large checkpoint summaries and transcript usage fallback scans amplified the cost.
• Missing detection / guardrail: No perf/regression coverage around large session stores with compaction checkpoints, many subagent links, and transcript usage fallback reads.
• Contributing context (if known): Control UI polling repeatedly exercises this path, so even moderate per-call overhead becomes noticeable.

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/gateway/session-utils.subagent.test.ts
  • src/gateway/session-utils.fs.test.ts
  • sessions.list handler tests under src/gateway/server-methods/
• Scenario the test should lock in:
  • sessions.list builds subagent child relationships using request-local indexes without changing stale/live child-link semantics.
  • transcript usage fallback returns cached snapshots when transcript size/mtime has not changed.
  • latest compaction checkpoint in list rows omits the heavyweight summary payload.
• Why this is the smallest reliable guardrail: These are the narrow gateway paths that caused the observed CPU/memory pressure.
• Existing test that already covers this (if any): Existing subagent metadata tests cover most child-link semantics; targeted tests were run against the changed files.
• If no new test is added, why not: Existing coverage already exercises the critical behavior; this PR primarily changes implementation/performance characteristics.

User-visible / Behavior Changes

sessions.list responses now include only a minimal latestCompactionCheckpoint preview (checkpointId, createdAt, reason) instead of returning the full checkpoint object with large summary data.

Diagram (if applicable)

Before:
Control UI poll -> sessions.list -> deep clone store + per-row subagent scans + transcript scans + full checkpoint summary

After:
Control UI poll -> sessions.list -> validated cache reuse + request-local indexes + stat-keyed transcript usage cache + checkpoint preview

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: N/A

Repro + Verification

Environment

• OS: Linux
• Runtime/container: OpenClaw source checkout based on release/2026.4.29
• Model/provider: N/A
• Integration/channel (if any): Control UI / gateway sessions.list path
• Relevant config (redacted): N/A

Steps

1. Create or use a session store with many sessions/subagent relationships and compaction checkpoints.
2. Trigger sessions.list via gateway/Control UI polling.
3. Observe CPU/memory pressure before the fix; compare with the request-local cache/index behavior after the fix.

Expected

• sessions.list remains responsive and avoids repeated heavyweight cloning/scanning work.
• Existing subagent child-link semantics are preserved.
• Large checkpoint summary payloads are not returned in list rows.

Actual

• Before: repeated list calls can cause high CPU/memory pressure.
• After: sessions.list uses list-specific fast paths and preserves tested behavior.

Evidence

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

Targeted verification run:

OPENCLAW_VITEST_MAX_WORKERS=1 corepack pnpm exec vitest run \
  --config test/vitest/vitest.gateway.config.ts \
  src/gateway/session-utils.subagent.test.ts \
  src/gateway/session-utils.fs.test.ts \
  src/gateway/server-methods/sessions.send-followup-status.test.ts \
  src/gateway/server-methods/sessions.send-deleted-agent.test.ts

Test Files  4 passed (4)
Tests       80 passed (80)

Also verified:

git diff --check origin/release/2026.4.29...HEAD

No whitespace errors.

corepack pnpm tsgo:core was attempted locally but this checkout is missing UI dependencies (@noble/ed25519, dompurify, @vitest/browser-playwright), so it fails before providing a clean repo-wide type signal. The failures are unrelated to the changed session/gateway files.

Human Verification (required)

• Verified scenarios:
  • Existing subagent metadata tests pass with the request-local index path.
  • Transcript usage tests pass with stat-keyed caching.
  • sessions.list-related gateway handler smoke tests pass.
• Edge cases checked:
  • stale active subagent snapshots
  • ended parent with live descendant
  • moved child sessions
  • store-only child links
  • transcript usage fallback reads
• What you did not verify:
  • Full CI matrix
  • Real-world perf numbers from a production-sized session store

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, except latestCompactionCheckpoint list payload is intentionally narrowed to preview fields)
• Config/env changes? (No)
• Migration needed? (No)
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: The sessions.list-specific cache path returns the cached store object without cloning, so accidental mutation by list code would affect the cached object.
  • Mitigation: The sessions.list row construction path is read-only; tests exercise the relevant gateway behavior. Mutation paths continue to use the existing general loader.
• Risk: Narrowing latestCompactionCheckpoint could affect callers that depended on full checkpoint summaries from list rows.
  • Mitigation: The list endpoint should only expose a lightweight preview; full checkpoint data remains in the store/compaction paths.
• Risk: Request-local subagent indexes could diverge from existing lookup semantics.
  • Mitigation: Existing subagent metadata tests pass, including stale/moved child edge cases.

AI/Vibe-Coded PR Transparency

• AI-assisted
• Testing degree: targeted gateway tests passed; full local typecheck blocked by missing UI dependencies in this checkout.
• I understand what the code does: yes — this PR converts installed monkey-patch performance fixes into source-level changes and centralizes subagent read indexes for sessions.list.