Problem

Codex native hook relays can be registered in one module instance and invoked from another module instance in the same process. When those instances each keep their own in-memory relay maps, OpenClaw can install Codex hook commands but later fail to find the active relay for the same run. A separate race also lets a late hook command for an old run reuse the stable relay id after a replacement run has registered.

Fixes #73723 and replaces the abandoned approach in #73950.

Change and value

This PR moves native hook relay registry state onto a process-global symbol so duplicate module instances share the same relay, bridge, invocation, and permission-approval state. It also adds a per-registration generation token to newly generated hidden hook commands and validates that token through the direct bridge, gateway fallback, and Codex app-server approval bridge.

The result is that current hook commands still reach the active relay, while stale commands fail closed instead of invoking a replacement registration with the same stable relay id.

Who is affected, and who is not

• Affected: Codex app-server/native hook relay users, especially runs that load duplicate agent-harness runtime instances or overlap old and replacement Codex runs for the same session relay id.
• Not affected: ordinary plugin hooks, non-Codex native relay providers, and public user-facing CLI commands. hooks relay remains a hidden internal command.
• Compatibility: buildNativeHookRelayCommand() and the hidden CLI still tolerate omitted generations so older already-written commands fail through the normal unavailable path rather than crashing at option parsing.

Why now

#73723 is still open, and #73950 has gone stale. Recent cleanup work fixed one pending-unregister race, but it did not make duplicate module instances share relay state or prevent late stale commands from crossing into replacement registrations.

Implementation

• Store relay registrations, bridge records, invocation history, pending permission approvals, rate-limit windows, and allow-always approvals in a process-global Symbol.for("openclaw.nativeHookRelay.state") object.
• Add an internal required generation to active registrations while keeping the exported handle field optional for SDK/source compatibility.
• Include --generation in newly generated hidden hook commands.
• Require matching generations for direct bridge requests, gateway nativeHook.invoke, and the Codex app-server approval bridge's in-process relay invocation.
• Return/recognize stale bridge registrations as a fail-closed unavailable relay result instead of falling back to a newer gateway registration.
• Keep replacement pending permission approvals from being deleted by stale approval finalizers.

Verification

• Local lightweight checks:
  • git diff --check origin/main...HEAD
  • ./node_modules/.bin/oxfmt --check --threads=1 extensions/codex/src/app-server/approval-bridge.ts extensions/codex/src/app-server/approval-bridge.test.ts extensions/codex/src/app-server/native-hook-relay.test.ts src/agents/harness/native-hook-relay.ts src/agents/harness/native-hook-relay.test.ts src/cli/hooks-cli.ts src/cli/native-hook-relay-cli.ts src/cli/native-hook-relay-cli.test.ts src/gateway/server-methods/native-hook-relay.ts src/gateway/server-methods/native-hook-relay.test.ts
• Review gates:
  • Codex review after rebase against origin/main: no actionable findings.
  • Read-only adversarial lanes during development found stale-generation and app-server approval-bridge gaps; both were fixed before final validation.
• Final Crabbox/GCP validation:
  • Lease cbx_9c0044dd81ae, slug brisk-hermit, GCP us-east1-b, Spot e2-standard-8, no local sync.
  • Fresh GitHub clone of openclaw/openclaw, fetched Kaspre/openclaw branch fix/native-hook-relay-shared-state, checked out exact head 2a37ac2fc5945c7a3020dfa92c47625ea51dbd67.
  • Live proof command output:

[proof] head=2a37ac2fc5945c7a3020dfa92c47625ea51dbd67
[proof] duplicate-module-invoke=0
[proof] stale-generation-error=native hook relay bridge stale registration
[proof] replacement-generation-invoke=0

• Focused changed-path tests passed: src/agents/harness/native-hook-relay.test.ts, src/cli/native-hook-relay-cli.test.ts, src/gateway/server-methods/native-hook-relay.test.ts, extensions/codex/src/app-server/native-hook-relay.test.ts, extensions/codex/src/app-server/approval-bridge.test.ts (118 tests across 4 Vitest shards).
• pnpm check:changed passed on the same exact head.

Real behavior proof

Behavior or issue addressed: Codex native hook relay state remains available across duplicate module instances, and a stale relay command from an old stable relay-id registration cannot invoke the replacement registration.

Real environment tested: Crabbox GCP Spot VM (us-east1-b, e2-standard-8) from a fresh GitHub clone, checking out pushed fork head 2a37ac2fc5945c7a3020dfa92c47625ea51dbd67.

Exact steps or command run after this patch: On the Crabbox VM, cloned https://github.com/openclaw/openclaw.git, fetched https://github.com/Kaspre/openclaw.git fix/native-hook-relay-shared-state, checked out FETCH_HEAD, installed Node 24.15.0 and pnpm@11.0.8, then ran a node --import tsx --input-type=module -e ... script that imported src/agents/harness/native-hook-relay.ts twice, registered a relay in one module instance, invoked it from the duplicate module instance, replaced the same stable relay id, attempted a stale-generation bridge invocation, and then invoked the replacement generation. The same VM then ran the focused Vitest files and pnpm check:changed.

Evidence after fix: Terminal capture from lease cbx_9c0044dd81ae:

[proof] head=2a37ac2fc5945c7a3020dfa92c47625ea51dbd67
[proof] duplicate-module-invoke=0
[proof] stale-generation-error=native hook relay bridge stale registration
[proof] replacement-generation-invoke=0

Observed result after fix: The duplicate module successfully invoked the current relay (exitCode=0), the stale generation was rejected with native hook relay bridge stale registration, the replacement generation invoked successfully (exitCode=0), focused changed-path tests passed, and pnpm check:changed exited 0.

What was not tested: No changed-path behavior gap remains. The full unrelated repository test suite is left to GitHub CI; this PR ran live relay proof, focused changed-path tests, and check:changed on the exact pushed head.

AI Assistance

I used Codex to prepare the patch and verification.