target-supabase-sdk 0.2.12 → 0.2.14

package/src/node/service-guard/service-guard-node.ts

@@ -1,17 +1,35 @@
-import type { LoggerWithScope } from "../../shared/log";
+import { createLogger, type LoggerWithScope } from "../../shared/log";
+import { registerCollectLogRunner } from "../../shared/log/spool/register-collect-log-runner";
+import { getErrorMessage } from "../../shared/utils/error.utils";
 import { TriggerNode } from "../../trigger/trigger-node";
+import type { NodeLoopContext } from "../node-runtime.base";
+import { pollUntil } from "../readiness/poll-until";
+import { runReadinessGate } from "../readiness/run-readiness-gate";
+import type { GuardRuntimeSlice } from "../runtime-state/service-runtime-state.types";
 import { registerServiceGuardRunner } from "./register-service-guard-runner";
-import { runReadinessGate } from "./run-readiness-gate";
 import type { ServiceGuardNodeOptions } from "./service-guard.interface";
+import { markWorkerSpawned } from "./worker-spawn-cooldown";
+
+const SILENT_BACKOFF_MS = [15_000, 30_000, 60_000, 120_000, 240_000, 300_000] as const;
+const SILENT_EVENT_LIMIT = 32;
+const DEFAULT_BUSINESS_READY_TIMEOUT_MS = 180_000;
 
 /**
- * L3 guard process TriggerNode: readiness gate, TaskNode worker spawn owner,
+ * L3 guard process TriggerNode: readiness gate, business-node spawn owner,
  * and {@link registerServiceGuardRunner} tick (registry slot + liveness + runtime).
  *
+ * Consecutive heartbeat failure enters silent mode (no process exit). Recovery
+ * respawns business nodes; leaving silent requires heartbeat + all nodes ready.
+ *
  * Use {@link ServiceGuardNode.create} so the guard runner is registered before `start()`.
  */
 class ServiceGuardNode extends TriggerNode {
     private readonly options: ServiceGuardNodeOptions;
+    private readonly businessReadyTimeoutMs: number;
+    private mode: GuardRuntimeSlice["mode"] = "healthy";
+    private silentBackoffIndex = 0;
+    private silentEvents: GuardRuntimeSlice["silentEvents"] = [];
+    private recoverPromise: Promise<void> | null = null;
 
     private constructor(options: ServiceGuardNodeOptions) {
         super({
@@ -19,18 +37,56 @@ class ServiceGuardNode extends TriggerNode {
             beforeProcessExit: options.beforeProcessExit,
         });
         this.options = options;
+        this.businessReadyTimeoutMs = options.businessReadyTimeoutMs ?? DEFAULT_BUSINESS_READY_TIMEOUT_MS;
     }
 
     /** Register the guard runner and return a ready-to-start node. */
     static create(options: ServiceGuardNodeOptions): ServiceGuardNode {
         registerServiceGuardRunner({
+            ...options.guardRunner,
             serviceValue: options.serviceValue,
             logTopic: options.logTopic,
-            ...options.guardRunner,
+            spawnWorker: options.spawnBusinessNodes,
+        });
+        registerCollectLogRunner({
+            serviceValue: options.serviceValue,
+            getServiceId: options.guardRunner.getServiceId,
         });
         return new ServiceGuardNode(options);
     }
 
+    protected isSilenced(): boolean {
+        return this.mode !== "healthy";
+    }
+
+    protected getLoopIntervalMs(): number {
+        if (this.mode === "silent") {
+            return SILENT_BACKOFF_MS[this.silentBackoffIndex] ?? 300_000;
+        }
+        return super.getLoopIntervalMs();
+    }
+
+    protected async onHealthCheckFailed(_ctx: NodeLoopContext): Promise<void> {
+        if (this.mode !== "healthy") {
+            this.bumpSilentBackoff();
+            await this.persistGuard({
+                lastDecision: "silent_heartbeat_fail",
+                silentConsecutiveFailures: this.silentConsecutiveFailures(),
+                silentBackoffMs: this.getLoopIntervalMs(),
+                silentLastHeartbeatAt: new Date().toISOString(),
+            });
+            return;
+        }
+        await this.enterSilent("heartbeat:consecutive-failures");
+    }
+
+    protected async onHeartbeatRecovered(ctx: NodeLoopContext): Promise<void> {
+        if (this.mode !== "silent") {
+            return;
+        }
+        await this.recoverFromSilent(ctx);
+    }
+
     protected async onBeforeRegisterNode(nodeLogger: LoggerWithScope): Promise<void> {
         await runReadinessGate({
             checks: this.options.readinessChecks,
@@ -41,11 +97,183 @@ class ServiceGuardNode extends TriggerNode {
 
         await super.onBeforeRegisterNode(nodeLogger);
 
-        nodeLogger.info("Spawning TaskNode worker (single spawn owner)", {
+        nodeLogger.info("Spawning business nodes", {
             topic: this.options.logTopic ?? "guard",
         });
-        await this.options.spawnWorker("guard:readiness-passed");
+        await this.options.spawnBusinessNodes("guard:readiness-passed");
+        markWorkerSpawned();
         this.options.onWorkerSpawned?.();
+
+        await this.waitUntilBusinessReady();
+        await this.persistGuard({
+            mode: "healthy",
+            lastDecision: "bootstrap_ready",
+        });
+    }
+
+    protected async runLoopSteps(ctx: NodeLoopContext, heartbeatOk: boolean): Promise<void> {
+        await super.runLoopSteps(ctx, heartbeatOk);
+        if (this.mode !== "healthy" || !heartbeatOk) {
+            return;
+        }
+        // Idempotent — respawn exited children without entering silent (worker stale is the runner's job).
+        try {
+            await this.options.spawnBusinessNodes("guard:ensure-business");
+        } catch (error) {
+            this.createGuardLogger().warn("ensure-business spawn failed", {
+                topic: this.options.logTopic ?? "guard",
+                data: { error: getErrorMessage(error) },
+            });
+        }
+    }
+
+    private silentConsecutiveFailures(): number {
+        return this.silentBackoffIndex + 1;
+    }
+
+    private bumpSilentBackoff(): void {
+        if (this.silentBackoffIndex < SILENT_BACKOFF_MS.length - 1) {
+            this.silentBackoffIndex += 1;
+        }
+    }
+
+    private async enterSilent(reason: string): Promise<void> {
+        this.mode = "silent";
+        this.silentBackoffIndex = 0;
+        const enteredAt = new Date().toISOString();
+        this.pushEvent("enter", reason);
+        await this.persistGuard({
+            mode: "silent",
+            lastDecision: `silent:${reason}`,
+            silentEnteredAt: enteredAt,
+            silentLastHeartbeatAt: enteredAt,
+            silentBackoffMs: SILENT_BACKOFF_MS[0],
+            silentConsecutiveFailures: 1,
+            silentRecoveryAttempt: 0,
+            silentEvents: this.silentEvents,
+        });
+
+        const logger = this.createGuardLogger();
+        logger.warn("Entering silent mode — service unavailable until heartbeat + business nodes recover", {
+            topic: this.options.logTopic ?? "guard",
+            data: { reason },
+        });
+
+        try {
+            await this.options.stopBusinessNodes();
+        } catch (error) {
+            logger.warn("stopBusinessNodes failed (best-effort)", {
+                topic: this.options.logTopic ?? "guard",
+                data: { error: getErrorMessage(error) },
+            });
+        }
+    }
+
+    private async recoverFromSilent(ctx: NodeLoopContext): Promise<void> {
+        if (this.recoverPromise != null) {
+            return this.recoverPromise;
+        }
+        this.recoverPromise = this.runRecover(ctx).finally(() => {
+            this.recoverPromise = null;
+        });
+        return this.recoverPromise;
+    }
+
+    private async runRecover(ctx: NodeLoopContext): Promise<void> {
+        this.mode = "recovering";
+        this.pushEvent("recover_start", ctx.loopTraceId);
+        await this.persistGuard({
+            mode: "recovering",
+            lastDecision: "recovering",
+            silentLastHeartbeatAt: new Date().toISOString(),
+            silentRecoveryAttempt: this.silentEvents.filter((event) => event.type === "recover_start").length,
+            silentEvents: this.silentEvents,
+        });
+
+        const logger = this.createGuardLogger();
+        logger.info("Heartbeat restored — recovering business nodes", {
+            topic: this.options.logTopic ?? "guard",
+        });
+
+        try {
+            await this.options.stopBusinessNodes();
+        } catch (error) {
+            logger.warn("stopBusinessNodes failed before respawn", {
+                topic: this.options.logTopic ?? "guard",
+                data: { error: getErrorMessage(error) },
+            });
+        }
+
+        try {
+            await this.options.spawnBusinessNodes("guard:silent-recover");
+            markWorkerSpawned();
+            await this.waitUntilBusinessReady();
+        } catch (error) {
+            this.pushEvent("recover_fail", getErrorMessage(error));
+            this.mode = "silent";
+            this.bumpSilentBackoff();
+            await this.persistGuard({
+                mode: "silent",
+                lastDecision: "recover_fail",
+                silentBackoffMs: this.getLoopIntervalMs(),
+                silentEvents: this.silentEvents,
+            });
+            logger.warn("Recovery failed — returning to silent", {
+                topic: this.options.logTopic ?? "guard",
+                data: { error: getErrorMessage(error) },
+            });
+            try {
+                await this.options.stopBusinessNodes();
+            } catch {
+                // best-effort — leftover children are stopped again on the next recover
+            }
+            return;
+        }
+
+        this.mode = "healthy";
+        this.silentBackoffIndex = 0;
+        this.pushEvent("recover_ok");
+        await this.persistGuard({
+            mode: "healthy",
+            lastDecision: "recover_ok",
+            silentEnteredAt: null,
+            silentBackoffMs: 0,
+            silentConsecutiveFailures: 0,
+            silentEvents: this.silentEvents,
+        });
+        logger.success("Left silent mode — business nodes ready", {
+            topic: this.options.logTopic ?? "guard",
+        });
+    }
+
+    private async waitUntilBusinessReady(): Promise<void> {
+        try {
+            await pollUntil({
+                timeoutMs: this.businessReadyTimeoutMs,
+                intervalMs: 500,
+                until: () => this.options.isBusinessReady(),
+            });
+        } catch {
+            throw new Error(`Business nodes not ready within ${this.businessReadyTimeoutMs}ms`);
+        }
+    }
+
+    private pushEvent(type: string, detail?: string): void {
+        this.silentEvents = [...this.silentEvents, { at: new Date().toISOString(), type, detail }].slice(
+            -SILENT_EVENT_LIMIT,
+        );
+    }
+
+    private async persistGuard(patch: Partial<GuardRuntimeSlice>): Promise<void> {
+        try {
+            await this.options.guardRunner.onGuardPatch(patch);
+        } catch {
+            // best-effort — disk/runtime state must not take down the guard loop
+        }
+    }
+
+    private createGuardLogger(): LoggerWithScope {
+        return createLogger({ module: "service-guard" });
     }
 }
 

package/src/node/service-guard/service-guard.interface.ts

@@ -1,8 +1,8 @@
-import type { Node } from "../../node/node.interface";
 import type { RegistrySlotRuntimeState } from "../../service/registry-lifecycle";
 import type { LoggerWithScope } from "../../shared/log";
-import type { TriggerNodeOptions } from "../../trigger/trigger.interface";
+import type { Node } from "../node.interface";
 import type { ReadinessCheck, ReadinessReport } from "../readiness/readiness.types";
+import type { GuardRuntimeSlice } from "../runtime-state/service-runtime-state.types";
 
 /** Default TriggerManager runner key for {@link registerServiceGuardRunner}. */
 export const SERVICE_GUARD_RUNNER_KEY = "service-guard";
@@ -45,20 +45,45 @@ export interface RegisterServiceGuardRunnerOptions {
     onRegistryPatch: (
         patch: Pick<RegistrySlotRuntimeState, "slotOwned" | "lastSlotCheckAt" | "lastSlotCheckError">,
     ) => Promise<void>;
-    onGuardPatch: (patch: { nodeId: string; lastCheckAt: string; lastDecision?: string }) => Promise<void>;
+    onGuardPatch: (patch: Partial<GuardRuntimeSlice>) => Promise<void>;
     onDecision?: (decision: string) => Promise<void>;
 }
 
-export interface ServiceGuardNodeOptions extends TriggerNodeOptions {
+export interface ServiceGuardNodeOptions {
     serviceValue: string;
     logTopic?: string;
     readinessChecks: ReadinessCheck[];
     onReadinessReport: (report: ReadinessReport) => Promise<void>;
-    guardRunner: Omit<
-        RegisterServiceGuardRunnerOptions,
-        "serviceValue" | "logTopic" | "runnerKey" | "intervalMs" | "initialDelayMs"
-    > &
-        Pick<RegisterServiceGuardRunnerOptions, "intervalMs" | "initialDelayMs">;
-    spawnWorker: (reason: string) => Promise<void>;
+    guardRunner: Omit<RegisterServiceGuardRunnerOptions, "serviceValue" | "logTopic" | "runnerKey" | "spawnWorker">;
+    /**
+     * Idempotent spawn of all business nodes (scheduler + worker, etc.).
+     * Used at bootstrap, silent recovery, and healthy-mode TaskNode respawn.
+     */
+    spawnBusinessNodes: (reason: string) => Promise<void>;
+    /** Stop business nodes only (never the guard process). */
+    stopBusinessNodes: () => Promise<void>;
+    /** Local runtime gate: all business nodes registered and ready. */
+    isBusinessReady: () => Promise<boolean>;
+    /** Timeout for {@link isBusinessReady} during bootstrap and recovery. Default 180s. */
+    businessReadyTimeoutMs?: number;
+    /** Extra hook after the initial business spawn (cooldown is recorded automatically). */
     onWorkerSpawned?: () => void;
+    beforeProcessExit?: () => void | Promise<void>;
+}
+
+/** True when the guard slice is serving traffic (`mode` omitted = legacy healthy). */
+export function isGuardAvailable(guard: Pick<GuardRuntimeSlice, "mode">): boolean {
+    return guard.mode == null || guard.mode === "healthy";
+}
+
+/**
+ * Seconds for `Retry-After` when the guard is not serving traffic.
+ * `null` when {@link isGuardAvailable} is true.
+ */
+export function guardRetryAfterSec(guard: Pick<GuardRuntimeSlice, "mode" | "silentBackoffMs">): number | null {
+    if (isGuardAvailable(guard)) {
+        return null;
+    }
+    const backoffMs = guard.silentBackoffMs > 0 ? guard.silentBackoffMs : 15_000;
+    return Math.max(1, Math.ceil(backoffMs / 1000));
 }

package/src/node/service-host/claim-registry-slot.ts

@@ -0,0 +1,33 @@
+import { ServiceRegistryError } from "../../service/registry.service";
+import { claimServiceRegistrySlot, type ServiceRegistrySession } from "../../service/registry-lifecycle";
+import type { Service } from "../../service/service.interface";
+import type { LoggerWithScope } from "../../shared/log";
+
+export interface ClaimRegistrySlotOrExitInput {
+    serviceValue: string;
+    createInstance: () => Promise<Service>;
+    logger: LoggerWithScope;
+    logTopic: string;
+}
+
+/**
+ * Claim a registry slot, or `process.exit(1)` when no EMPTY slot remains.
+ * Other errors propagate.
+ */
+export async function claimRegistrySlotOrExit(input: ClaimRegistrySlotOrExitInput): Promise<ServiceRegistrySession> {
+    try {
+        return await claimServiceRegistrySlot({
+            serviceValue: input.serviceValue,
+            createInstance: input.createInstance,
+        });
+    } catch (error) {
+        if (error instanceof ServiceRegistryError && error.code === "SERVICE_SLOTS_FULL") {
+            input.logger.critical("No EMPTY registry slot — refusing to start", {
+                topic: input.logTopic,
+                data: { serviceValue: input.serviceValue, code: error.code },
+            });
+            process.exit(1);
+        }
+        throw error;
+    }
+}

package/src/node/service-host/create-l3-child-launcher.ts

@@ -0,0 +1,157 @@
+import type { ChildProcess } from "node:child_process";
+import type { ManagedChildProcesses } from "../process/managed-child-processes";
+import type {
+    GuardRuntimeSlice,
+    SchedulerRuntimeSlice,
+    WorkerRuntimeSlice,
+} from "../runtime-state/service-runtime-state.types";
+
+const WORKER_SCRIPT = "./dist/processes/worker.js";
+const GUARD_SCRIPT = "./dist/processes/guard.js";
+const SCHEDULER_SCRIPT = "./dist/processes/scheduler.js";
+
+export interface L3ChildLauncherRuntimeStore {
+    readRuntimeState(): Promise<{
+        worker: WorkerRuntimeSlice;
+        scheduler: SchedulerRuntimeSlice;
+        guard: GuardRuntimeSlice;
+    }>;
+    writeRuntimeState(patch: {
+        worker?: Partial<WorkerRuntimeSlice>;
+        scheduler?: Partial<SchedulerRuntimeSlice>;
+        guard?: Partial<GuardRuntimeSlice>;
+    }): Promise<unknown>;
+}
+
+export interface CreateL3ChildLauncherOptions {
+    childProcesses: ManagedChildProcesses;
+    readRuntimeState: L3ChildLauncherRuntimeStore["readRuntimeState"];
+    writeRuntimeState: L3ChildLauncherRuntimeStore["writeRuntimeState"];
+    /** Merged onto the child env. Default: `{ LOG_PERSIST_PROCESS: label }`. */
+    spawnEnv?: (label: string) => Record<string, string>;
+}
+
+export interface L3ChildLauncher {
+    spawnGuard: () => ChildProcess;
+    spawnTaskWorker: (reason: string) => Promise<ChildProcess>;
+    spawnScheduler: (reason: string) => Promise<ChildProcess>;
+    spawnBusinessNodes: (reason: string) => Promise<void>;
+    stopBusinessNodes: () => Promise<void>;
+    isBusinessReady: () => Promise<boolean>;
+    stopChildProcesses: () => Promise<void>;
+}
+
+function defaultSpawnEnv(label: string): Record<string, string> {
+    return { LOG_PERSIST_PROCESS: label };
+}
+
+/**
+ * Guard-owned scheduler + worker spawn/stop, plus main-owned Guard spawn.
+ * `stopBusinessNodes` must run in the Guard process (that instance's children only).
+ * `stopChildProcesses` is for main shutdown (`extraPids` for Guard-spawned PIDs).
+ */
+export function createL3ChildLauncher(options: CreateL3ChildLauncherOptions): L3ChildLauncher {
+    const { childProcesses, readRuntimeState, writeRuntimeState } = options;
+    const spawnEnv = options.spawnEnv ?? defaultSpawnEnv;
+
+    function nowIso(): string {
+        return new Date().toISOString();
+    }
+
+    async function spawnTaskWorker(reason: string): Promise<ChildProcess> {
+        const { child, created } = childProcesses.spawn("worker", WORKER_SCRIPT, {
+            env: spawnEnv("worker"),
+        });
+        if (!created) {
+            return child;
+        }
+
+        const current = await readRuntimeState();
+        await writeRuntimeState({
+            worker: {
+                pid: child.pid ?? null,
+                spawnedAt: nowIso(),
+                ready: false,
+                registeredTasks: [],
+                readyAt: null,
+            },
+            guard: {
+                lastSpawnAt: nowIso(),
+                lastDecision: reason,
+                spawnCount: current.guard.spawnCount + 1,
+            },
+        });
+
+        return child;
+    }
+
+    function spawnGuard(): ChildProcess {
+        return childProcesses.spawn("guard", GUARD_SCRIPT, { env: spawnEnv("guard") }).child;
+    }
+
+    async function spawnScheduler(reason: string): Promise<ChildProcess> {
+        const { child, created } = childProcesses.spawn("scheduler", SCHEDULER_SCRIPT, {
+            env: spawnEnv("scheduler"),
+        });
+        if (!created) {
+            return child;
+        }
+
+        await writeRuntimeState({
+            scheduler: {
+                pid: child.pid ?? null,
+                spawnedAt: nowIso(),
+                ready: false,
+                readyAt: null,
+            },
+            guard: {
+                lastDecision: reason,
+            },
+        });
+
+        return child;
+    }
+
+    async function spawnBusinessNodes(reason: string): Promise<void> {
+        await spawnScheduler(reason);
+        await spawnTaskWorker(reason);
+    }
+
+    async function stopBusinessNodes(): Promise<void> {
+        await childProcesses.stopAll();
+        await writeRuntimeState({
+            worker: {
+                pid: null,
+                ready: false,
+                readyAt: null,
+                registeredTasks: [],
+            },
+            scheduler: {
+                pid: null,
+                ready: false,
+                readyAt: null,
+            },
+        });
+    }
+
+    async function isBusinessReady(): Promise<boolean> {
+        const state = await readRuntimeState();
+        return state.worker.ready && state.scheduler.ready;
+    }
+
+    async function stopChildProcesses(): Promise<void> {
+        const state = await readRuntimeState();
+        const extraPids = [state.worker.pid, state.scheduler.pid].filter((pid): pid is number => pid != null);
+        await childProcesses.stopAll({ extraPids });
+    }
+
+    return {
+        spawnGuard,
+        spawnTaskWorker,
+        spawnScheduler,
+        spawnBusinessNodes,
+        stopBusinessNodes,
+        isBusinessReady,
+        stopChildProcesses,
+    };
+}

package/src/node/service-host/index.ts

@@ -1,24 +1,9 @@
 export type {
-    RegisterServiceGuardRunnerOptions,
-    RunReadinessGateInput,
-    ServiceGuardNodeOptions,
-    ServiceGuardTickInput,
-    ServiceGuardTickResult,
-} from "../service-guard";
-export {
-    getWorkerSpawnCooldownLastAt,
-    markWorkerSpawned,
-    registerServiceGuardRunner,
-    runReadinessGate,
-    runServiceGuardTick,
-    SERVICE_GUARD_RUNNER_KEY,
-    ServiceGuardNode,
-} from "../service-guard";
-export type {
-    ApplyRegistrySlotGuardInput,
-    ApplyRegistrySlotGuardResult,
-} from "./registry-slot-guard-step";
-export { applyRegistrySlotGuardStep } from "./registry-slot-guard-step";
+    CreateL3ChildLauncherOptions,
+    L3ChildLauncher,
+    L3ChildLauncherRuntimeStore,
+} from "./create-l3-child-launcher";
+export { createL3ChildLauncher } from "./create-l3-child-launcher";
 export type {
     ServiceHost,
     ServiceHostClosable,

package/src/node/service-host/service-host.ts

@@ -1,7 +1,12 @@
-import { createLogger, type Service, ServiceRegistryError } from "../../browser";
-import { claimServiceRegistrySlot, type ServiceRegistrySession } from "../../service/registry-lifecycle";
-import type { LoggerWithScope } from "../../shared/log";
+import { ServiceRegistryError } from "../../service/registry.service";
+import type { ServiceRegistrySession } from "../../service/registry-lifecycle";
+import type { Service } from "../../service/service.interface";
+import { createLogger, type LoggerWithScope } from "../../shared/log";
+import { LOG_SPOOL_SERVICE_ID_ENV } from "../../shared/log/spool/config";
+import { ensureLogSpoolFromEnv } from "../../shared/log/spool/enable";
+import { logSpoolEnabledFromEnv } from "../../shared/log/upload/env";
 import type { ManagedChildProcesses } from "../process/managed-child-processes";
+import { claimRegistrySlotOrExit } from "./claim-registry-slot";
 
 export interface ServiceHostClosable {
     close: () => Promise<void>;
@@ -10,6 +15,8 @@ export interface ServiceHostClosable {
 export interface ServiceHostContext {
     service: Service;
     session: ServiceRegistrySession;
+    /** Registry instance id — same as `service.id`; children inherit via spawn env injection. */
+    serviceId: string;
 }
 
 export interface ServiceHostOptions {
@@ -23,9 +30,11 @@ export interface ServiceHostOptions {
     prepare?: () => Promise<void>;
     createInstance: () => Promise<Service | { service: Service; baseUrl?: string }>;
     onRegistryClaimed?: (ctx: ServiceHostContext) => Promise<void>;
-    startSupervisors?: () => void | Promise<void>;
+    startSupervisors?: (ctx: ServiceHostContext) => void | Promise<void>;
     waitUntilReady?: () => Promise<void>;
     startServer?: () => Promise<ServiceHostClosable>;
+    /** When true (default), enable file log spool for main after registry claim. */
+    enableLogSpoolAfterClaim?: boolean;
     /** Stop child processes and other local resources (not registry release). */
     onShutdown?: (signal: string) => Promise<void>;
 }
@@ -105,28 +114,31 @@ export function createServiceHost(options: ServiceHostOptions): ServiceHost {
             await options.prepare();
         }
 
-        try {
-            session = await claimServiceRegistrySlot({
-                serviceValue: options.serviceValue,
-                createInstance: async () => unwrapService(await options.createInstance()),
-            });
-        } catch (error) {
-            if (error instanceof ServiceRegistryError && error.code === "SERVICE_SLOTS_FULL") {
-                logger.critical("No EMPTY registry slot — refusing to start", {
-                    topic: logTopic,
-                    data: { serviceValue: options.serviceValue, code: error.code },
-                });
-                process.exit(1);
-            }
-            throw error;
-        }
+        session = await claimRegistrySlotOrExit({
+            serviceValue: options.serviceValue,
+            createInstance: async () => unwrapService(await options.createInstance()),
+            logger,
+            logTopic,
+        });
+
+        const hostCtx: ServiceHostContext = { service: session.service, session, serviceId: session.service.id };
 
         if (options.onRegistryClaimed != null) {
-            await options.onRegistryClaimed({ service: session.service, session });
+            await options.onRegistryClaimed(hostCtx);
+        }
+
+        const enableSpool = options.enableLogSpoolAfterClaim ?? true;
+        if (enableSpool && logSpoolEnabledFromEnv()) {
+            process.env[LOG_SPOOL_SERVICE_ID_ENV] = session.service.id;
+            await ensureLogSpoolFromEnv({
+                serviceId: session.service.id,
+                serviceValue: options.serviceValue,
+                processRole: "main",
+            });
         }
 
         if (options.startSupervisors != null) {
-            await options.startSupervisors();
+            await options.startSupervisors(hostCtx);
         }
 
         if (options.waitUntilReady != null) {