Summary

ACP sessions reported agentRuntime.id: "auto" (post-02fe0d8978) — which is also wrong, since they aren't routed via the auto runtime; they're driven by acpx. Add a session-key-aware overlay applied at the production resolver so ACP-keyed rows report { id: "acpx", source: "session-key" }. Closes catalog #18.

Bug detail

Running openclaw sessions --all-agents --json against the deployed container produced (excerpt, redacted UUIDs):

{
  "key": "agent:copilot:acp:86b7b5af-…",
  "agentId": "copilot",
  "agentRuntime": { "id": "auto", "source": "implicit" },
  "kind": "direct"
}

The :acp: segment unambiguously marks an ACP session, yet the JSON labels it as runtime "auto". The original catalog finding documented "pi", but commit 02fe0d8978 ("Keep OpenAI Codex migrations on automatic runtime routing") had already shifted the unrecognized-model default from "pi" to "auto" before this PR was opened. The remaining bug — the production path returning the wrong runtime identifier for ACP sessions — is what this PR addresses.

How to reproduce

Live repro before fix (deployed container, OpenClaw 2026.5.6):

docker exec codeclaw-openclaw openclaw sessions --all-agents --json \
  | jq -c '.sessions[] | select(.key | startswith("agent:copilot:acp:")) | .agentRuntime'
{"id":"auto","source":"implicit"}
{"id":"auto","source":"implicit"}
{"id":"auto","source":"implicit"}
…

7/7 ACP sessions report auto/implicit.

Unit-level:

git checkout 4195dd0bf6            # red-test cherry-pick
pnpm test src/commands/sessions.acp-runtime-metadata.test.ts
# Before fix: 2 RED (resolveModelAgentRuntimeMetadata returns "auto" for ACP sessions; should be "acpx")
# After fix commits 6860ee0385 + 952afa3114: all 3 GREEN

Root cause

The 6 production emit sites all call resolveModelAgentRuntimeMetadata(...), which had zero session-key awareness — it routed off model identity / config policy only. ACP sessions, having no special model identity, fell into the post-02fe0d8978 default of "auto".

Fix approach

Caller-side overlay. Keeps the resolver pure; aligns with the same pattern PR 7 (catalog #20) uses for the model / modelProvider columns:

1. NEW src/agents/acp-runtime-overlay.ts — exports applyAcpRuntimeOverlay(meta, sessionKey). When isAcpSessionKey(sessionKey) is true, returns { id: "acpx", source: "session-key" }; otherwise returns meta unchanged.
2. Extends AgentRuntimeMetadata.source union with "session-key". Two downstream type unions (GatewayAgentRuntime.source, AgentListEntry.agentRuntime.source) needed the same | "session-key" addition for type compatibility — included as additive type-propagation.
3. resolveModelAgentRuntimeMetadata calls the overlay with the session key. The 6 emit sites all already call this resolver and inherit the fix automatically — no per-call-site change needed.
4. resolveAgentRuntimeMetadata left untouched as the 02fe0d8978 stub. The original implementation attempted to revert that contributor's intentional refactor (which had stubbed resolveAgentRuntimeMetadata to return { id: "auto", source: "implicit" }); after review, the stub-revert was undone in cleanup commit 952afa3114 to respect the upstream direction. Production already routes through resolveModelAgentRuntimeMetadata, where the overlay correctly applies.

Tests

• Red test (now GREEN): src/commands/sessions.acp-runtime-metadata.test.ts — 3 cases:
  • ACP session id is not "auto" (the post-02fe0d8978 default) — overlay must take precedence
  • ACP session id is "acpx" — overlay sentinel
  • Non-ACP session does NOT receive the "acpx" sentinel (control)
• Adjacent suite: src/commands/ (vitest.commands.config.ts shard) — passing.
• Cleanup commit (952afa3114): reverted the unauthorized stub-restoration, kept the production overlay, retargeted the test at resolveModelAgentRuntimeMetadata.

Catalog reference

Catalog finding: #18. Investigation lives in branch edpiva/acp-native-session-investigation (not yet upstream) at docs/plans/2026-05-08-acp-findings-catalog.md.

Verification commands

pnpm test src/commands/sessions.acp-runtime-metadata.test.ts   # 3/3 GREEN
pnpm exec vitest run --config test/vitest/vitest.commands.config.ts src/commands/   # passes

Updates

Bot feedback addressed (P2, commit d4a6eb0b92): the overlay now reads entry.acp.backend instead of hard-coding "acpx". When a session entry carries an explicit acp.backend (configurable ACP backend, binding/agent override, or persisted entry.acp.backend), that value is used as the runtime id. Fallback to "acpx" only when no backend is set on the entry. acpBackend is threaded from call sites that have the session entry in scope (sessions.ts, session-utils.ts, server-methods/sessions.ts, status.summary.runtime.ts); call sites without an entry in scope (agents-list-tool.ts, session-utils.ts agent-list path, doctor-claude-cli.ts) continue to receive the "acpx" fallback. Two new test cases added: one proving a custom backend is reported, one proving the fallback fires when no backend is set. All 5 test cases green.

Notes for reviewers

• The original catalog framing of "pi" is stale — 02fe0d8978 shifted unrecognized-model default to "auto". The actual production-path bug is the ACP runtime not being identified at all; this PR fixes that without touching resolveAgentRuntimeMetadata's stub.
• The two downstream type-union edits (src/shared/session-types.ts, src/agents/tools/agents-list-tool.ts) add | "session-key" to keep the gateway/tools row types compatible with the new source variant. Additive only.
• The new acp-runtime-overlay.ts helper is reused by PR 7 (catalog Heartbeat skipped when last inbound message is from a group chat #20 — model/modelProvider ACP-aware), which currently inlines the equivalent logic awaiting this PR. After both land, PR 7 can be slimmed via a small follow-up to import from this file.

Real behavior proof

Behavior addressed: ACP control-plane rows from openclaw sessions --json, status, and Gateway session RPC metadata now report ACP runtime metadata from persisted ACP session metadata/backend instead of the implicit model runtime. ACP-shaped bridge rows without entry.acp are not overlaid.

Real environment tested: Maintainer Linux worktree at PR SHA 4ebbf1d7e9242924df520cdaefd1f2e3bedc91dc, rebased on upstream/main 97ed9b2d82950dd64b94c4fd1ac732e701b54a24. Earlier Azure Crabbox seeded-session proof for the original runtime overlay ran on amber-lobster / cbx_4c7c7efb6dc7; the new bridge guard was verified locally after the rebase fix.

Exact steps or command run after this patch: Seeded a temp OPENCLAW_CONFIG_PATH and explicit session store with an ACP control-plane row carrying entry.acp.backend = "acpx", an ACP-shaped bridge row with no entry.acp, and a non-ACP control row, then ran:

OPENCLAW_CONFIG_PATH="$proof_dir/openclaw.json" OPENCLAW_HOME="$proof_dir/home" pnpm --silent openclaw sessions --store "$proof_dir/sessions.json" --json

pnpm test src/commands/sessions.acp-runtime-metadata.test.ts src/commands/sessions.acp-model-display.test.ts -- --reporter=verbose
pnpm tsgo:core
pnpm tsgo:core:test
pnpm exec oxfmt --check --threads=1 src/agents/acp-runtime-overlay.ts src/agents/agent-runtime-metadata.ts src/commands/sessions.acp-runtime-metadata.test.ts src/commands/sessions.ts src/commands/status.summary.runtime.ts src/gateway/session-utils.ts src/gateway/server-methods/sessions.ts
git diff --check upstream/main...HEAD

Evidence after fix: Copied terminal output from the after-fix CLI run and focused tests:

AFTER_FIX_ACP_AGENT_RUNTIME={"id":"acpx","source":"session-key"}
CONTROL_ACP_BRIDGE_AGENT_RUNTIME={"id":"auto","source":"implicit"}
CONTROL_NON_ACP_AGENT_RUNTIME={"id":"auto","source":"implicit"}
AFTER_FIX_ACP_SESSION_ROW={"key":"agent:copilot:acp:proof-79550","agentId":"copilot","kind":"direct","modelProvider":"acpx","model":"copilot-acp","agentRuntime":{"id":"acpx","source":"session-key"}}
CONTROL_ACP_BRIDGE_SESSION_ROW={"key":"agent:copilot:acp:bridge-proof-79550","modelProvider":"microsoft-foundry","model":"gpt-5.3-codex","agentRuntime":{"id":"auto","source":"implicit"}}
src/commands/sessions.acp-runtime-metadata.test.ts: 6/6 tests passed
src/commands/sessions.acp-model-display.test.ts: 4/4 tests passed
pnpm tsgo:core: passed
pnpm tsgo:core:test: passed
oxfmt touched-file check: passed
git diff --check upstream/main...HEAD: passed

Observed result after fix: The ACP control-plane session row reports agentRuntime.id: "acpx" and source: "session-key"; the ACP-shaped bridge row keeps modelProvider: "microsoft-foundry", model: "gpt-5.3-codex", and normal implicit runtime metadata, so key shape alone no longer triggers the ACP runtime overlay.

What was not tested: No live ACP provider/harness turn with external credentials was run after the maintainer rebase fix; this was seeded session-store CLI proof plus focused regression/type/format checks.