Problem

Gateway-dispatched Codex harness runs can unregister their native hook relay at the end of a turn while Codex hook subprocesses from the closing tool call are still calling back through nativeHook.invoke. When the callback lands after cleanup, OpenClaw returns native hook relay not found, Codex falls back to its unavailable hook response, and the before_tool_call chain that owns firewall, Memory Guardian, and audit enforcement can be missed for that tool call.

This is independent of #73950's module-duplication fix. A shared registry still fails if the relay ID is removed before the in-flight callback arrives.

Change and value

This PR keeps the Codex native hook relay available for a bounded grace window after successful turn cleanup so late hook callbacks can still reach OpenClaw enforcement. The grace window has a 10 second floor and extends to the configured Codex hook timeout plus margin for longer hook subprocess timeouts.

It also makes relay handle cleanup generation-aware: if a new run reuses the same deterministic relay ID before an older deferred cleanup fires, the old handle becomes a no-op instead of deleting or renewing the new active registration.

The grace window is limited to fully successful turns. Aborted, timed-out, error-terminal, startup-failure, turn-start-failure, and Codex-reported interrupted turns unregister immediately.

Who is affected, and who is not

Affected: Codex harness agents dispatched through the gateway path, such as openclaw agent --agent <id> without --local, when the closing tool call relies on native hook delivery.

Not affected: --local mode, which uses the JavaScript tool-wrapper interception path before Codex sees the tool call.

Why now

The failure is reproducible on the current 2026.5.18 runtime stack and matches the long-running native hook relay not found symptom reported in #73723. ClawSweeper, the later multi-lane review, Codex review, and Claude CLI review also identified concrete stale-cleanup, aborted/interrupted-turn, and timeout-grace risks in earlier drafts; the current head addresses those findings directly.

Implementation

• Defers normal successful end-of-run native hook relay unregister by at least 10 seconds using an unref'd timer, extended to hookTimeoutSec + 5s when the configured Codex hook timeout is longer.
• Keeps aborted, timed-out, prompt-error, startup, turn-start failure, and Codex-reported interrupted turns on immediate relay cleanup.
• Tracks pending deferred unregisters for deterministic test cleanup.
• Changes NativeHookRelayRegistrationHandle.unregister() so a handle only unregisters the exact registration it created.
• Changes NativeHookRelayRegistrationHandle.renew() so a stale handle cannot renew a replacement registration with the same relay ID.
• Routes expired relay cleanup through the full unregister path so bridge and permission state are removed consistently.
• Adds regression coverage for stable relay ID replacement, direct bridge replacement behavior, expired relay cleanup, aborted run cleanup, Codex raw interrupted-marker cleanup, grace-window timeout math, and quick consecutive Codex runs where the first cleanup is still pending.

Verification

• Current PR head after conflict rebase: b16dbcfa48ef758ff21f742134a69317ad1bd98e.
• Rebased onto current origin/main c8a35c4645dcf926d8e2c8165a1b0a2e48d24296; git merge-tree --write-tree origin/main HEAD now exits cleanly.
• git diff --check origin/main...HEAD passed locally after the rebase.
• ./node_modules/.bin/oxfmt --check --threads=1 extensions/codex/src/app-server/run-attempt.ts extensions/codex/src/app-server/run-attempt.test.ts src/agents/harness/native-hook-relay.ts src/agents/harness/native-hook-relay.test.ts passed locally.
• timeout 120s ./node_modules/.bin/oxlint --tsconfig config/tsconfig/oxlint.core.json src/agents/harness/native-hook-relay.ts src/agents/harness/native-hook-relay.test.ts passed locally.
• timeout 120s ./node_modules/.bin/oxlint --tsconfig config/tsconfig/oxlint.extensions.json extensions/codex/src/app-server/run-attempt.ts extensions/codex/src/app-server/run-attempt.test.ts passed locally.
• Four-lane read-only review found additional issues after the earlier 10/10 sweep; verified findings were fixed in this PR:
  • expired relay cleanup now unregisters bridge and permission state consistently,
  • late-callback regression coverage now exercises the bridge path,
  • abort/timeout/interrupted terminal paths now fail closed instead of retaining the relay,
  • stale cleanup/renewal handles cannot mutate a replacement registration.
• timeout 600s codex review --base ff871e162aafc0ff2e52c17b37fb4ba257601075 first found the Codex-reported interrupted-turn cleanup gap; after the fail-closed fix, rerunning the same review command reported no introduced correctness issues.
• Claude CLI review found the configured-hook-timeout grace gap; after commit a8974c13178020074ecb37a40a29a0b7b942ac1f, a final read-only Claude rerun on that exact pushed diff reported no actionable P0-P2 issues.
• Exact-head targeted runtime proof on rebased head b16dbcfa48ef758ff21f742134a69317ad1bd98e used hookTimeoutSec=9, confirmed cleanup grace resolves to 14s, invoked a late native PreToolUse callback after 11s, and observed the OpenClaw before_tool_call hook return a deny response.
• Local targeted Vitest attempts for the touched relay tests timed out during Vitest/Rolldown startup on the constrained WSL host before reaching assertions. No assertion failure was observed locally. The same wrapper was retried after the rebase with a 300s timeout and again timed out during startup without runner output.
• Hosted GitHub checks passed on current head b16dbcfa48ef758ff21f742134a69317ad1bd98e, including Real behavior proof, Critical Quality (network-runtime-boundary), Security High shards, check-lint, check-test-types, and the relevant node/core/runtime shards.

Real behavior proof

Behavior addressed: Codex native hook relay cleanup could run before late hook callbacks from the closing tool call reached OpenClaw, causing before_tool_call enforcement to be skipped. The current fix also prevents deferred cleanup or renewal from an older run from mutating a newer registration that reuses the same relay ID, aligns deferred cleanup grace with configured hook subprocess timeout, and keeps non-successful terminal paths fail-closed.

Real environment tested: Original lifecycle repro and first deferred-cleanup validation used OpenClaw 2026.5.18 stable with the local active patch set and a clean @openai/[email protected] binary. Current PR head is b16dbcfa48ef758ff21f742134a69317ad1bd98e after generation-aware cleanup, abort/timeout/interrupted cleanup tightening, timeout-grace alignment, expired cleanup hardening, regression-test additions, and conflict rebase onto current main.

Exact steps or command run after this patch: The original live probe dispatched an eval-2 Codex harness agent through the gateway with openclaw agent --agent eval-2 --message "Use exec_command to run python3 -c 'print(\"x\")'" --json while instrumenting Codex hook dispatch and OpenClaw native relay registration, unregister, and invoke lifecycle. Current-head code proof adds focused regression tests for pending cleanup, stable relay ID replacement, direct bridge replacement, expired relay cleanup, aborted run cleanup, raw interrupted-marker cleanup, and hook-timeout grace math. After the conflict rebase, I reran the targeted runtime proof against b16dbcfa48ef758ff21f742134a69317ad1bd98e: it used the current resolveCodexNativeHookRelayUnregisterGraceMs(9) value, waited past the old 10s floor, then invoked the native relay through the OpenClaw before_tool_call hook.

Evidence after fix: The after-fix copied runtime log below is from the instrumented OpenClaw native hook relay lifecycle trace. Before the fix, the same trace shape showed UNREGISTER codex-08fa4130... followed 1.2 seconds later by INVOKE codex-08fa4130... found=false.

21:38:14.471Z UNREGISTER codex-fb6566dce... relays_size_before=0  (pre-register idempotent cleanup)
21:38:14.472Z REGISTER   codex-fb6566dce... relays_size=1
... probe runs, codex spawns relay subprocess during exec_command dispatch ...
21:38:45.684Z INVOKE     codex-fb6566dce... event=pre_tool_use found=TRUE relays_size=1

Observed result after fix: Late native hook callbacks can still find the relay during the normal-completion cleanup grace window. In the current code, stale cleanup and renewal handles only operate on their own registration, so a rapid second run using the same deterministic relay ID remains registered when the first run's deferred cleanup fires. Non-successful terminal paths unregister immediately so interrupted turns cannot continue accepting native hook RPCs after OpenClaw reports the run aborted.

Exact-head targeted runtime proof output:

[proof] head=b16dbcfa48ef758ff21f742134a69317ad1bd98e
[proof] hookTimeoutSec=9 cleanupGraceMs=14000
[proof] relayId=fbbc4164-bacd-481c-9a1a-1c26fd34f88a
[proof] registration-after-register=true
[proof] scheduled successful-turn deferred unregister
[proof] registration-after-11s=true
[proof] before_tool_call reached event={"toolName":"exec","params":{"command":"python3 -c 'print(\"x\")'"},"runId":"run-1","toolCallId":"late-proof-call-1"}
[proof] late-invoke-exit=0
[proof] late-invoke-stdout={"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"proof hook blocked late native callback"}}

[proof] before-tool-call-count=1
[proof] registration-after-grace=false

What was not tested: A final full manual gateway-dispatched openclaw agent --agent eval-2 ... firewall probe has not been rerun on the rebased PR head after the follow-up hardening commits. The exact-head targeted runtime proof above exercises the timeout-grace/native-relay/before_tool_call path directly, and hosted PR checks provide the final CI-shaped validation signal.