Bug type

Behavior bug (incorrect output/state without crash)

Beta release blocker

No

Summary

On the first Discord inbound that resolves to a type: "acp" configured binding, the gateway silently suspends inside await conversationRuntime.ensureConfiguredBindingRouteReady(...) in the Discord preflight handler. No error, no timeout, no subprocess spawn, no further log output. The event loop goes idle in kevent() with zero pending JS frames — every async chain kicked off by the inbound has landed on a Promise that never settles. Discord gateway heartbeats and other channels continue to work; only this one dispatch path is dead. Reproducible 100% of the time on fresh gateway boots.

Steps to reproduce

1. npm install -g openclaw (tested on 2026.4.14 and 2026.4.15).
2. Configure a Discord channel binding of type: "acp" pointing to an agent. Crucially, the agent's agents.list[*].runtime block is unset (no explicit runtime: { type: "acp", ... }). The acpx plugin has a per-agent override set in plugins.entries.acpx.config.agents.<agent>.command. Abridged config:

// openclaw.json
{
  "agents": { "list": [
    { "name": "my-agent" /* no runtime block */ }
  ]},
  "plugins": { "entries": { "acpx": { "config": {
    "cwd": "/abs/override",
    "agents": {
      "my-agent": { "command": "npx -y @agentclientprotocol/claude-agent-acp@^0.25.0" }
    }
  }}}},
  "channels": { "discord": { "guilds": [{
    "id": "…",
    "channels": { "…": { "binding": { "type": "acp", "agent": "my-agent" } } }
  }]}}
}

1. Start the gateway. Confirm [plugins] embedded acpx runtime backend ready appears in the gateway log (backend is healthy).
2. Send a message in the Discord channel bound in step 2.
3. Watch the gateway log — the preflight runs through the channel-allowed checks and then stops emitting. No [discord-preflight] success: …, no discord: configured ACP binding unavailable …, no subprocess spawn in ps, no state directory created by FileSessionStore.
4. sample <gateway-pid> during the hang shows 2242/2251 samples parked in uv_run → uv__io_poll → kevent. Event loop has nothing to do — all JS is parked on pending Promises.

Minimal probe showing the code path itself works:

The same call chain completes cleanly in ~540ms when run in a fresh Node process loading the installed bundle:

// Minimal repro — uses the real AcpxRuntime
const { n: resolveConfiguredBinding }          = await import(`${dist}/binding-registry-CUcd4-sZ.js`);
const { t: ensureConfiguredBindingRouteReady } = await import(`${dist}/binding-routing-ClFjxSCF.js`);
// … construct cfg, register acpx backend …
const res = resolveConfiguredBinding({
  cfg,
  conversation: { channel: "discord", accountId: "default", conversationId: "…" },
});
const ensured = await ensureConfiguredBindingRouteReady({ cfg, bindingResolution: res });
// returns { ok: false, error: "spawn my-agent ENOENT" } in ~540ms

So the code path is not broken in isolation — the hang is state-specific to the running gateway process.

Expected behavior

After the [discord-preflight] shouldRequireMention=… wasMentioned=… log line, exactly one of the following should emit within a bounded time:

• [discord-preflight] success: route=<agent> sessionKey=… — happy path; subprocess spawns, reply dispatch runs.
• discord: configured ACP binding unavailable … — failure path; error surfaces and the inbound is rejected cleanly.

Either way, the gateway should NOT silently park forever. A bounded timeout with an error log would be a floor-level safety net for this class of bug.

Actual behavior

Neither outcome log fires. The preflight stops emitting immediately after wasMentioned=…. No subprocess is spawned (ps shows no claude-agent-acp/openclaw-acp/codex-acp children). No FileSessionStore state directory is created. The gateway's V8 isolate is idle — sample <pid> shows essentially 100% of samples in kevent, zero JS frames pending. Other gateway work (heartbeats, other channels) continues to run normally.

OpenClaw version

2026.4.14 AND 2026.4.15 — bug reproduces identically on both. The 2026.4.15 upgrade was tried as a hypothesized fix; it is not a fix.

Operating system

macOS 26.4 (arm64)

Install method

Global npm: npm install -g openclaw. Binary symlinked at /opt/homebrew/bin/openclaw. Node.js: v24.14.1.

Model

anthropic/claude-sonnet-4-6 — note: model is not relevant to this bug; the hang occurs before any model invocation or subprocess spawn.

Provider / routing chain

• Provider: Anthropic - Channel provider: Discord (1 bot, 1 guild, 1 channel bound) - Routing: Discord inbound → preflight channel-allowed check → resolveConfiguredBinding (works; matches correctly) → ensureConfiguredBindingRouteReady (hangs here) → (would be) ensureConfiguredAcpBindingSession → acpManager.initializeSession → runtime.ensureSession (acpx) → FileSessionStore.load → ensureDir → subprocess spawn. - Other channels (Telegram) work normally on the same gateway, same process, same config version.

Additional provider/model setup details

Not relevant to the bug — hang occurs before any auth/model path is exercised (before subprocess spawn). For completeness: both anthropic:default (api_key) and anthropic:claude-cli (CLI OAuth) profiles are present in auth-profiles.json; the api_key profile was the active default during reproductions.

Logs, screenshots, and evidence

### Gateway log trace around the hang

[discord-preflight] channelId=… channelType=0 isGuild=true
[routing] resolveAgentRoute: … bindings=0    ← red herring; see note below
[discord-preflight] pass: channel allowed
discord: inbound id=… channel=… mention=no content=yes
[discord-preflight] shouldRequireMention=false … wasMentioned=false
<<< silence — nothing else on the dispatch path is ever emitted >>>

**Red-herring note:** `bindings=0` from `[routing] resolveAgentRoute` is NOT the cause. `listRouteBindings` intentionally filters out `type: "acp"` bindings; the ACP binding path uses a separate registry (`listConfiguredBindings`) which correctly sees all configured bindings.

### `sample` trace during the hang

2251 Thread_… DispatchQueue_1: com.apple.main-thread (serial)

2243 uv_run
! 2242 uv__io_poll
! :  2242 kevent
7   uv__run_check

Zero JS application frames. Event loop is idle; every Promise created by the inbound is still pending.

### Bypass / smoking gun

Pre-seeding the session store with a minimal `.acp` metadata record under the ACP session key makes the gateway **skip** the hang:


// ~/.openclaw/agents/my-agent/sessions/sessions.json
{
  "agent:my-agent:discord:channel:…": { /* real entry, unchanged */ },

  "agent:my-agent:acp:binding:discord:default:<hash>": {
    "acp": {
      "backend": "acpx",
      "agent": "my-agent",
      "runtimeSessionName": "test",
      "identity": {
        "state": "pending",
        "acpxRecordId": "test-record",
        "acpxSessionId": "test-bsid",
        "agentSessionId": "test-asid",
        "source": "ensure",
        "lastUpdatedAt": 1776561874172
      },
      "mode": "persistent",
      "runtimeOptions": { "cwd": "/abs/workspace/my-agent" },
      "cwd": "/abs/workspace/my-agent",
      "state": "idle",
      "lastActivityAt": 1776561874172
    },
    "sessionId": "<uuid>",
    "updatedAt": 1776561874172
  }
}


With this pre-seeded record, the first Discord inbound after gateway boot immediately logs:

[discord-preflight] success: route=my-agent sessionKey=agent:my-agent:acp:binding:discord:default:<hash>
[hooks] running reply_dispatch (1 handlers, first-claim wins)

This narrows the hang to `ensureConfiguredAcpBindingSession` (`persistent-bindings.lifecycle-DmrH1JJ1.js` around lines 35–80) — specifically the chain `acpManager.initializeSession` → `runtime.ensureSession` → lazy init of the stateful-target driver (candidate: `ensureStatefulTargetBuiltinsRegistered`'s `builtinsRegisteredPromise`).

The same pre-seeding also reveals a **second** hang: after `reply_dispatch` fires, the agent runner never spawns the ACP subprocess, and the event loop goes idle again with the same `kevent`-only signature. This strongly suggests the root cause is generic: *any* first-call to the ACP runtime/session machinery from inside the Discord handler's async context pends forever.

Impact and severity

Severity: high for affected users. Any agent configured with a type: "acp" Discord binding is completely unreachable from Discord after gateway boot. Reproducible 100% of the time on fresh boots.

No workaround exists at user-config level: the session-store pre-seeding described above gets past the first hang but hits an identical second hang one layer deeper (no subprocess spawn, same idle signature).

Telegram and other non-Discord channel providers on the same gateway are unaffected. Configurations where agents have an explicit runtime: { type: "acp", ... } block in agents.list[*] may or may not be affected — NOT_ENOUGH_INFO; only the runtime-unset case was tested.

Scope of affected users: NOT_ENOUGH_INFO. Requires the specific combination of (Discord channel binding with type: "acp") + (agent with unset runtime block) + (acpx per-agent command override). Not an exotic configuration.

Additional information

Hypothesis

A global singleton in the stateful-target ACP driver captures a Promise on its first invocation. When that first invocation happens from inside the Discord handler's async context (with whatever abort-signal / async-local-storage / logger injection it carries), something about the capture prevents the Promise from ever settling. Every subsequent caller then awaits the same stuck Promise. The bypass above supports this: pre-seeding the session record lets the code path short-circuit before ever awaiting the stuck singleton.

Candidates

• ensureStatefulTargetBuiltinsRegistered's builtinsRegisteredPromise (first-call-only lazy init in the stateful-target registration chain).
• A cache keyed by the cfg object (compiledRegistryCache or similar).
• An abort-signal propagation issue between the Discord plugin and the acpx runtime.

Things ruled out during debugging

• Binding compilation — works (primeConfiguredBindingRegistry(cfg) returns positive binding/channel counts; resolveConfiguredBinding matches correctly).
• ACP adapter — works ([email protected] installed globally, responds to initialize when spawned manually).
• openclaw acp bridge — works in isolation.
• Spawn command value — tried three variants ("openclaw acp", no override, "npx -y @agentclientprotocol/claude-agent-acp@^0.25.0"); all produce the identical silent hang, including the no-override case which should fail immediately with ENOENT — it doesn't, meaning we never reach the spawn call.
• Session store file locks / lock-file contention.
• Actor-queue backpressure (gateway restarted cleanly many times, first inbound always hangs).

Ask

1. Confirm whether ensureStatefulTargetBuiltinsRegistered (or any equivalent lazy init in the ACP driver chain) is the stuck singleton.
2. If it is, shift the init to gateway boot or make it re-entrant-safe across async contexts.
3. Consider adding a timeout-with-log to ensureConfiguredBindingRouteReady so future occurrences of this class of bug surface as an error instead of silent idleness.

Happy to test any patch against this reproducer.