target-supabase-sdk 0.2.13 → 0.2.15

package/dist/preload.js

@@ -1,6 +1,6 @@
 import { resolve } from 'node:path';
 import { w as logManager, H as resolveLogMinLevel } from './chunks/list.api-BzbTJBsM.js';
-import { r as resolveProjectRootByPackageName, p as pinEnvProfileFromArgv, l as loadEnvFiles, v as validateLogSpoolPreloadEnv, a as logSpoolEnabledFromEnv, m as mergeLogSpoolExtraProcessRolesEnv } from './chunks/enable-DqnfLPsQ.js';
+import { r as resolveProjectRootByPackageName, p as pinEnvProfileFromArgv, l as loadEnvFiles, v as validateLogSpoolPreloadEnv, a as logSpoolEnabledFromEnv, m as mergeLogSpoolExtraProcessRolesEnv } from './chunks/enable-C7lFooTG.js';
 import 'zod';
 import 'lodash-es';
 import '@supabase/supabase-js';

package/dist/shared/utils/postgrest.utils.d.ts

@@ -0,0 +1,23 @@
+/**
+ * PostgREST / Supabase JS client helpers for `target` table filters.
+ *
+ * @see `.cursor/skills/postgrest-query-filters/SKILL.md`
+ */
+/**
+ * Escape `%`, `_`, and `\` for PostgREST `ilike` patterns.
+ * Also strips commas — they break `.or()` filter strings when multiple columns are searched.
+ */
+export declare function escapeIlikePattern(raw: string): string;
+/**
+ * Format a JS string array as a PostgreSQL `text[]` literal for PostgREST filter values.
+ *
+ * Required when tag values contain `:` or other special characters, and when using
+ * `.filter(column, "not.ov", literal)` — `.not("column", "ov", jsArray)` stringifies
+ * with `Array#toString()` and produces an invalid array literal.
+ *
+ * @example
+ * toPostgrestTextArrayLiteral(["stop-word:base", "small-word"])
+ * // → '{"stop-word:base","small-word"}'
+ */
+export declare function toPostgrestTextArrayLiteral(values: readonly string[]): string;
+//# sourceMappingURL=postgrest.utils.d.ts.map

package/dist/shared/utils/postgrest.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgrest.utils.d.ts","sourceRoot":"","sources":["../../../src/shared/utils/postgrest.utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAE7E"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "target-supabase-sdk",
-    "version": "0.2.13",
+    "version": "0.2.15",
     "description": "Supabase client initializer and data access APIs",
     "license": "MIT",
     "author": "KyLoc20",

package/src/browser.ts

@@ -233,6 +233,7 @@ export {
     classifyNetworkError,
     formatNetworkError,
 } from "./shared/utils/network-error";
+export { escapeIlikePattern, toPostgrestTextArrayLiteral } from "./shared/utils/postgrest.utils";
 export type { SanitizeFileNameOptions } from "./shared/utils/safe-file-name";
 export { sanitizeFileName, sanitizeParcelFileName } from "./shared/utils/safe-file-name";
 export { sha256Hex } from "./shared/utils/sha256";

package/src/node/env/index.ts

@@ -7,10 +7,6 @@ export {
     CLI_PROD_FLAG,
     envProfileFromProcess,
     loadEnvFiles,
-    parseEnvFile,
-    parseEnvFileContent,
-    parseEnvLine,
-    pinEnvProfileFromArgv,
     resolveDefaultEnvFiles,
     SERVICE_ENV_PROFILE_ENV_KEY,
     SERVICE_ENV_PROFILE_PROD,

package/src/node/node-runtime.base.ts

@@ -12,9 +12,12 @@ import {
 } from "../shared/log";
 import { getErrorMessage } from "../shared/utils/error.utils";
 import { patchChangeNodeStatus, patchNodeHeartBeat, patchStopNode, postRegisterNode } from "./node.api";
+import { LOG_TOPIC_NODE } from "./node.constant";
 import { NodeStatus } from "./node.interface";
 import { formatHeartbeat, getRandomInterval } from "./node.utils";
 
+export { LOG_TOPIC_NODE };
+
 /** 主循环单轮运行时上下文 — 由 start() 创建并向下传递 */
 export interface NodeLoopContext {
     loopTraceId: string;
@@ -31,7 +34,6 @@ export interface BaseNodeRuntimeOptions {
     beforeProcessExit?: () => void | Promise<void>;
 }
 
-export const LOG_TOPIC_NODE = "node";
 const LOG_TOPIC_COMMAND = "command";
 const LOG_TOPIC_PROCESS = "process";
 
@@ -118,6 +120,25 @@ abstract class BaseNodeRuntime {
         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.
+     */
+    protected isSilenced(): boolean {
+        return false;
+    }
+
+    /**
+     * Consecutive heartbeat failures reached {@link HEARTBEAT_FAILURE_THRESHOLD}.
+     * Default: shut down the node. Override to wait for recovery instead of exiting.
+     */
+    protected async onHealthCheckFailed(_ctx: NodeLoopContext): Promise<void> {
+        this.requestShutdown("heartbeat:consecutive-failures");
+    }
+
+    /** Heartbeat succeeded while {@link isSilenced} is true. Default: no-op. */
+    protected async onHeartbeatRecovered(_ctx: NodeLoopContext): Promise<void> {}
+
     private getLogNodeId(): string {
         return this.localNodeId ?? BaseNodeRuntime.NODE_ID_PENDING_ASSIGNMENT;
     }
@@ -284,7 +305,9 @@ abstract 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;
@@ -294,7 +317,9 @@ abstract 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} 輪遇到未知錯誤`, {
                     topic: LOG_TOPIC_NODE,
@@ -410,11 +435,11 @@ abstract 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 });
             }
@@ -422,6 +447,9 @@ abstract class BaseNodeRuntime {
         }
 
         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,

package/src/node/node.api.ts

@@ -2,10 +2,10 @@ import { z } from "zod";
 import { createTarget, type QueryFilter, updateTargetDetails, validateWithSchema } from "../core.api";
 import { generateResponse } from "../core.interface";
 import { createLogger } from "../shared/log";
+import { LOG_TOPIC_NODE } from "./node.constant";
 import { CategoryNode, type Node, type NodeDetails, NodeStatus } from "./node.interface";
 
 const NODE_STATUS_FIELD = "details->>status" as const;
-const LOG_TOPIC_NODE = "node";
 
 const nodeIdSchema = z.string().trim().min(1);
 const traceIdSchema = z.string().trim().min(1).optional();

package/src/node/node.constant.ts

@@ -0,0 +1,2 @@
+/** Shared log topic for Node domain APIs and {@link BaseNodeRuntime}. */
+export const LOG_TOPIC_NODE = "node";

package/src/node/node.utils.ts

@@ -1,4 +1,4 @@
-export const formatTimestamp = (timestamp: number): string => {
+const formatTimestamp = (timestamp: number): string => {
     return new Intl.DateTimeFormat("zh-CN", {
         year: "numeric",
         month: "2-digit",
@@ -11,7 +11,7 @@ export const formatTimestamp = (timestamp: number): string => {
     }).format(timestamp);
 };
 
-export const formatRelativeTime = (timestamp: number): string => {
+const formatRelativeTime = (timestamp: number): string => {
     const now = Date.now();
     const diff = now - timestamp;
 

package/src/node/readiness/index.ts

@@ -12,6 +12,8 @@ export {
     createSupabaseReachableCheck,
 } from "./readiness-checks";
 export { runReadinessChecks } from "./run-readiness-checks";
+export type { RunReadinessGateInput } from "./run-readiness-gate";
+export { runReadinessGate } from "./run-readiness-gate";
 export type {
     ServiceReadyGate,
     ServiceReadySnapshot,

package/src/node/{service-guard → readiness}/run-readiness-gate.ts

@@ -1,6 +1,6 @@
 import type { LoggerWithScope } from "../../shared/log";
-import type { ReadinessCheck, ReadinessReport } from "../readiness/readiness.types";
-import { runReadinessChecks } from "../readiness/run-readiness-checks";
+import type { ReadinessCheck, ReadinessReport } from "./readiness.types";
+import { runReadinessChecks } from "./run-readiness-checks";
 
 export interface RunReadinessGateInput {
     checks: ReadinessCheck[];

package/src/node/readiness/service-ready-gate.ts

@@ -1,8 +1,5 @@
 import type { LoggerWithScope } from "../../shared/log";
-
-function sleep(ms: number): Promise<void> {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}
+import { pollUntil } from "./poll-until";
 
 export interface ServiceReadySnapshot {
     failed: boolean;
@@ -36,30 +33,37 @@ export async function waitForServiceReady(
 ): Promise<ServiceReadySnapshot> {
     const pollMs = options.pollMs ?? 500;
     const defaultFailureMessage = options.failureMessage ?? "Readiness checks failed";
-    const deadline = Date.now() + options.timeoutMs;
     let last: ServiceReadySnapshot = { 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;
 }

package/src/node/runtime-state/create-service-runtime-state-store.ts

@@ -58,11 +58,22 @@ function createDefaultServiceRuntimeState<TExtraSlices extends Record<string, ob
         lastDecision: null,
         lastSpawnAt: null,
         spawnCount: 0,
+        mode: "healthy",
+        silentEnteredAt: null,
+        silentLastHeartbeatAt: null,
+        silentBackoffMs: 0,
+        silentConsecutiveFailures: 0,
+        silentRecoveryAttempt: 0,
+        silentEvents: [],
     };
     const scheduler: SchedulerRuntimeSlice = {
         lastTickAt: null,
         lastPostedCount: 0,
         lastFired: {},
+        pid: null,
+        spawnedAt: null,
+        ready: false,
+        readyAt: null,
     };
     const worker: WorkerRuntimeSlice = {
         pid: null,

package/src/node/runtime-state/service-runtime-state.types.ts

@@ -15,12 +15,24 @@ export interface GuardRuntimeSlice {
     lastDecision: string | null;
     lastSpawnAt: string | null;
     spawnCount: number;
+    /** `healthy` when omitted (legacy shards). Silent: heartbeat-only wait. Recovering: respawn business nodes. */
+    mode: "healthy" | "silent" | "recovering";
+    silentEnteredAt: string | null;
+    silentLastHeartbeatAt: string | null;
+    silentBackoffMs: number;
+    silentConsecutiveFailures: number;
+    silentRecoveryAttempt: number;
+    silentEvents: { at: string; type: string; detail?: string }[];
 }
 
 export interface SchedulerRuntimeSlice {
     lastTickAt: string | null;
     lastPostedCount: number;
     lastFired: Record<string, string>;
+    pid: number | null;
+    spawnedAt: string | null;
+    ready: boolean;
+    readyAt: string | null;
 }
 
 export interface WorkerRuntimeSlice {

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

@@ -1,6 +1,9 @@
 export { registerServiceGuardRunner } from "./register-service-guard-runner";
-export type { RunReadinessGateInput } from "./run-readiness-gate";
-export { runReadinessGate } from "./run-readiness-gate";
+export type {
+    ApplyRegistrySlotGuardInput,
+    ApplyRegistrySlotGuardResult,
+} from "./registry-slot-guard-step";
+export { applyRegistrySlotGuardStep } from "./registry-slot-guard-step";
 export { runServiceGuardTick } from "./run-service-guard-tick";
 export type {
     RegisterServiceGuardRunnerOptions,
@@ -8,10 +11,6 @@ export type {
     ServiceGuardTickInput,
     ServiceGuardTickResult,
 } from "./service-guard.interface";
-export { SERVICE_GUARD_RUNNER_KEY } from "./service-guard.interface";
+export { guardRetryAfterSec, isGuardAvailable, SERVICE_GUARD_RUNNER_KEY } from "./service-guard.interface";
 export { ServiceGuardNode } from "./service-guard-node";
-export {
-    getWorkerSpawnCooldownLastAt,
-    markWorkerSpawned,
-    resetWorkerSpawnCooldownForTests,
-} from "./worker-spawn-cooldown";
+export { markWorkerSpawned } from "./worker-spawn-cooldown";

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

@@ -60,5 +60,3 @@ export function registerServiceGuardRunner(options: RegisterServiceGuardRunnerOp
         fn: (ctx) => runServiceGuardRunner(ctx, options),
     });
 }
-
-export { SERVICE_GUARD_RUNNER_KEY };

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

@@ -1,5 +1,8 @@
-import { CategoryNode, evaluateBusyNodeLiveness, type Node, patchServiceRuntime, scanTargetList } from "../../browser";
-import { applyRegistrySlotGuardStep } from "../service-host/registry-slot-guard-step";
+import { scanTargetList } from "../../core.api";
+import { patchServiceRuntime } from "../../service/registry.service";
+import { CategoryNode, type Node } from "../node.interface";
+import { evaluateBusyNodeLiveness } from "../node-liveness";
+import { applyRegistrySlotGuardStep } from "./registry-slot-guard-step";
 import type { ServiceGuardTickInput, ServiceGuardTickResult } from "./service-guard.interface";
 import { getWorkerSpawnCooldownLastAt, markWorkerSpawned } from "./worker-spawn-cooldown";
 

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

@@ -1,18 +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({
@@ -20,14 +37,16 @@ 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,
@@ -36,6 +55,38 @@ class ServiceGuardNode extends TriggerNode {
         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,
@@ -46,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" });
     }
 }