Codex process recovery

How OpenClaw cleans up Codex app-server children after model discovery times out or the Gateway stops. Part of the Codex harness runtime guide; Where each section moved lists every section.

Timed-out model discovery

If a written discovery request reaches its deadline without a response, OpenClaw retires that shared client. Other active leases finish before its process closes; future discovery uses a new client. Successful discovery remains reusable.

Recovery after a hard Gateway stop

On POSIX systems, OpenClaw checks for registered orphaned Codex app-server processes before spawning each fresh stdio child. Gateway startup also runs a best-effort background sweep; the before-spawn check remains authoritative. OpenClaw records the parent and child process identities in the current state directory's SQLite plugin store before sending Codex initialize, so a child cannot start a native turn before its registration is durable.

Cleanup only targets a registered child whose original OpenClaw parent is no longer running. It checks process IDs, start times, and process groups before terminating the orphan and its discoverable descendants. When recorded, a fingerprint of the child command line must also match the live process before signaling; the durable registration stores only that digest, never the raw arguments. Another live OpenClaw instance, processes registered under another state directory, and externally managed WebSocket or Unix-socket app-servers are left alone. These portable process checks do not provide an atomic operating-system ownership guarantee or discover descendants that independently reparented before inspection.

Linux reads process identities directly from /proc, including the boot ID and process start ticks, so Alpine/BusyBox installations do not need procps. These asynchronous reads do not launch helper processes or block the Gateway while reading another process. If filesystem workers are saturated, inspection still fails at its deadline; retry once the host is responsive. Startup identity and command inspection share a 10-second deadline. During Linux startup, an empty command line waits within that deadline while the same live process identity remains valid. Registration still requires a usable command fingerprint; unreadable or changed identities fail. macOS uses its native ps with a fixed locale and timezone. Registration checks inspect only the observer and the relevant parent and child processes; an unrelated unreadable process does not block those checks. Destructive cleanup still requires full process-tree inspection and fresh identity checks before signaling.

If a required process cannot be inspected or bounded cleanup cannot confirm that the registered orphan is gone, the new stdio connection fails instead of spawning another child. Follow the reported reason: a deadline failure calls for checking host load and Gateway logs, while an access-denied failure calls for checking /proc access on Linux or ps permissions on macOS. Other inspection failures require checking that the process-inspection facility is available and returning usable data. Do not broaden permissions to address a timeout. If cleanup cannot stop a verified orphan, inspect and stop that process before retrying. If the cleanup budget expires, retry to finish the remaining registrations.

This recovery requires a spawn-time registration. It does not discover unregistered children left by an older OpenClaw version or scan command names to infer ownership. Windows has no equivalent orphan registration or recovery.