Summary

sessions_spawn(runtime="acp", ...) returns session identifiers such as childSessionKey / sessionKey, but does not expose the OS process PID(s) for the spawned ACP adapter / child agent process. When the child appears stuck, is still running, or has empty projected history, operators have no first-class way to correlate the OpenClaw session with the process that must be inspected or terminated.

This is related to #68916, but narrower: #68916 covers orphaned ACP processes and cleanup on completion/reset. This issue is about the missing observability/control surface while a sessions_spawn child is still running.

Environment

• OpenClaw: 2026.4.27 (cbc2ba0)
• Install: npm global
• OS: Linux
• Gateway: systemd user service
• ACP backend: bundled acpx
• Observed with ACP child sessions; most relevant for agentId: "claude" / agentId: "codex" style runs

Steps to reproduce

1. Spawn an ACP child session from a parent conversation, for example:

{
  "runtime": "acp",
  "agentId": "claude",
  "mode": "run",
  "task": "<long-running task>"
}

1. Observe the sessions_spawn response. It provides session-level identifiers, but no OS PID / process handle metadata.
2. While the task is running or appears stuck, inspect available session APIs such as sessions_list, sessions_history, and session_status.
3. Attempt to correlate the child session with live OS processes (claude-agent-acp, claude, codex-acp, etc.).

Expected behavior

For spawned sessions that create local child processes, OpenClaw should expose enough process metadata to correlate and debug the run. For example, one or more of:

• pid / pids in the sessions_spawn response when available
• persisted process metadata in the child session record
• session_status showing adapter PID and child agent PID while running
• a first-class sessions_kill / sessions_close path that can target the stored process handle without requiring manual ps matching

If a PID is unavailable for a backend, the response should explicitly say so rather than silently omitting it.

Actual behavior

The spawn result exposes logical session identifiers but no process PID. When the child appears to be running, hung, orphaned, or projected as empty by sessions_history, there is no reliable way to map:

childSessionKey -> ACP adapter process PID -> child agent process PID

Operators are forced to use manual process-table heuristics, timestamps, command-line matching, or gateway logs. That is brittle when multiple ACP sessions are active.

Impact

• Makes stuck ACP sessions hard to diagnose.
• Makes cleanup risky because manual kill commands can target the wrong process.
• Makes related empty-history / orphan-process bugs harder to investigate.
• Prevents automation from safely detecting and remediating runaway spawned sessions.

Related issues

• #51328: ACP session transcript exists but session APIs may return empty history.
• #68916: ACP oneshot sessions leave orphaned processes and parent reset does not clean child ACP sessions.
• #66465: persistent ACPX subprocess stderr logs would help post-mortem debugging, but PID/session correlation is still needed.