fix(dispatcher): use gateway HTTP API for isolated-session dispatch

[amittell]

Problem

The previous dispatch primitive for session_target=isolated cron jobs forked a sibling openclaw CLI to spawn the isolated session. In production on rh-bot.lan that fork inherited the launchd-tracked gateway parent's listening socket on port 18789 and the SIGTERM cascade killed the parent every cycle, leaving an orphan node process bound to the port and the gateway offline for hours.

The internal memory note project_rh_bot_isolated_session_sigkill records roughly 30 SIGTERM events per week traceable to this dispatch path.

Solution

This change names and pins the sanctioned isolated-session dispatch primitive in the scheduler:

1. gateway.js gains an exported ISOLATED_DISPATCH_PRIMITIVE contract marker plus a runIsolatedAgentTurn helper. The helper is a thin wrapper around the existing runAgentTurnWithActivityTimeout so the same HTTP /v1/chat/completions call site backs both names. The wrapper gives reviewers a single grep target for auditing the no-fork invariant.

2. dispatcher.js exposes runIsolatedAgentTurn in the dispatch deps bag.

3. dispatcher-strategies.js executeAgent (the strategy that handles session_target=isolated cron jobs) now routes through runIsolatedAgentTurn, with a fallback to the legacy runAgentTurnWithActivityTimeout name so the deps wiring tolerates older callers and tests.

Net runtime effect: every isolated cron dispatch reaches the gateway via the public HTTP API only, inside the existing gateway process. No child_process.spawn, fork, or execFile is ever invoked on the isolated-job hot path.

Verification

npm test passes locally: 1741 passed, 0 failed (was 1722 before; gained 19 assertions from the new regression test).

npm run verify:smoke packs cleanly.

npm run lint is clean.

The new regression test (-- Isolated dispatch primitive: no subprocess spawn --) covers the contract two ways:

• Source check: runIsolatedAgentTurn and the executeAgent strategy bodies are inspected for any reference to child_process, execFile, spawn(, fork(, or execSync and must contain none.
• Behavior check: executeAgent is invoked with a session_target=isolated job against the real exported gateway helpers, with globalThis.fetch stubbed. The test asserts /v1/chat/completions was hit via HTTP POST and the assistant reply round-trips back through executeAgent.result.content.

Migration

Existing scheduled jobs with session_target=isolated continue to work transparently. Same job row, same strategy dispatch, same delivery semantics, same retry/idempotency surface; only the named entry point used to reach the gateway is now stable and auditable. Operators deploying this drop the orphan-on-port risk without any job migration or config change.

The runAgentTurnWithActivityTimeout export and its existing behavior are preserved for compatibility with any out-of-tree caller; the new helper delegates to it directly so behavior is bit-identical.

[Copilot]

Pull request overview

This PR stabilizes the session_target=isolated dispatch path by routing isolated cron job turns through the gateway’s HTTP /v1/chat/completions API (instead of spawning a sibling CLI process), and pins that invariant behind an explicit, grep-able dispatch primitive.

Changes:

• Add ISOLATED_DISPATCH_PRIMITIVE and runIsolatedAgentTurn() to gateway.js as the sanctioned isolated dispatch entry point (thin wrapper over the existing HTTP chat-completions call site).
• Wire runIsolatedAgentTurn through dispatcher.js deps and route executeAgent (isolated strategy) through it with a legacy fallback.
• Add a regression test ensuring the isolated dispatch path does not reference subprocess primitives and performs an HTTP POST to /v1/chat/completions.

Reviewed changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
gateway.js	Introduces an explicit isolated-dispatch contract marker and a named wrapper helper for HTTP-only agent turns.
dispatcher.js	Exposes runIsolatedAgentTurn in the dispatch dependency bag.
dispatcher-strategies.js	Routes isolated executeAgent turns through runIsolatedAgentTurn (with fallback) and documents the no-fork invariant.
test.js	Adds a regression test enforcing “no subprocess spawn” and validating HTTP /v1/chat/completions dispatch behavior.
package-lock.json	Bumps package/lock metadata version and records Node engine requirement update.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.