The production service runner: one headless process for engine + service (#955)

[aarontrowbridge]

Refs #955 (the hub cutover, spec spec-20260910-080000).

What

The hub has no extension host: the extension-host arrangement (spawn the vendored engine, boot the amicode service alongside) has no permanent home there — the #822 boot probe only rehearses it and exits. This adds the runner: ONE long-lived headless process that spawns the engine and serves the app.

• src/amicode_service_runner.ts — bootAmicodeServiceRunner: engine spawn password-armed (the SAME mint convention as every spawn site: mintServerPassword() → OPENCODE_SERVER_PASSWORD, health-wait WITH the armed credential), then createAmicodeService wired exactly as startAmicodeService does (engine handle + shelf distRoot + engine-token auth). No fleetActivation is ever passed — H3: the hub runs the byte-identical unarmed base service.
• src/amicode_service_runner_cli.ts — the env surface, bundled to bin/dist/amicode-service-runner.mjs (the mcp-amico.mjs convention; plain node):
  • AMICODE_ENGINE_BIN (default: the vendored path relative to the bundle), AMICODE_APP_DIST (required — a missing/unbuilt dist fails loud, the NEEDS-SETUP placeholder is the extension's degradation, not a hub shape), AMICODE_SERVICE_PORT (4095), AMICODE_ENGINE_PORT (4094), AMICODE_ENGINE_CWD, OPENCODE_DB (the canonical pin, passed through), AMICODE_ENGINE_PASSWORD (ops-owned credential for the frontdoor's ?auth_token= carrier; random mint when absent).
  • SIGTERM/SIGINT → graceful teardown (service stop, SIGTERM engine, 3s SIGKILL fallback). Any boot failure or engine death mid-run → non-zero exit with a named [service-runner] FAIL: <reason> — never a silent half-boot.
• Latent upstream fix in amicode_service/server.ts: start() set this.server before the listen promise — a busy fixed port left instance state that made the caller's own ephemeral fallback die on "already running" (the wiring's fallback had the same exposure).

Tests (test/amicode_service_runner.test.ts)

Live-gated (real vendored engine + built dist, the boot-probe convention): the six #823 probe surfaces asserted through the runner's own orchestration; the OPENCODE_DB pin reaching the engine (the pinned DB file gets created/migrated); the busy-fixed-port fallback (pins the server.ts fix). Always-on fail-loud: missing engine bin / empty shelf / never-healthy engine — each a named AmicodeServiceRunnerError.reason, the spawned child torn down.

Evidence (run for real in the worktree, throwaway DB)

Runner boot lines:

[service-runner] spawning engine …/vendor/opencode/linux-x64/opencode serve --port=14094 (cwd=/tmp/…, OPENCODE_DB=/tmp/opencode/runner-955-evidence.db)
[service-runner] engine up at http://127.0.0.1:14094
[amicode-service] listening on http://127.0.0.1:14095 (43 routes; auth: per-boot Basic + engine token); app shelf mounted

Six surfaces against the runner's origin: app doc 200 text/html (not the placeholder) · bootstrap ?auth_token= (no header) 200 · anonymous asset 200 text/javascript · proxied GET /session 200 application/json ([]) · proxied GET /event 200 text/event-stream · GET /amicode/profile {"ok":true,…}. Pinned DB file created (256 KiB, engine-migrated).

Fail-loud (CLI): AMICODE_ENGINE_BIN=/nonexistent/opencode node bin/dist/amicode-service-runner.mjs → [service-runner] FAIL: no engine binary at /nonexistent/opencode — set AMICODE_ENGINE_BIN …, exit 1.

SIGTERM → [service-runner] SIGTERM — tearing down engine + service / [service-runner] stopped — service closed, engine torn down, runner exits 0, engine process gone, service port closed.

Baseline

typecheck clean; extension vitest: 8 pre-existing failures (clean main @ a7741ee, clean env: 9, of which cli_gate passes here only because a local build staged the amico-run bins) — none introduced. The runner tests: 5 live + 3 fail-loud green.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}