target-supabase-sdk 0.2.12 → 0.2.14

package/dist/node.js

@@ -1,14 +1,14 @@
 import { z } from 'zod';
 import { M as MAX_POLL_TARGET_LIST_SIZE, V as validateWithSchema, g as createLogger, z as pollTargetList, k as generateResponse, h as createTarget, K as supabase, w as logManager, X as createScope, d as LogLevel, Y as patchScope, J as scanTargetList, Z as withModule, l as getPossibleTarget, t as isOptimisticLockResponse, R as updateTargetDetails } from './chunks/list.api-BzbTJBsM.js';
 export { B as BaseValidator, C as CREATE_TARGET_ALREADY_EXISTS_MESSAGE, a as CategoryList, L as LOG_BATCH_LOADER_KEY, b as LOG_MIN_LEVEL_ENV_KEY, c as LOG_PERSIST_LOADER_KEY, e as MAX_TARGET_LIST_PAGE_SIZE, O as OPTIMISTIC_LOCK_ERROR_CODE, f as OPTIMISTIC_LOCK_FAILED_MESSAGE, P as PostListValidator, S as StatusCode, U as UPDATE_TARGET_NOT_FOUND_MESSAGE, i as deleteTarget, j as formatZodError, m as getTarget, n as getTargetList, o as getTargetTotalCount, p as handleSupabaseError, q as isCreateTargetAlreadyExistsError, r as isDevEnvironment, s as isOptimisticLockError, u as logDev, v as logDevGroup, x as logMinLevelFromEnv, y as patchTarget, A as postListCreate, D as postLogListCreate, E as postTarget, F as postTargetPayloadSchema, G as queryFilterSchema, H as resolveLogMinLevel, I as safeParseWithSchema, N as targetDraftSchema, Q as updateTarget, T as validateWith } from './chunks/list.api-BzbTJBsM.js';
-import { l as loadEnvFiles, b as readEnv, c as requireEnv, d as createJsonFileStateStore, a as logPersistEnabledFromEnv, e as disableLogPersist, g as getLogPersistStats, s as snapshotLogPersistReady, w as waitForLogPersistReady, f as ensureLogPersistFromEnv } from './chunks/enable-log-persist-Dl55_mv2.js';
-export { C as CLI_PROD_FLAG, S as SERVICE_ENV_PROFILE_ENV_KEY, h as SERVICE_ENV_PROFILE_PROD, i as enableLogPersist, j as envBool, k as envInt, m as envMs, n as envNumber, o as envPort, q as envProfileFromProcess, t as parseEnvFile, u as parseEnvLine, p as pinEnvProfileFromArgv, x as pollUntil, y as resolveDefaultEnvFiles, z as resolveLogPersistRegistryPath, r as resolveProjectRootByPackageName, A as resolveProjectRootFromModule, v as validateLogPersistPreloadEnv } from './chunks/enable-log-persist-Dl55_mv2.js';
-import { access, stat, readFile, mkdir, unlink, writeFile, readdir } from 'node:fs/promises';
-import { resolve, join, dirname, isAbsolute } from 'node:path';
-import { bg as sha256Hex, bl as getErrorMessage, aL as postRegisterNode, ap as patchChangeNodeStatus, N as NodeStatus, aA as patchStopNode, ax as patchNodeHeartBeat, E as EMPTY_REGISTRY_SLOT_RUNTIME_STATE, b6 as runRegistrySlotGuardCheck, aZ as registrySlotRuntimePatchFromGuardResult, c as CategoryNode, Q as evaluateBusyNodeLiveness, az as patchServiceRuntime, k as ServiceRegistryError, x as claimServiceRegistrySlot, e as CategoryRepo, R as ResultCode, bm as LOG_TOPIC_TASK, m as TASK_REPO_USAGE, a6 as getScanRemoteRepoValues, at as patchClaimTask, bn as CRITICAL_UNKNOWN_TASK_TRACE_ID, ar as patchChangeTaskStatus, o as TaskStatusAction, bo as toError, aT as postTaskSchema, bp as createTaskRow, n as TaskStatus } from './chunks/task-queue-H4mpSW8R.js';
-export { A as ApiMethod, C as CategoryConfig, a as CategoryExtraction, b as CategoryLink, d as CategoryParcel, f as CategoryService, g as CategoryTask, D as DEFAULT_SYSTEM_REGISTRY_SEED_SLOTS, L as LINK_MANIFEST_VERSION, h as LIST_MANIFEST_VERSION, P as POST_TASK_DEFAULT_MAX_ATTEMPTS, i as ParcelManager, j as PostLinkValidator, S as ServiceLifecycleStatus, l as ServiceSlotStatus, T as TARGET_SYSTEM_REGISTRY_KEY, p as apiDetailsSchema, q as appendSystemRegistrySlots, r as assertRegistrySlotAvailable, s as assertRegistrySlotOwner, t as buildEmptyServiceSlots, u as buildLinkTargetDraft, v as buildListTargetDraft, w as buildSystemRegistryConfigDetails, y as classifyNetworkError, z as countTasksByType, B as createActiveServiceLifecycle, F as createClaimedRegistrySlotRuntimeState, G as createStorageProviderRegistry, H as createUploadTracker, I as decodeLogBatch, J as decodeLogBatchList, K as defaultL3ServiceDetails, M as deleteParcel, O as deleteParcelSchema, U as fetchBinaryWithRetry, V as fetchWithRetry, W as fieldDefinitionSchema, X as flattenLogBatch, Y as flattenLogBatches, Z as formatNetworkError, _ as getApi, $ as getApiSchema, a0 as getConfig, a1 as getConfigSchema, a2 as getExtraction, a3 as getExtractionSchema, a4 as getParcel, a5 as getParcelSchema, a7 as getScanRemoteRepoValuesSchema, a8 as getService, a9 as getServiceSchema, aa as getTargetSystemRegistry, ab as getValueAtPath, ac as installChunkFetchRegistry, ad as isHttpUrl, ae as isLocalFilesystemPath, af as isLogBatchList, ag as isLogEntry, ah as isOpaqueChunkUrl, ai as isRetryableHttpStatus, aj as linkTargetDraftBuildInputSchema, ak as parcelDetailsSchema, al as parseLogBatchMeta, am as parseProviderPrefixedUrl, an as parseServiceSlot, ao as parseServiceSlots, aq as patchChangeNodeStatusSchema, as as patchChangeTaskStatusSchema, au as patchClaimTaskSchema, av as patchExtractionObjects, aw as patchExtractionObjectsSchema, ay as patchNodeHeartBeatSchema, aB as patchStopNodeSchema, aC as patchTaskProgress, aD as patchTaskProgressSchema, aE as postApi, aF as postApiSchema, aG as postExtraction, aH as postExtractionSchema, aI as postLinkCreate, aJ as postParcel, aK as postParcelSchema, aM as postRegisterNodeSchema, aN as postService, aO as postServiceInstance, aP as postServiceSchema, aQ as postSystemRegistryConfig, aR as postSystemRegistryConfigSchema, aS as postTask, aU as postTaskWithRetry, aV as publishParcel, aW as registerProviderChunkResolver, aX as registerService, aY as registerServiceAtStartup, a_ as releaseSystemRegistrySlots, a$ as requestHasBody, b0 as resetSystemRegistryConfig, b1 as resetSystemRegistryConfigSchema, b2 as resolveActiveRegistryServiceId, b3 as resolveFetchUrl, b4 as restoreParcel, b5 as restoreParcelById, b7 as sanitizeFileName, b8 as sanitizeParcelFileName, b9 as scanExtractionList, ba as scanExtractionListSchema, bb as schemaDefinitionSchema, bc as serviceDetailsSchema, bd as serviceLifecycleSchema, be as serviceNodeSnapshotSchema, bf as serviceRuntimeSchema, bh as summarizeTaskQueue, bi as systemRegistrySeedSlotSchema, bj as unregisterService, bk as unregisterServiceAtShutdown } from './chunks/task-queue-H4mpSW8R.js';
+import { l as loadEnvFiles, b as readEnv, c as requireEnv, d as resolveLogSpoolSpawnEnvForLabel, e as resolveLogSpoolConfig, f as resolveLogSpoolRoot, g as resolveAllLogSpoolProcessRoles, h as logSpoolProcessDir, s as spoolLogger, i as parseLogSpoolBatchFilename, j as computeLogBatchIdempotencyKey, k as buildLogListDraft, n as postLogBatch, a as logSpoolEnabledFromEnv, o as logSpoolConfigFromEnv, L as LOG_SPOOL_SERVICE_ID_ENV, q as ensureLogSpoolFromEnv, t as shutdownLogSpoolFromEnv, u as getLogSpoolStats } from './chunks/enable-C7lFooTG.js';
+export { C as CLI_PROD_FLAG, S as SERVICE_ENV_PROFILE_ENV_KEY, w as SERVICE_ENV_PROFILE_PROD, x as buildLogSpoolSpawnEnv, y as envBool, z as envInt, A as envMs, B as envNumber, D as envPort, E as envProfileFromProcess, F as resolveDefaultEnvFiles, r as resolveProjectRootByPackageName, G as resolveProjectRootFromModule, v as validateLogSpoolPreloadEnv } from './chunks/enable-C7lFooTG.js';
+import { randomBytes, createHash } from 'node:crypto';
+import { readFile, unlink, mkdir, writeFile, rename, access, stat, readdir, constants } from 'node:fs/promises';
+import { dirname, resolve, join, isAbsolute } from 'node:path';
+import { bh as sha256Hex, bm as getErrorMessage, bn as LOG_TOPIC_NODE, aL as postRegisterNode, ap as patchChangeNodeStatus, N as NodeStatus, aA as patchStopNode, ax as patchNodeHeartBeat, E as EMPTY_REGISTRY_SLOT_RUNTIME_STATE, b7 as runRegistrySlotGuardCheck, aZ as registrySlotRuntimePatchFromGuardResult, c as CategoryNode, Q as evaluateBusyNodeLiveness, az as patchServiceRuntime, ag as isLogEntry, x as claimServiceRegistrySlot, k as ServiceRegistryError, e as CategoryRepo, R as ResultCode, bo as LOG_TOPIC_TASK, m as TASK_REPO_USAGE, a6 as getScanRemoteRepoValues, at as patchClaimTask, bp as CRITICAL_UNKNOWN_TASK_TRACE_ID, ar as patchChangeTaskStatus, o as TaskStatusAction, bq as toError, aT as postTaskSchema, br as createTaskRow, n as TaskStatus } from './chunks/task-queue-qSnsfiIg.js';
+export { A as ApiMethod, C as CategoryConfig, a as CategoryExtraction, b as CategoryLink, d as CategoryParcel, f as CategoryService, g as CategoryTask, D as DEFAULT_SYSTEM_REGISTRY_SEED_SLOTS, L as LINK_MANIFEST_VERSION, h as LIST_MANIFEST_VERSION, P as POST_TASK_DEFAULT_MAX_ATTEMPTS, i as ParcelManager, j as PostLinkValidator, S as ServiceLifecycleStatus, l as ServiceSlotStatus, T as TARGET_SYSTEM_REGISTRY_KEY, p as apiDetailsSchema, q as appendSystemRegistrySlots, r as assertRegistrySlotAvailable, s as assertRegistrySlotOwner, t as buildEmptyServiceSlots, u as buildLinkTargetDraft, v as buildListTargetDraft, w as buildSystemRegistryConfigDetails, y as classifyNetworkError, z as countTasksByType, B as createActiveServiceLifecycle, F as createClaimedRegistrySlotRuntimeState, G as createStorageProviderRegistry, H as createUploadTracker, I as decodeLogBatch, J as decodeLogBatchList, K as defaultL3ServiceDetails, M as deleteParcel, O as deleteParcelSchema, U as fetchBinaryWithRetry, V as fetchWithRetry, W as fieldDefinitionSchema, X as flattenLogBatch, Y as flattenLogBatches, Z as formatNetworkError, _ as getApi, $ as getApiSchema, a0 as getConfig, a1 as getConfigSchema, a2 as getExtraction, a3 as getExtractionSchema, a4 as getParcel, a5 as getParcelSchema, a7 as getScanRemoteRepoValuesSchema, a8 as getService, a9 as getServiceSchema, aa as getTargetSystemRegistry, ab as getValueAtPath, ac as installChunkFetchRegistry, ad as isHttpUrl, ae as isLocalFilesystemPath, af as isLogBatchList, ah as isOpaqueChunkUrl, ai as isRetryableHttpStatus, aj as linkTargetDraftBuildInputSchema, ak as parcelDetailsSchema, al as parseLogBatchMeta, am as parseProviderPrefixedUrl, an as parseServiceSlot, ao as parseServiceSlots, aq as patchChangeNodeStatusSchema, as as patchChangeTaskStatusSchema, au as patchClaimTaskSchema, av as patchExtractionObjects, aw as patchExtractionObjectsSchema, ay as patchNodeHeartBeatSchema, aB as patchStopNodeSchema, aC as patchTaskProgress, aD as patchTaskProgressSchema, aE as postApi, aF as postApiSchema, aG as postExtraction, aH as postExtractionSchema, aI as postLinkCreate, aJ as postParcel, aK as postParcelSchema, aM as postRegisterNodeSchema, aN as postService, aO as postServiceInstance, aP as postServiceSchema, aQ as postSystemRegistryConfig, aR as postSystemRegistryConfigSchema, aS as postTask, aU as postTaskWithRetry, aV as publishParcel, aW as registerProviderChunkResolver, aX as registerService, aY as registerServiceAtStartup, a_ as releaseSystemRegistrySlots, a$ as releaseSystemRegistrySlotsByServiceId, b0 as requestHasBody, b1 as resetSystemRegistryConfig, b2 as resetSystemRegistryConfigSchema, b3 as resolveActiveRegistryServiceId, b4 as resolveFetchUrl, b5 as restoreParcel, b6 as restoreParcelById, b8 as sanitizeFileName, b9 as sanitizeParcelFileName, ba as scanExtractionList, bb as scanExtractionListSchema, bc as schemaDefinitionSchema, bd as serviceDetailsSchema, be as serviceLifecycleSchema, bf as serviceNodeSnapshotSchema, bg as serviceRuntimeSchema, bi as summarizeTaskQueue, bj as systemRegistrySeedSlotSchema, bk as unregisterService, bl as unregisterServiceAtShutdown } from './chunks/task-queue-qSnsfiIg.js';
 import { spawn } from 'node:child_process';
-import { createHash } from 'node:crypto';
 import { tmpdir } from 'node:os';
 import { pathToFileURL } from 'node:url';
 import 'lodash-es';
@@ -119,6 +119,98 @@ function publicBaseUrlFromEnv(port, options) {
     return `http://localhost:${port}`;
 }
 
+/** Per-file write queue — serializes read-modify-write for a single JSON path within one process. */
+const writeChains = new Map();
+function withSerializedFileWrites(filePath, operation) {
+    const previous = writeChains.get(filePath) ?? Promise.resolve();
+    const next = previous.then(operation, operation);
+    writeChains.set(filePath, next.then(() => undefined, () => undefined));
+    return next;
+}
+
+function mergeWithNested(defaults, current, patch, nestedKeys) {
+    const merged = {
+        ...defaults,
+        ...current,
+        ...patch,
+    };
+    for (const key of nestedKeys) {
+        const defaultNested = defaults[key];
+        if (defaultNested != null && typeof defaultNested === "object") {
+            merged[key] = {
+                ...defaultNested,
+                ...current?.[key],
+                ...patch[key],
+            };
+        }
+    }
+    return merged;
+}
+async function atomicWriteJson(filePath, data) {
+    await mkdir(dirname(filePath), { recursive: true });
+    const content = `${JSON.stringify(data, null, 2)}\n`;
+    JSON.parse(content);
+    const tempPath = `${filePath}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+    try {
+        await writeFile(tempPath, content, "utf8");
+        await rename(tempPath, filePath);
+    }
+    catch (error) {
+        await unlink(tempPath).catch(() => undefined);
+        throw error;
+    }
+}
+/** JSON file-backed state with optional nested key merge and atomic writes. */
+function createJsonFileStateStore(options) {
+    const { filePath, defaultState, nestedKeys = [], updatedAtKey } = options;
+    function touchUpdatedAt(state) {
+        if (updatedAtKey == null) {
+            return state;
+        }
+        return {
+            ...state,
+            [updatedAtKey]: new Date().toISOString(),
+        };
+    }
+    async function readFromDisk() {
+        try {
+            const raw = await readFile(filePath, "utf8");
+            const parsed = JSON.parse(raw);
+            return mergeWithNested(defaultState, parsed, {}, nestedKeys);
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                return mergeWithNested(defaultState, {}, {}, nestedKeys);
+            }
+            if (error instanceof SyntaxError) {
+                await unlink(filePath).catch(() => undefined);
+                return mergeWithNested(defaultState, {}, {}, nestedKeys);
+            }
+            throw error;
+        }
+    }
+    return {
+        read() {
+            return readFromDisk();
+        },
+        write(patch) {
+            return withSerializedFileWrites(filePath, async () => {
+                const current = await readFromDisk();
+                const next = touchUpdatedAt(mergeWithNested(defaultState, current, patch, nestedKeys));
+                await atomicWriteJson(filePath, next);
+                return next;
+            });
+        },
+        reset() {
+            return withSerializedFileWrites(filePath, async () => {
+                const next = touchUpdatedAt({ ...defaultState });
+                await atomicWriteJson(filePath, next);
+                return next;
+            });
+        },
+    };
+}
+
 /** Copy a Node.js Buffer view to a standalone ArrayBuffer. */
 function nodeBufferToArrayBuffer(nodeBuffer) {
     return nodeBuffer.buffer.slice(nodeBuffer.byteOffset, nodeBuffer.byteOffset + nodeBuffer.byteLength);
@@ -196,7 +288,6 @@ const formatHeartbeat = (timestamp) => {
     return `${absolute} (${relative})`;
 };
 
-const LOG_TOPIC_NODE = "node";
 const LOG_TOPIC_COMMAND = "command";
 const LOG_TOPIC_PROCESS = "process";
 /**
@@ -265,6 +356,22 @@ class BaseNodeRuntime {
     getLoopIntervalMs() {
         return getRandomInterval();
     }
+    /**
+     * When true, the main loop skips commands and {@link runLoopSteps} (heartbeat only).
+     * Used by the L3 guard process while waiting for connectivity to recover.
+     */
+    isSilenced() {
+        return false;
+    }
+    /**
+     * Consecutive heartbeat failures reached {@link HEARTBEAT_FAILURE_THRESHOLD}.
+     * Default: shut down the node. Override to wait for recovery instead of exiting.
+     */
+    async onHealthCheckFailed(_ctx) {
+        this.requestShutdown("heartbeat:consecutive-failures");
+    }
+    /** Heartbeat succeeded while {@link isSilenced} is true. Default: no-op. */
+    async onHeartbeatRecovered(_ctx) { }
     getLogNodeId() {
         return this.localNodeId ?? BaseNodeRuntime.NODE_ID_PENDING_ASSIGNMENT;
     }
@@ -421,7 +528,9 @@ class BaseNodeRuntime {
                 data: { nodeId, loopCount: this.loopCount },
             });
             try {
-                await this.batchCommand(loopCtx);
+                if (!this.isSilenced()) {
+                    await this.batchCommand(loopCtx);
+                }
                 if (this.isShuttingDown()) {
                     iterLogger.debug("節點關閉中，跳過本輪剩餘步驟", { topic: LOG_TOPIC_NODE });
                     break;
@@ -431,7 +540,9 @@ class BaseNodeRuntime {
                     iterLogger.debug("節點關閉中，跳過本輪剩餘步驟", { topic: LOG_TOPIC_NODE });
                     break;
                 }
-                await this.runLoopSteps(loopCtx, heartbeatOk);
+                if (!this.isSilenced()) {
+                    await this.runLoopSteps(loopCtx, heartbeatOk);
+                }
             }
             catch (error) {
                 iterLogger.critical(`主循環第 ${this.loopCount} 輪遇到未知錯誤`, {
@@ -543,11 +654,11 @@ class BaseNodeRuntime {
                 threshold: BaseNodeRuntime.HEARTBEAT_FAILURE_THRESHOLD,
             };
             if (failureCount >= BaseNodeRuntime.HEARTBEAT_FAILURE_THRESHOLD) {
-                logger.critical("連續心跳失敗達上限，準備關閉節點", {
+                logger.critical("連續心跳失敗達上限", {
                     topic: LOG_TOPIC_NODE,
                     data: logData,
                 });
-                this.requestShutdown("heartbeat:consecutive-failures");
+                await this.onHealthCheckFailed(ctx);
             }
             else {
                 logger.warn("心跳更新失敗", { topic: LOG_TOPIC_NODE, data: logData });
@@ -555,6 +666,9 @@ class BaseNodeRuntime {
             return false;
         }
         this.consecutiveHeartbeatFailures = 0;
+        if (this.isSilenced()) {
+            await this.onHeartbeatRecovered(ctx);
+        }
         // Success is the steady state every loop — do not INFO-spam; failures already warn/critical.
         logger.debug("心跳更新成功", {
             topic: LOG_TOPIC_NODE,
@@ -725,12 +839,16 @@ class ManagedChildProcesses {
         if (existing != null) {
             return { child: existing, created: false };
         }
+        const logSpoolEnv = resolveLogSpoolSpawnEnvForLabel(label);
+        const childEnv = spawnOptions?.env != null
+            ? { ...process.env, ...logSpoolEnv, ...spawnOptions.env }
+            : { ...process.env, ...logSpoolEnv };
         const child = spawnTsxChild({
             projectRoot: this.projectRoot,
             entryScript,
             preloadModules: this.preloadModules,
             useTsx: spawnOptions?.useTsx ?? this.defaultUseTsx,
-            env: spawnOptions?.env != null ? { ...process.env, ...spawnOptions.env } : process.env,
+            env: childEnv,
         });
         child.on("exit", (code, signal) => {
             this.logger?.info("child exited", { topic: "process", data: { label, code, signal } });
@@ -805,6 +923,25 @@ function createManagedChildProcesses(options) {
     });
 }
 
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Poll `until()` until it returns true or `timeoutMs` elapses.
+ * @throws Error on timeout
+ */
+async function pollUntil(options) {
+    const intervalMs = options.intervalMs ?? 500;
+    const deadline = Date.now() + options.timeoutMs;
+    while (Date.now() < deadline) {
+        if (await options.until()) {
+            return;
+        }
+        await sleep(intervalMs);
+    }
+    throw new Error(`pollUntil timeout after ${options.timeoutMs}ms`);
+}
+
 /** Factory: all listed env keys must be non-empty. */
 function createRequiredEnvCheck(name, keys, options) {
     return () => {
@@ -874,9 +1011,26 @@ async function runReadinessChecks(checks) {
     };
 }
 
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+/** Run readiness checks, persist report via callback, fail-fast when not ok. */
+async function runReadinessGate(input) {
+    const { checks, onReport, logger, logTopic = "guard" } = input;
+    logger.info("Running readiness checks", { topic: logTopic });
+    const report = await runReadinessChecks(checks);
+    await onReport(report);
+    if (!report.ok) {
+        logger.error("Readiness checks failed", {
+            topic: logTopic,
+            data: { message: report.message, checks: report.checks },
+        });
+        throw new Error(report.message ?? "Readiness checks failed");
+    }
+    logger.debug("Readiness checks passed", {
+        topic: logTopic,
+        data: { checks: report.checks.map((check) => check.name) },
+    });
+    return report;
 }
+
 /**
  * Poll {@link ServiceReadyGate} until ready, fail fast on `failed`, or timeout.
  * Returns the final ready snapshot.
@@ -884,25 +1038,37 @@ function sleep(ms) {
 async function waitForServiceReady(gate, options) {
     const pollMs = options.pollMs ?? 500;
     const defaultFailureMessage = options.failureMessage ?? "Readiness checks failed";
-    const deadline = Date.now() + options.timeoutMs;
     let last = { failed: false, ready: false };
-    while (Date.now() < deadline) {
-        last = await gate.read();
+    try {
+        await pollUntil({
+            timeoutMs: options.timeoutMs,
+            intervalMs: pollMs,
+            until: async () => {
+                last = await gate.read();
+                if (last.failed) {
+                    throw new Error(last.failureMessage ?? defaultFailureMessage);
+                }
+                return last.ready;
+            },
+        });
+    }
+    catch (error) {
         if (last.failed) {
-            throw new Error(last.failureMessage ?? defaultFailureMessage);
+            throw error instanceof Error ? error : new Error(defaultFailureMessage);
         }
-        if (last.ready) {
-            options.logger?.info("service ready", {
-                topic: "readiness",
-                data: last.readyDetail ?? {},
-            });
-            return last;
+        const isPollTimeout = error instanceof Error && error.message.startsWith("pollUntil timeout after");
+        if (!isPollTimeout) {
+            throw error;
         }
-        await sleep(pollMs);
+        const message = options.formatTimeoutError?.(last, options.timeoutMs) ??
+            `Service ready timeout after ${options.timeoutMs}ms (failed=${last.failed}, ready=${last.ready})`;
+        throw new Error(message);
     }
-    const message = options.formatTimeoutError?.(last, options.timeoutMs) ??
-        `Service ready timeout after ${options.timeoutMs}ms (failed=${last.failed}, ready=${last.ready})`;
-    throw new Error(message);
+    options.logger?.info("service ready", {
+        topic: "readiness",
+        data: last.readyDetail ?? {},
+    });
+    return last;
 }
 
 const RUNTIME_STATE_SHARD_DIR = "runtime-state";
@@ -1066,11 +1232,22 @@ function createDefaultServiceRuntimeState(options) {
         lastDecision: null,
         lastSpawnAt: null,
         spawnCount: 0,
+        mode: "healthy",
+        silentEnteredAt: null,
+        silentLastHeartbeatAt: null,
+        silentBackoffMs: 0,
+        silentConsecutiveFailures: 0,
+        silentRecoveryAttempt: 0,
+        silentEvents: [],
     };
     const scheduler = {
         lastTickAt: null,
         lastPostedCount: 0,
         lastFired: {},
+        pid: null,
+        spawnedAt: null,
+        ready: false,
+        readyAt: null,
     };
     const worker = {
         pid: null,
@@ -1489,6 +1666,21 @@ async function runServiceGuardTick(input) {
 
 /** Default TriggerManager runner key for {@link registerServiceGuardRunner}. */
 const SERVICE_GUARD_RUNNER_KEY = "service-guard";
+/** True when the guard slice is serving traffic (`mode` omitted = legacy healthy). */
+function isGuardAvailable(guard) {
+    return guard.mode == null || guard.mode === "healthy";
+}
+/**
+ * Seconds for `Retry-After` when the guard is not serving traffic.
+ * `null` when {@link isGuardAvailable} is true.
+ */
+function guardRetryAfterSec(guard) {
+    if (isGuardAvailable(guard)) {
+        return null;
+    }
+    const backoffMs = guard.silentBackoffMs > 0 ? guard.silentBackoffMs : 15_000;
+    return Math.max(1, Math.ceil(backoffMs / 1000));
+}
 
 async function runServiceGuardRunner(ctx, options) {
     const { loopTraceId, nodeId, logger } = ctx;
@@ -1534,24 +1726,312 @@ function registerServiceGuardRunner(options) {
     });
 }
 
-/** Run readiness checks, persist report via callback, fail-fast when not ok. */
-async function runReadinessGate(input) {
-    const { checks, onReport, logger, logTopic = "guard" } = input;
-    logger.info("Running readiness checks", { topic: logTopic });
-    const report = await runReadinessChecks(checks);
-    await onReport(report);
-    if (!report.ok) {
-        logger.error("Readiness checks failed", {
-            topic: logTopic,
-            data: { message: report.message, checks: report.checks },
+const UPLOAD_LANE = "slow";
+/** Per serviceId — guard collect-log tick runs GC at most once per `gc.intervalMs`. */
+const lastGcAtMsByServiceId = new Map();
+async function pathExists$1(filePath) {
+    try {
+        await access(filePath, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readBatchTmpFile(tmpPath) {
+    try {
+        const raw = await readFile(tmpPath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed.entries) || parsed.entries.length === 0) {
+            return null;
+        }
+        const entries = parsed.entries.filter(isLogEntry);
+        if (entries.length === 0) {
+            return null;
+        }
+        return { entries, meta: parsed.meta };
+    }
+    catch {
+        return null;
+    }
+}
+function processMetaKey(serviceId, processRole) {
+    return `${serviceId}:${processRole}`;
+}
+async function uploadTmpBatch(input) {
+    const parsed = parseLogSpoolBatchFilename(input.fileName);
+    if (parsed == null) {
+        spoolLogger.warn("collect-log skipped — invalid tmp filename", { fileName: input.fileName });
+        return "failed";
+    }
+    const jsonFileName = input.fileName.replace(/\.tmp$/, ".json");
+    const jsonPath = join(logSpoolProcessDir(input.spoolRoot, input.serviceId, input.processRole), jsonFileName);
+    if (await pathExists$1(jsonPath)) {
+        try {
+            await unlink(input.tmpPath);
+            spoolLogger.info("collect-log removed orphan tmp (json exists)", {
+                tmpPath: input.tmpPath,
+                jsonPath,
+            });
+        }
+        catch {
+            // best-effort
+        }
+        return "skipped";
+    }
+    const batch = await readBatchTmpFile(input.tmpPath);
+    if (batch == null) {
+        spoolLogger.warn("collect-log skipped — tmp failed validation", {
+            tmpPath: input.tmpPath,
+            fileName: input.fileName,
         });
-        throw new Error(report.message ?? "Readiness checks failed");
+        try {
+            await unlink(input.tmpPath);
+            spoolLogger.info("collect-log removed invalid tmp", { tmpPath: input.tmpPath });
+        }
+        catch {
+            // best-effort
+        }
+        return "failed";
     }
-    logger.debug("Readiness checks passed", {
-        topic: logTopic,
-        data: { checks: report.checks.map((check) => check.name) },
+    const processKey = processMetaKey(input.serviceId, input.processRole);
+    // TODO: `lane` is legacy transport metadata — scheduled for removal; fixed to "slow" for downstream decode compatibility.
+    const idempotencyKey = computeLogBatchIdempotencyKey({
+        service: input.serviceValue,
+        process: processKey,
+        lane: UPLOAD_LANE,
+        entries: batch.entries,
+    });
+    const draft = buildLogListDraft({
+        service: input.serviceValue,
+        process: processKey,
+        lane: UPLOAD_LANE,
+        idempotencyKey,
+        entries: batch.entries,
+    });
+    try {
+        await postLogBatch(draft, input.postTimeoutMs);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        spoolLogger.error("collect-log upload failed", {
+            fileName: input.fileName,
+            processRole: input.processRole,
+            error: message,
+        });
+        return "failed";
+    }
+    try {
+        await rename(input.tmpPath, jsonPath);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        spoolLogger.error("collect-log rename tmp→json failed after upload", {
+            tmpPath: input.tmpPath,
+            jsonPath,
+            error: message,
+        });
+        return "failed";
+    }
+    spoolLogger.info("collect-log uploaded batch", {
+        processRole: input.processRole,
+        fileName: jsonFileName,
+        entryCount: batch.entries.length,
+        idempotencyKey,
+    });
+    return "uploaded";
+}
+async function gcTmpFiles(input) {
+    const processDir = logSpoolProcessDir(input.spoolRoot, input.serviceId, input.processRole);
+    let removed = 0;
+    try {
+        const names = await readdir(processDir);
+        for (const name of names) {
+            if (!name.endsWith(".tmp")) {
+                continue;
+            }
+            const parsed = parseLogSpoolBatchFilename(name);
+            if (parsed == null) {
+                continue;
+            }
+            if (input.nowMs - parsed.timestampMs <= input.tmpRetentionMs) {
+                continue;
+            }
+            try {
+                await unlink(join(processDir, name));
+                removed += 1;
+                spoolLogger.info("collect-log gc removed stale tmp", {
+                    fileName: name,
+                    processRole: input.processRole,
+                });
+            }
+            catch {
+                // best-effort
+            }
+        }
+    }
+    catch {
+        // directory may not exist yet
+    }
+    return removed;
+}
+async function gcSyncedJsonFiles(input) {
+    let removed = 0;
+    for (const processRole of resolveAllLogSpoolProcessRoles()) {
+        const processDir = logSpoolProcessDir(input.spoolRoot, input.serviceId, processRole);
+        let names = [];
+        try {
+            names = await readdir(processDir);
+        }
+        catch {
+            continue;
+        }
+        for (const name of names) {
+            if (!name.endsWith(".json")) {
+                continue;
+            }
+            if (parseLogSpoolBatchFilename(name) == null) {
+                continue;
+            }
+            const jsonPath = join(processDir, name);
+            try {
+                const fileStat = await stat(jsonPath);
+                if (input.nowMs - fileStat.mtimeMs <= input.syncedRetentionMs) {
+                    continue;
+                }
+                await unlink(jsonPath);
+                removed += 1;
+                spoolLogger.info("collect-log gc removed synced json", {
+                    fileName: name,
+                    processRole,
+                });
+            }
+            catch {
+                // best-effort
+            }
+        }
+    }
+    return removed;
+}
+function shouldRunGc(serviceId, nowMs, intervalMs) {
+    const lastAt = lastGcAtMsByServiceId.get(serviceId) ?? 0;
+    if (nowMs - lastAt < intervalMs) {
+        return false;
+    }
+    lastGcAtMsByServiceId.set(serviceId, nowMs);
+    return true;
+}
+/**
+ * Guard-only: upload pending `.tmp` batches, rename to `.json`, then periodic GC.
+ * Upload completion is implied by `.json` presence; no sync-state file.
+ */
+async function runCollectLogTick(input) {
+    const config = resolveLogSpoolConfig(input.config);
+    const spoolRoot = input.spoolRoot ?? resolveLogSpoolRoot();
+    const nowMs = input.nowMs ?? Date.now();
+    const result = {
+        uploaded: 0,
+        skipped: 0,
+        failed: 0,
+        gcTmpRemoved: 0,
+        gcSyncedRemoved: 0,
+    };
+    for (const processRole of resolveAllLogSpoolProcessRoles()) {
+        const processDir = logSpoolProcessDir(spoolRoot, input.serviceId, processRole);
+        let names = [];
+        try {
+            names = await readdir(processDir);
+        }
+        catch {
+            continue;
+        }
+        for (const name of names) {
+            if (!name.endsWith(".tmp")) {
+                continue;
+            }
+            const status = await uploadTmpBatch({
+                serviceId: input.serviceId,
+                serviceValue: input.serviceValue,
+                processRole,
+                tmpPath: join(processDir, name),
+                fileName: name,
+                spoolRoot,
+                postTimeoutMs: config.writer.postTimeoutMs,
+            });
+            if (status === "uploaded") {
+                result.uploaded += 1;
+            }
+            else if (status === "skipped") {
+                result.skipped += 1;
+            }
+            else {
+                result.failed += 1;
+            }
+        }
+    }
+    if (shouldRunGc(input.serviceId, nowMs, config.gc.intervalMs)) {
+        for (const processRole of resolveAllLogSpoolProcessRoles()) {
+            result.gcTmpRemoved += await gcTmpFiles({
+                spoolRoot,
+                serviceId: input.serviceId,
+                processRole,
+                tmpRetentionMs: config.gc.tmpRetentionMs,
+                nowMs,
+            });
+        }
+        result.gcSyncedRemoved = await gcSyncedJsonFiles({
+            spoolRoot,
+            serviceId: input.serviceId,
+            syncedRetentionMs: config.gc.syncedRetentionMs,
+            nowMs,
+        });
+    }
+    if (result.uploaded > 0 || result.failed > 0) {
+        spoolLogger.info("collect-log tick complete", { ...result, serviceId: input.serviceId });
+    }
+    return result;
+}
+
+const COLLECT_LOG_RUNNER_KEY = "collect-log";
+/**
+ * Guard process only — uploads `.tmp` spool batches and runs GC.
+ * Register before {@link TriggerNode.start} (e.g. in {@link ServiceGuardNode.create}).
+ */
+function registerCollectLogRunner(options) {
+    if (!logSpoolEnabledFromEnv()) {
+        return;
+    }
+    const config = logSpoolConfigFromEnv();
+    const intervalMs = options.intervalMs ?? config.collectIntervalMs;
+    TriggerManager.registerRunner({
+        key: options.runnerKey ?? COLLECT_LOG_RUNNER_KEY,
+        intervalMs,
+        initialDelayMs: options.initialDelayMs ?? 0,
+        retryCount: 1,
+        fn: async (ctx) => {
+            const serviceId = await options.getServiceId();
+            if (serviceId == null) {
+                ctx.logger.warn("collect-log skipped — serviceId unavailable", { topic: LOG_TOPIC_TRIGGER });
+                return;
+            }
+            const result = await runCollectLogTick({
+                serviceId,
+                serviceValue: options.serviceValue,
+                spoolRoot: options.spoolRoot,
+                config,
+            });
+            if (result.uploaded > 0 || result.failed > 0) {
+                ctx.logger.info("collect-log runner finished", {
+                    topic: LOG_TOPIC_TRIGGER,
+                    data: result,
+                });
+            }
+        },
+    });
+    spoolLogger.info("collect-log runner registered", {
+        intervalMs,
+        serviceValue: options.serviceValue,
     });
-    return report;
 }
 
 /**
@@ -1624,30 +2104,74 @@ class TriggerNode extends BaseNodeRuntime {
     }
 }
 
+const SILENT_BACKOFF_MS = [15_000, 30_000, 60_000, 120_000, 240_000, 300_000];
+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 {
     options;
+    businessReadyTimeoutMs;
+    mode = "healthy";
+    silentBackoffIndex = 0;
+    silentEvents = [];
+    recoverPromise = null;
     constructor(options) {
         super({
             requireRunners: true,
             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) {
         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);
     }
+    isSilenced() {
+        return this.mode !== "healthy";
+    }
+    getLoopIntervalMs() {
+        if (this.mode === "silent") {
+            return SILENT_BACKOFF_MS[this.silentBackoffIndex] ?? 300_000;
+        }
+        return super.getLoopIntervalMs();
+    }
+    async onHealthCheckFailed(_ctx) {
+        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");
+    }
+    async onHeartbeatRecovered(ctx) {
+        if (this.mode !== "silent") {
+            return;
+        }
+        await this.recoverFromSilent(ctx);
+    }
     async onBeforeRegisterNode(nodeLogger) {
         await runReadinessGate({
             checks: this.options.readinessChecks,
@@ -1656,11 +2180,298 @@ class ServiceGuardNode extends TriggerNode {
             logTopic: this.options.logTopic,
         });
         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",
+        });
+    }
+    async runLoopSteps(ctx, heartbeatOk) {
+        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) },
+            });
+        }
+    }
+    silentConsecutiveFailures() {
+        return this.silentBackoffIndex + 1;
+    }
+    bumpSilentBackoff() {
+        if (this.silentBackoffIndex < SILENT_BACKOFF_MS.length - 1) {
+            this.silentBackoffIndex += 1;
+        }
+    }
+    async enterSilent(reason) {
+        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) },
+            });
+        }
+    }
+    async recoverFromSilent(ctx) {
+        if (this.recoverPromise != null) {
+            return this.recoverPromise;
+        }
+        this.recoverPromise = this.runRecover(ctx).finally(() => {
+            this.recoverPromise = null;
+        });
+        return this.recoverPromise;
+    }
+    async runRecover(ctx) {
+        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",
+        });
+    }
+    async waitUntilBusinessReady() {
+        try {
+            await pollUntil({
+                timeoutMs: this.businessReadyTimeoutMs,
+                intervalMs: 500,
+                until: () => this.options.isBusinessReady(),
+            });
+        }
+        catch {
+            throw new Error(`Business nodes not ready within ${this.businessReadyTimeoutMs}ms`);
+        }
+    }
+    pushEvent(type, detail) {
+        this.silentEvents = [...this.silentEvents, { at: new Date().toISOString(), type, detail }].slice(-32);
+    }
+    async persistGuard(patch) {
+        try {
+            await this.options.guardRunner.onGuardPatch(patch);
+        }
+        catch {
+            // best-effort — disk/runtime state must not take down the guard loop
+        }
+    }
+    createGuardLogger() {
+        return createLogger({ module: "service-guard" });
+    }
+}
+
+const WORKER_SCRIPT = "./dist/processes/worker.js";
+const GUARD_SCRIPT = "./dist/processes/guard.js";
+const SCHEDULER_SCRIPT = "./dist/processes/scheduler.js";
+function defaultSpawnEnv(label) {
+    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).
+ */
+function createL3ChildLauncher(options) {
+    const { childProcesses, readRuntimeState, writeRuntimeState } = options;
+    const spawnEnv = options.spawnEnv ?? defaultSpawnEnv;
+    function nowIso() {
+        return new Date().toISOString();
+    }
+    async function spawnTaskWorker(reason) {
+        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() {
+        return childProcesses.spawn("guard", GUARD_SCRIPT, { env: spawnEnv("guard") }).child;
+    }
+    async function spawnScheduler(reason) {
+        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) {
+        await spawnScheduler(reason);
+        await spawnTaskWorker(reason);
+    }
+    async function stopBusinessNodes() {
+        await childProcesses.stopAll();
+        await writeRuntimeState({
+            worker: {
+                pid: null,
+                ready: false,
+                readyAt: null,
+                registeredTasks: [],
+            },
+            scheduler: {
+                pid: null,
+                ready: false,
+                readyAt: null,
+            },
+        });
+    }
+    async function isBusinessReady() {
+        const state = await readRuntimeState();
+        return state.worker.ready && state.scheduler.ready;
+    }
+    async function stopChildProcesses() {
+        const state = await readRuntimeState();
+        const extraPids = [state.worker.pid, state.scheduler.pid].filter((pid) => pid != null);
+        await childProcesses.stopAll({ extraPids });
+    }
+    return {
+        spawnGuard,
+        spawnTaskWorker,
+        spawnScheduler,
+        spawnBusinessNodes,
+        stopBusinessNodes,
+        isBusinessReady,
+        stopChildProcesses,
+    };
+}
+
+/**
+ * Claim a registry slot, or `process.exit(1)` when no EMPTY slot remains.
+ * Other errors propagate.
+ */
+async function claimRegistrySlotOrExit(input) {
+    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;
     }
 }
 
@@ -1719,27 +2530,27 @@ function createServiceHost(options) {
         if (options.prepare != null) {
             await options.prepare();
         }
-        try {
-            session = await claimServiceRegistrySlot({
+        session = await claimRegistrySlotOrExit({
+            serviceValue: options.serviceValue,
+            createInstance: async () => unwrapService(await options.createInstance()),
+            logger,
+            logTopic,
+        });
+        const hostCtx = { service: session.service, session, serviceId: session.service.id };
+        if (options.onRegistryClaimed != null) {
+            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,
-                createInstance: async () => unwrapService(await options.createInstance()),
+                processRole: "main",
             });
         }
-        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;
-        }
-        if (options.onRegistryClaimed != null) {
-            await options.onRegistryClaimed({ service: session.service, session });
-        }
         if (options.startSupervisors != null) {
-            await options.startSupervisors();
+            await options.startSupervisors(hostCtx);
         }
         if (options.waitUntilReady != null) {
             await options.waitUntilReady();
@@ -1783,23 +2594,12 @@ async function runSingleProcessService(options) {
     if (options.prepare != null) {
         await options.prepare();
     }
-    let session = null;
-    try {
-        session = await claimServiceRegistrySlot({
-            serviceValue: options.serviceValue,
-            createInstance: 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;
-    }
+    const session = await claimRegistrySlotOrExit({
+        serviceValue: options.serviceValue,
+        createInstance: options.createInstance,
+        logger,
+        logTopic,
+    });
     try {
         await options.run({ service: session.service, session });
     }
@@ -2265,58 +3065,66 @@ const RepoManager = {
     clearRepoScriptModuleCache,
 };
 
-/**
- * Bind service-specific log-persist registry settings (process list, paths, timeouts).
- * Each L3 service exports one instance from `src/startup/log-persist.ts`.
- */
-function createLogPersistCoordinator(options) {
-    const { service, registryFilePath, expectedProcesses, readyTimeoutMs } = options;
+function createLogSpoolCoordinator(options) {
+    const { serviceValue, serviceId } = options;
     return {
         isEnabled() {
-            return logPersistEnabledFromEnv();
+            return logSpoolEnabledFromEnv();
         },
-        getRegistryFilePath() {
-            return registryFilePath;
+        getServiceId() {
+            return serviceId;
         },
         registerProcess(process) {
-            return ensureLogPersistFromEnv({
-                process,
-                service,
-                registryFilePath,
-            });
-        },
-        waitForAllProcessesReady() {
-            return waitForLogPersistReady({
-                registryFilePath,
-                service,
-                expectedProcesses: [...expectedProcesses],
-                timeoutMs: readyTimeoutMs,
-            });
-        },
-        async snapshotProcessesReady() {
-            if (!logPersistEnabledFromEnv()) {
-                return null;
-            }
-            return snapshotLogPersistReady({
-                registryFilePath,
-                expectedProcesses: [...expectedProcesses],
+            return ensureLogSpoolFromEnv({
+                serviceValue,
+                serviceId,
+                processRole: process,
             });
         },
-        getPersistStats() {
-            if (!logPersistEnabledFromEnv()) {
+        getWriterStats() {
+            if (!logSpoolEnabledFromEnv()) {
                 return null;
             }
-            return getLogPersistStats();
+            return getLogSpoolStats();
         },
-        async shutdownLogPersist() {
-            if (!logPersistEnabledFromEnv()) {
+        async shutdownLogSpool() {
+            if (!logSpoolEnabledFromEnv()) {
                 return;
             }
-            await disableLogPersist();
+            await shutdownLogSpoolFromEnv();
         },
     };
 }
 
+/** Whether file log spool is enabled (`LOG_PERSIST_ENABLED=true`). */
+function isLogSpoolEnabled(env = process.env) {
+    return logSpoolEnabledFromEnv(env);
+}
+/**
+ * Guard / scheduler / worker (and extra roles) — enable writer from spawn env.
+ * Main is enabled by `createServiceHost` after registry claim.
+ */
+async function enableLogSpoolFromEnvInChild() {
+    if (!logSpoolEnabledFromEnv()) {
+        return;
+    }
+    await ensureLogSpoolFromEnv();
+}
+/** Writer buffer stats when spool enabled; `null` when disabled. Typical use: main observability. */
+function getMainLogSpoolWriterStats() {
+    if (!logSpoolEnabledFromEnv()) {
+        return null;
+    }
+    return getLogSpoolStats();
+}
+/** Flush memory buffer and disable writer when spool enabled; no-op otherwise. */
+async function shutdownLogSpool() {
+    if (!logSpoolEnabledFromEnv()) {
+        return;
+    }
+    await shutdownLogSpoolFromEnv();
+}
+
 const EMPTY_RESULT = {
     status: "not_configured",
     registered: [],
@@ -3228,5 +4036,5 @@ const patchTriggerFired = validateWithSchema(patchTriggerFiredSchema, "patchTrig
     }
 });
 
-export { BaseNodeRuntime, CategoryCommand, CategoryNode, CategoryRepo, CategoryTrigger, CommandType, EMPTY_REGISTRY_SLOT_RUNTIME_STATE, LOG_TOPIC_TRIGGER, LogLevel, MAX_POLL_TARGET_LIST_SIZE, ManagedChildProcesses, NodeStatus, RepoManager, ResultCode, SERVICE_GUARD_RUNNER_KEY, ServiceGuardNode, ServiceRegistryError, TASK_LOCAL_PACKAGE_CONFIG_FILENAME, TASK_REPO_SCRIPT_CATEGORY, TASK_REPO_USAGE, TASK_RUNNER_CONFIG_DIR, TASK_RUNNER_ROOT_CONFIG_FILENAME, TASK_RUNNER_ROOT_CONFIG_LEGACY_RELATIVE_PATH, TASK_RUNNER_ROOT_CONFIG_RELATIVE_PATH, TRIGGER_LOOP_INTERVAL_MS, TRIGGER_RUNNER_DEFAULT_RETRY_COUNT, TRIGGER_RUNNER_DEFAULT_RETRY_DELAY_MS, TaskManager, TaskNode, TaskRepoValidation, TaskStatus, TaskStatusAction, TriggerManager, TriggerNode, TriggerStatus, applyRegistrySlotGuardStep, buildNodeImportArgs, claimServiceRegistrySlot, createJsonFileStateStore, createLogPersistCoordinator, createLogger, createManagedChildProcesses, createPathsExistCheck, createRequiredEnvCheck, createServiceHost, createServiceRuntimeStateStore, createSupabaseReachableCheck, createTarget, disableLogPersist, ensureLogPersistFromEnv, evaluateBusyNodeLiveness, generateResponse, getConfigFileDir, getLogPersistStats, getPollCommandList, getPollCommandListSchema, getPossibleTarget, getScanRemoteRepoValues, getWorkerSpawnCooldownLastAt, importJsConfigModule, initSupabaseFromStandardEnv, isChildProcessRunning, isOptimisticLockResponse, loadCachedJsConfigModule, loadEnvFiles, logManager, logPersistEnabledFromEnv, markWorkerSpawned, nodeBufferToArrayBuffer, patchChangeNodeStatus, patchChangeTaskStatus, patchClaimTask, patchNodeHeartBeat, patchServiceRuntime, patchStopNode, patchTriggerFired, patchTriggerFiredSchema, pathExists, pollTargetList, postCommand, postCommandSchema, postRegisterNode, postTaskSchema, postTaskWithValidation, postTrigger, postTriggerSchema, publicBaseUrlFromEnv, readAndVerifySourceFile, readEnv, registerServiceGuardRunner, registrySlotRuntimePatchFromGuardResult, requireEnv, resolveFirstExistingPath, resolvePathFromBaseDir, resolvePathFromConfigFile, resolvePathFromCwd, runReadinessChecks, runReadinessGate, runRegistrySlotGuardCheck, runServiceGuardTick, runSingleProcessService, scanEnabledTriggers, scanEnabledTriggersSchema, scanTargetList, sha256Hex, snapshotLogPersistReady, spawnTsxChild, supabase, toFileImportHref, updateTargetDetails, validateTaskRepoAndParams, validateWithSchema, waitForLogPersistReady, waitForServiceReady };
+export { BaseNodeRuntime, COLLECT_LOG_RUNNER_KEY, CategoryCommand, CategoryNode, CategoryRepo, CategoryTrigger, CommandType, EMPTY_REGISTRY_SLOT_RUNTIME_STATE, LOG_SPOOL_SERVICE_ID_ENV, LOG_TOPIC_TRIGGER, LogLevel, MAX_POLL_TARGET_LIST_SIZE, ManagedChildProcesses, NodeStatus, RepoManager, ResultCode, SERVICE_GUARD_RUNNER_KEY, ServiceGuardNode, ServiceRegistryError, TASK_LOCAL_PACKAGE_CONFIG_FILENAME, TASK_REPO_SCRIPT_CATEGORY, TASK_REPO_USAGE, TASK_RUNNER_CONFIG_DIR, TASK_RUNNER_ROOT_CONFIG_FILENAME, TASK_RUNNER_ROOT_CONFIG_LEGACY_RELATIVE_PATH, TASK_RUNNER_ROOT_CONFIG_RELATIVE_PATH, TRIGGER_LOOP_INTERVAL_MS, TRIGGER_RUNNER_DEFAULT_RETRY_COUNT, TRIGGER_RUNNER_DEFAULT_RETRY_DELAY_MS, TaskManager, TaskNode, TaskRepoValidation, TaskStatus, TaskStatusAction, TriggerManager, TriggerNode, TriggerStatus, applyRegistrySlotGuardStep, buildNodeImportArgs, claimServiceRegistrySlot, createJsonFileStateStore, createL3ChildLauncher, createLogSpoolCoordinator, createLogger, createManagedChildProcesses, createPathsExistCheck, createRequiredEnvCheck, createServiceHost, createServiceRuntimeStateStore, createSupabaseReachableCheck, createTarget, enableLogSpoolFromEnvInChild, ensureLogSpoolFromEnv, evaluateBusyNodeLiveness, generateResponse, getConfigFileDir, getLogSpoolStats, getMainLogSpoolWriterStats, getPollCommandList, getPollCommandListSchema, getPossibleTarget, getScanRemoteRepoValues, guardRetryAfterSec, importJsConfigModule, initSupabaseFromStandardEnv, isChildProcessRunning, isGuardAvailable, isLogEntry, isLogSpoolEnabled, isOptimisticLockResponse, loadCachedJsConfigModule, loadEnvFiles, logManager, logSpoolEnabledFromEnv, markWorkerSpawned, nodeBufferToArrayBuffer, patchChangeNodeStatus, patchChangeTaskStatus, patchClaimTask, patchNodeHeartBeat, patchServiceRuntime, patchStopNode, patchTriggerFired, patchTriggerFiredSchema, pathExists, pollTargetList, pollUntil, postCommand, postCommandSchema, postRegisterNode, postTaskSchema, postTaskWithValidation, postTrigger, postTriggerSchema, publicBaseUrlFromEnv, readAndVerifySourceFile, readEnv, registerCollectLogRunner, registerServiceGuardRunner, registrySlotRuntimePatchFromGuardResult, requireEnv, resolveFirstExistingPath, resolveLogSpoolRoot, resolvePathFromBaseDir, resolvePathFromConfigFile, resolvePathFromCwd, runCollectLogTick, runReadinessChecks, runReadinessGate, runRegistrySlotGuardCheck, runServiceGuardTick, runSingleProcessService, scanEnabledTriggers, scanEnabledTriggersSchema, scanTargetList, sha256Hex, shutdownLogSpool, shutdownLogSpoolFromEnv, spawnTsxChild, supabase, toFileImportHref, updateTargetDetails, validateTaskRepoAndParams, validateWithSchema, waitForServiceReady };
 //# sourceMappingURL=node.js.map