Gateway: legacy context engine never registered at boot → transcript persistence silently fails for runner: cli sessions

Summary

In OpenClaw 2026.5.6, the built-in legacy context engine is only registered as a side-effect of importing subagent-spawn, pi-embedded, or subagent-registry.runtime. The main gateway boot path does not import any of those modules, so on any gateway start where the first agent activity is a runner: cli request, ensureContextEnginesInitialized() is never called and the engine map stays empty.

When agent-command then tries to persist the CLI transcript, resolveContextEngine("legacy") throws (registry.ts:253 — the requested engine is the default, so there is no fallback), the error is caught and warned, and the transcript is silently dropped. sessions.json records a sessionFile path that is never written to disk, and sessions_history returns empty for that key on the next turn — so every subsequent message starts a fresh CLI session with no resumed context.

The bug is deterministic under that ordering: a clean systemctl --user restart openclaw-gateway reproduces it 100% if the first turn is a runner: cli agent run. A full machine reboot only "fixes" it because under the warmer post-reboot startup the first agent turn happens to take the runner: embedded path, which loads pi-embedded.js and triggers the init side-effect.

Environment

• OpenClaw 2026.5.6 (commit c97b9f7) installed via npm i -g openclaw
• Node 18+, Linux (Debian-like)
• Gateway run under user systemd: openclaw-gateway.service
• Reproduced on a production host; same code present in published npm tarball

Reproduction

# 1. Restart the gateway cleanly
systemctl --user restart openclaw-gateway.service

# 2. Wait for it to be active
systemctl --user is-active openclaw-gateway.service   # → active

# 3. Fire a single agent turn that lands on the cli runner
openclaw agent --agent main -m "ping" --thinking off --json
#    (look for "runner": "cli" in the executionTrace)

# 4. Check the journal
journalctl --user -u openclaw-gateway.service --since "1 minute ago" \
  | grep -E 'context engine|persistence'

Expected: transcript is persisted to ~/.openclaw/agents/main/sessions/<sid>.jsonl.

Actual:

[agents/agent-command] CLI transcript persistence failed for agent:main:main:
  Context engine "legacy" is not registered. Available engines: (none)

No file is written to the path stored in sessions.json under sessionFile. Subsequent agent turns log cli session reset: reason=missing-transcript and start fresh.

Evidence

Journal (verbatim, redacted)

May 07 16:39:26 [agents/agent-command] CLI transcript persistence failed
  for agent:main:explicit:pipeline-classifier:
  Context engine "legacy" is not registered. Available engines: (none)

May 07 18:37:42 [agent/cli-backend] cli session reset:
  provider=claude-cli reason=missing-transcript
May 07 19:45:43 [agent/cli-backend] cli session reset:
  provider=claude-cli reason=missing-transcript
May 07 20:41:14 [agent/cli-backend] cli session reset:
  provider=claude-cli reason=missing-transcript

Filesystem

sessions.json for the affected session key contained:

{
  "sessionFile": "/home/edith/.openclaw/agents/main/sessions/66695fc2-….jsonl",
  "claudeCliSessionId": "038eba44-…"
}

But 66695fc2-….jsonl did not exist on disk; meanwhile claude-cli's own jsonl at ~/.claude/projects/.../038eba44-….jsonl had 58 turns of real content. So the data exists; only the OpenClaw-side persistence step failed.

Code paths

registerContextEngineForOwner("legacy", …) is called exactly once in the package — from src/context-engine/init.ts → ensureContextEnginesInitialized():

// dist/init-CslInz0x.js
function registerLegacyContextEngine() {
  registerContextEngineForOwner(
    "legacy",
    async () => new LegacyContextEngine(),
    "core",
    { allowSameOwnerRefresh: true }
  );
}
let initialized = false;
function ensureContextEnginesInitialized() {
  if (initialized) return;
  initialized = true;
  registerLegacyContextEngine();
}

grep -rn "ensureContextEnginesInitialized\b" dist/ shows the only call sites are inside lazily-loaded modules:

dist/subagent-registry-CSyDa4Jl.js:1368
dist/subagent-spawn-NfQX5n3V.js:464
dist/pi-embedded-CM_pfO4f.js:86
dist/pi-embedded-CM_pfO4f.js:2064

None of these are imported on the gateway main boot path. agent-command — which is the module that hits the persistence error — does not import any of them either; it calls persistSessionEntry$1 from attempt-execution.shared.js which calls resolveContextEngine directly.

So unless one of the lazy importers happens to load before the first transcript-persist call, the engine map is empty and persistence fails.

Suggested fix

Make the init eager. One option: call ensureContextEnginesInitialized() from the gateway entry point (gateway/index.ts or wherever the main boot sequence lives), right after plugin loading completes and before any agent request can be served. Alternatively, register the legacy engine directly in registry.ts module init, since it's the documented default fallback.

A one-line side-effect import on the boot path would also do it:

// somewhere in the gateway boot module
import "./context-engine/init.js";   // forces registerLegacyContextEngine()

Workaround for affected users

Until a release with the fix lands:

1. Restart the gateway, then immediately fire a runner: embedded agent turn (not a runner: cli one) — e.g. an agent that prefers an OpenAI/Anthropic embedded provider over claude-cli. That loads pi-embedded.js and triggers the init side-effect.
2. Or hot-patch the gateway entry to side-effect-import ./context-engine/init.js (or one of the modules that does).

A full machine reboot may "fix" it apparently because of which code path runs first post-boot — but it's a race; a subsequent gateway restart can put it back into the broken state.

Why this surfaced as "ShieldCortex broke my agent"

Several ShieldCortex installs that include shieldcortex setup end up restarting the OpenClaw gateway (to register MCP/hooks). After the restart, this race kicks in. ShieldCortex itself doesn't touch context-engine registration — its hooks load cleanly (6 internal hook handlers in the journal). The correlation is real but the cause is upstream.