fix(plugins): in-process sandbox fallback when child-process fork is restricted

[HareeshDaxton]

Closes #93 (B-0018).

Problem

Vencore runs each plugin backend in an isolated forked child process. On hosts that restrict child-process creation, fork() fails: the plugin never mounts its router (404 PLUGIN_NOT_MOUNTED / "Plugin not found") and a synchronous fork throw during load surfaces as a 500.

What changed

An in-process execution strategy behind a strategy dispatcher, so no caller changes:

• facade.ts — shared vencore facade builder parameterized by a transport, so the plugin-facing API is byte-for-byte identical in both modes and cannot drift.
• runner.ts — builds its facade from the shared builder over an IPC transport (child behavior unchanged).
• child-process.ts — existing fork logic extracted; fork sync-throws and pre-ready child error/exit funnel into an onForkUnavailable hook (this also closes the 500).
• in-process.ts — runs the bundle via require (cache-busted), calls dispatchBridgeCall directly with envelope unwrap, mounts HTTP routes locally, forwards declared listen topics from the workspace bus.
• manager.ts — thin dispatcher. PLUGIN_SANDBOX_MODE (auto | child | in-process, default auto) selects the strategy. In auto, the first detected fork failure latches into in-process for all plugins.
• index.ts — startup log names the active mode; SIGTERM/SIGINT now call killAllSandboxes (previously dead code) so in-process bus subscriptions don't leak.

auto keeps the isolated child process wherever forking works, so the reduced isolation of in-process only applies on hosts that force it.

A second defect, found while testing

Reproducing the issue against a real fork-restricted container (exhausted pids cgroup) showed the fallback above was not sufficient.

It only fires when fork fails loudly — a synchronous fork() throw, a child error, or an exit before ready. When the host limit is a process/thread budget rather than an outright block, fork() succeeds: the child process exists but can never finish booting. It emits no error, never exits, and never signals ready. None of the three triggers fire, the spawn hangs forever, and the plugin stays unmounted — the exact 404 this PR set out to prevent.

The final commit adds a readiness deadline. A child that misses it is SIGKILLed (a process wedged before boot may never run a SIGTERM handler) and reported as fork-unavailable, so auto latches into in-process as it does elsewhere. The timer is unref'd and cleared on both ready and exit. Configurable via PLUGIN_SANDBOX_READY_TIMEOUT_MS (default 15s).

This is the failure mode a restricted host is most likely to produce — budgets exhaust silently, they don't throw EPERM.

Verification

End-to-end against a live stack (Docker Compose: TimescaleDB + Redis + API), with a seeded test plugin and the API container's process budget starved via pids_limit: 15:

Scenario	Result
Fork available (baseline)	count: 1, child-process sandbox mounts
Fork restricted, before readiness fix	Hangs silently, plugin unmounted — bug reproduced
Fork restricted, after readiness fix	Falls back, plugin mounts — bug fixed

Log from the restricted container after the fix:

WARN  Plugin child-process fork unavailable
        reason: "child did not signal ready within 15000ms"
WARN  Child-process fork unavailable — falling back to in-process plugin sandbox for all plugins
INFO  Plugin in-process sandbox setup complete
WARN  Plugin sandbox process exited          <- wedged child reaped, PIDs 15->14

Also verified: both modes honored in the deployed API (pluginSandboxMode: "auto" / "in-process"), tsc clean across packages/* and apps/api, web app renders.

28 automated tests, all passing:

• plugin-sandbox-fallback.test.ts (12) — mode selection, the fork-unavailable fallback and its latch across plugins, crash respawn routing back through mode selection, strategy-agnostic lookups.
• plugin-sandbox-in-process.test.ts (10) — the real in-process strategy against real bundles over a real HTTP server: routes serve, bodies pass through, a throwing handler yields a contained 500, bridge envelope unwrapping, bus/cron delivery, require-cache busting on upgrade, teardown.
• plugin-sandbox-ready-timeout.test.ts (6) — the wedged-child case (stubbed fork + fake timers, since a unit test cannot exhaust a cgroup), including that it does not trigger the 5s crash-restart into the same dead end.

Reviewer notes

• Security trade-off. In-process mode removes OS process isolation — plugin code shares the API process and can read process.env and process globals directly. The facade still never hands env/secrets to the plugin, and auto limits this to hosts that force it, but this matters if you run untrusted third-party plugins. Pin PLUGIN_SANDBOX_MODE=child to refuse the trade entirely (plugins stay down rather than lose isolation).
• The 15s default is a judgment call. A genuinely slow host could exceed it and fall back unnecessarily, trading isolation for availability. That is the safer direction, but worth a look for your deployment.
• Both new env vars are documented in .env.example and validated in apiEnvSchema.

Out of scope / not done

• The full API test suite was not run — only the three sandbox files. There is no Node toolchain on the dev machine used here, so tests ran in a container with vitest + express only.
• No authenticated HTTP request was made to a plugin route in the live app (first-run setup was not completed). Router mounting is evidenced by the live log line, which fires only after entry.router is assigned, and by the integration tests serving real plugin routes.
• The worker service was not exercised.