@undefineds.co/xpod 0.4.15 → 0.4.16

package/dist/runtime/port-reservations.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Port reservations: one small mechanism that keeps every *other* group off the fixed ports a
+ * group needs.
+ *
+ * The tunnel acceptance has two legs whose origin port is not ours to choose — the Cloudflare
+ * Dashboard's local service port and the SakuraFrp console's `local_port`, both 5737 on the
+ * operator's machine. Those are fixed parameters, so the group that needs them publishes a
+ * reservation, and every port *allocator* in the repo skips reserved ports:
+ *
+ * - allocation helpers in `src/runtime/port-finder.ts` (which is what the runtime, the test
+ *   helpers, `run-integration-full`/`run-integration-lite` and the acceptance harness use);
+ * - the harness's own free-port helpers.
+ *
+ * Two sources, both optional and both additive:
+ * - the `XPOD_RESERVED_PORTS` env var (`"5737,4599"`), for a run that knows its fixed ports;
+ * - one JSON file per reservation under `.test-data/port-reservations/`, for a group that
+ *   holds a port for the duration of a run.
+ *
+ * A reservation is a *claim about the future*, not a lock: it is never enforced against a
+ * process that ignores it. That is deliberate — the network group fails loudly naming whoever
+ * holds its port, and nothing in this repo signals a process it does not own.
+ *
+ * Reservations expire (12h by default) so a crashed run cannot block a port forever.
+ */
+export declare const RESERVED_PORTS_ENV = "XPOD_RESERVED_PORTS";
+export declare const PORT_RESERVATION_DIR_ENV = "XPOD_PORT_RESERVATION_DIR";
+export interface PortReservation {
+    port: number;
+    /** Who holds it: a run id, a harness name, an operator. */
+    owner: string;
+    /** Which group needs the fixed port (`network` for the tunnel acceptance). */
+    group: string;
+    /** ISO timestamp the reservation was written. */
+    reservedAt: string;
+    /** Why this port is fixed, so the next person does not have to guess. */
+    note?: string;
+    /** Where the reservation came from, so a log line can name the source. */
+    source?: 'file' | 'env';
+}
+export declare function portReservationDir(root?: string): string;
+export declare function portReservationFile(port: number, root?: string): string;
+/** Publishes a reservation (idempotent for the same owner and port). */
+export declare function reservePort(reservation: Omit<PortReservation, 'reservedAt'> & {
+    reservedAt?: string;
+}, root?: string): PortReservation;
+/** Removes a reservation this owner wrote; another owner's reservation is left alone. */
+export declare function releasePort(port: number, owner: string, root?: string): boolean;
+export declare function parseReservedPortsEnv(value: string | undefined): number[];
+/** Every reservation in force right now: env var plus unexpired files. */
+export declare function readPortReservations(options?: {
+    env?: Record<string, string | undefined>;
+    root?: string;
+    now?: number;
+    ttlMs?: number;
+}): PortReservation[];
+/** The set every allocator skips. Cheap enough to call once per allocation. */
+export declare function reservedPorts(options?: {
+    env?: Record<string, string | undefined>;
+    root?: string;
+    now?: number;
+}): Set<number>;
+/** The reservation covering a port, when there is one: what a failure message should name. */
+export declare function portReservation(port: number, options?: {
+    env?: Record<string, string | undefined>;
+    root?: string;
+    now?: number;
+}): PortReservation | undefined;
+/** The slice of `net.Server`/`http.Server` this needs, so both can be passed in. */
+export interface ReservingListenable {
+    listen(port: number, host: string, callback: () => void): unknown;
+    address(): {
+        port: number;
+    } | string | null;
+    close(callback?: (error?: Error) => void): unknown;
+    once(event: 'error', listener: (error: Error) => void): unknown;
+}
+/**
+ * Binds a server to an OS-assigned port that is not reserved.
+ *
+ * `listen(0)` hands out whatever the kernel likes, reservations included. Fixtures that bind
+ * their own server therefore come through here: one retry loop, one rule, and a reserved port is
+ * never taken even by accident.
+ */
+export declare function listenOnUnreservedPort(server: ReservingListenable, host?: string, attempts?: number): Promise<number>;
+/** An unreserved OS-assigned port, released again so the caller can bind it itself. */
+export declare function getUnreservedEphemeralPort(host?: string, attempts?: number): Promise<number>;

package/dist/runtime/port-reservations.js

@@ -0,0 +1,183 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PORT_RESERVATION_DIR_ENV = exports.RESERVED_PORTS_ENV = void 0;
+exports.portReservationDir = portReservationDir;
+exports.portReservationFile = portReservationFile;
+exports.reservePort = reservePort;
+exports.releasePort = releasePort;
+exports.parseReservedPortsEnv = parseReservedPortsEnv;
+exports.readPortReservations = readPortReservations;
+exports.reservedPorts = reservedPorts;
+exports.portReservation = portReservation;
+exports.listenOnUnreservedPort = listenOnUnreservedPort;
+exports.getUnreservedEphemeralPort = getUnreservedEphemeralPort;
+const node_fs_1 = require("node:fs");
+const node_net_1 = __importDefault(require("node:net"));
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Port reservations: one small mechanism that keeps every *other* group off the fixed ports a
+ * group needs.
+ *
+ * The tunnel acceptance has two legs whose origin port is not ours to choose — the Cloudflare
+ * Dashboard's local service port and the SakuraFrp console's `local_port`, both 5737 on the
+ * operator's machine. Those are fixed parameters, so the group that needs them publishes a
+ * reservation, and every port *allocator* in the repo skips reserved ports:
+ *
+ * - allocation helpers in `src/runtime/port-finder.ts` (which is what the runtime, the test
+ *   helpers, `run-integration-full`/`run-integration-lite` and the acceptance harness use);
+ * - the harness's own free-port helpers.
+ *
+ * Two sources, both optional and both additive:
+ * - the `XPOD_RESERVED_PORTS` env var (`"5737,4599"`), for a run that knows its fixed ports;
+ * - one JSON file per reservation under `.test-data/port-reservations/`, for a group that
+ *   holds a port for the duration of a run.
+ *
+ * A reservation is a *claim about the future*, not a lock: it is never enforced against a
+ * process that ignores it. That is deliberate — the network group fails loudly naming whoever
+ * holds its port, and nothing in this repo signals a process it does not own.
+ *
+ * Reservations expire (12h by default) so a crashed run cannot block a port forever.
+ */
+exports.RESERVED_PORTS_ENV = 'XPOD_RESERVED_PORTS';
+exports.PORT_RESERVATION_DIR_ENV = 'XPOD_PORT_RESERVATION_DIR';
+const DEFAULT_TTL_MS = 12 * 60 * 60 * 1_000;
+const DEFAULT_DIRECTORY = node_path_1.default.join('.test-data', 'port-reservations');
+function portReservationDir(root = process.cwd()) {
+    return process.env[exports.PORT_RESERVATION_DIR_ENV]?.trim() || node_path_1.default.join(root, DEFAULT_DIRECTORY);
+}
+function portReservationFile(port, root = process.cwd()) {
+    return node_path_1.default.join(portReservationDir(root), `${port}.json`);
+}
+/** Publishes a reservation (idempotent for the same owner and port). */
+function reservePort(reservation, root = process.cwd()) {
+    const record = {
+        ...reservation,
+        reservedAt: reservation.reservedAt ?? new Date().toISOString(),
+        source: 'file',
+    };
+    const directory = portReservationDir(root);
+    (0, node_fs_1.mkdirSync)(directory, { recursive: true });
+    (0, node_fs_1.writeFileSync)(portReservationFile(record.port, root), JSON.stringify(record, null, 2), 'utf8');
+    return record;
+}
+/** Removes a reservation this owner wrote; another owner's reservation is left alone. */
+function releasePort(port, owner, root = process.cwd()) {
+    const file = portReservationFile(port, root);
+    const existing = readReservationFile(file);
+    if (!existing) {
+        return false;
+    }
+    if (existing.owner !== owner) {
+        return false;
+    }
+    (0, node_fs_1.rmSync)(file, { force: true });
+    return true;
+}
+function parseReservedPortsEnv(value) {
+    if (!value) {
+        return [];
+    }
+    return value
+        .split(/[\s,]+/u)
+        .map((entry) => Number.parseInt(entry.trim(), 10))
+        .filter((port) => Number.isInteger(port) && port > 0 && port <= 65_535);
+}
+/** Every reservation in force right now: env var plus unexpired files. */
+function readPortReservations(options = {}) {
+    const env = options.env ?? process.env;
+    const root = options.root ?? process.cwd();
+    const now = options.now ?? Date.now();
+    const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+    const reservations = [];
+    // Files first: they carry owner, group and timestamp, so a failure message can name who
+    // reserved the port. The env var only says "this number is spoken for".
+    let entries;
+    try {
+        entries = (0, node_fs_1.readdirSync)(portReservationDir(root));
+    }
+    catch {
+        entries = [];
+    }
+    for (const entry of entries) {
+        if (!entry.endsWith('.json')) {
+            continue;
+        }
+        const record = readReservationFile(node_path_1.default.join(portReservationDir(root), entry));
+        if (!record) {
+            continue;
+        }
+        if (now - Date.parse(record.reservedAt) > ttlMs) {
+            // A crashed run must not block a port forever; expiry is the whole reason for the stamp.
+            continue;
+        }
+        reservations.push({ ...record, source: 'file' });
+    }
+    for (const port of parseReservedPortsEnv(env[exports.RESERVED_PORTS_ENV])) {
+        if (reservations.some((reservation) => reservation.port === port)) {
+            continue;
+        }
+        reservations.push({
+            port,
+            owner: `${exports.RESERVED_PORTS_ENV}`,
+            group: 'env',
+            reservedAt: new Date(now).toISOString(),
+            source: 'env',
+        });
+    }
+    return reservations;
+}
+/** The set every allocator skips. Cheap enough to call once per allocation. */
+function reservedPorts(options = {}) {
+    return new Set(readPortReservations(options).map((reservation) => reservation.port));
+}
+/** The reservation covering a port, when there is one: what a failure message should name. */
+function portReservation(port, options = {}) {
+    return readPortReservations(options).find((reservation) => reservation.port === port);
+}
+function readReservationFile(file) {
+    try {
+        const parsed = JSON.parse((0, node_fs_1.readFileSync)(file, 'utf8'));
+        return typeof parsed?.port === 'number' && typeof parsed?.reservedAt === 'string' ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Binds a server to an OS-assigned port that is not reserved.
+ *
+ * `listen(0)` hands out whatever the kernel likes, reservations included. Fixtures that bind
+ * their own server therefore come through here: one retry loop, one rule, and a reserved port is
+ * never taken even by accident.
+ */
+async function listenOnUnreservedPort(server, host = '127.0.0.1', attempts = 8) {
+    const reserved = reservedPorts();
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        const port = await new Promise((resolve, reject) => {
+            server.once('error', reject);
+            server.listen(0, host, () => {
+                const address = server.address();
+                resolve(typeof address === 'object' && address ? address.port : 0);
+            });
+        });
+        if (!reserved.has(port)) {
+            return port;
+        }
+        await new Promise((resolve) => server.close(() => resolve()));
+    }
+    throw new Error('the OS only offered reserved ephemeral ports; release a reservation or widen the pool');
+}
+/** An unreserved OS-assigned port, released again so the caller can bind it itself. */
+async function getUnreservedEphemeralPort(host = '127.0.0.1', attempts = 8) {
+    const server = node_net_1.default.createServer();
+    try {
+        return await listenOnUnreservedPort(server, host, attempts);
+    }
+    finally {
+        await new Promise((resolve) => server.close(() => resolve()));
+    }
+}
+//# sourceMappingURL=port-reservations.js.map

package/dist/runtime/safe-env.d.ts

@@ -4,7 +4,7 @@ export interface AiConnectionsRuntimeConfig {
     apiKey: string;
     model?: string;
 }
-export declare function sanitizeRuntimeEnv(source?: NodeJS.ProcessEnv | Record<string, string | undefined>): Record<string, string>;
+export declare function sanitizeRuntimeEnv(source?: Record<string, string | undefined> | Record<string, string | undefined>): Record<string, string>;
 export declare function requireAiConnectionsRuntimeConfig(input: {
     baseUrl?: string;
     apiKey?: string;

package/dist/runtime/user-env.d.ts

@@ -1,6 +1,6 @@
 export declare function defaultXpodEnvPath({ env, platform, homeDir, }?: {
-    env?: NodeJS.ProcessEnv;
+    env?: Record<string, string | undefined>;
     platform?: NodeJS.Platform;
     homeDir?: string;
 }): string;
-export declare function resolveXpodEnvPath(explicitPath: string | undefined, env?: NodeJS.ProcessEnv): string;
+export declare function resolveXpodEnvPath(explicitPath: string | undefined, env?: Record<string, string | undefined>): string;

package/dist/supervisor/Supervisor.d.ts

@@ -5,6 +5,15 @@ export interface SupervisorLog {
     source: string;
     message: string;
 }
+export interface SupervisorOptions {
+    handleProcessSignals?: boolean;
+    /** Consecutive failed runs tolerated before giving up. */
+    maxRestarts?: number;
+    /** First restart delay; doubles per consecutive failure up to 60s. */
+    restartBaseDelayMs?: number;
+    /** Uptime that counts as a healthy run and resets the failure streak. */
+    healthyUptimeMs?: number;
+}
 export declare class Supervisor {
     private processes;
     private managedStops;
@@ -13,9 +22,13 @@ export declare class Supervisor {
     private logs;
     private onStatusChange?;
     private isShuttingDown;
-    constructor(options?: {
-        handleProcessSignals?: boolean;
-    });
+    private childOutput;
+    private pendingRestarts;
+    private intentionalStops;
+    private readonly maxRestarts;
+    private readonly restartBaseDelayMs;
+    private readonly healthyUptimeMs;
+    constructor(options?: SupervisorOptions);
     private shutdown;
     private killAll;
     setStatusChangeHandler(handler: StatusChangeHandler): void;
@@ -31,6 +44,16 @@ export declare class Supervisor {
     startAll(): Promise<void>;
     stopAll(): Promise<void>;
     start(name: string): void;
+    /**
+     * Stop restarting a service and say why. The gateway must not keep advertising itself as
+     * healthy afterwards: readiness derives from supervised state, not from HTTP reachability.
+     */
+    private giveUp;
+    /**
+     * Readiness of the supervised set: every configured child must be running. Managed services
+     * (for example the gateway itself) are lifecycle-owned elsewhere and are not required here.
+     */
+    isReady(): boolean;
     stop(name: string): Promise<void>;
     restart(name: string): Promise<boolean>;
     getStatus(name: string): ServiceState | undefined;

package/dist/supervisor/Supervisor.js

@@ -8,6 +8,29 @@ const node_child_process_1 = require("node:child_process");
 const tree_kill_1 = __importDefault(require("tree-kill"));
 const MAX_RESTARTS = 5;
 const MAX_LOGS = 500;
+/** Restart backoff: 2s, 4s, 8s, 16s, 32s, capped at 60s. */
+const RESTART_BASE_DELAY_MS = 2_000;
+const RESTART_MAX_DELAY_MS = 60_000;
+/** A run that stays up this long counts as healthy and clears the failure streak. */
+const HEALTHY_UPTIME_MS = 60_000;
+/** Bounded tail of child output kept per service for crash diagnosis. */
+const MAX_CHILD_OUTPUT_LINES = 20;
+/**
+ * Failures that cannot be fixed by retrying: the child's own runtime cannot resolve a module,
+ * so every restart fails identically. Retrying only hides the breakage behind a healthy-looking
+ * gateway, which is exactly how the audited instance stayed half-dead for hours (N20).
+ */
+const NON_RETRYABLE_PATTERNS = [
+    { pattern: /Cannot find package ['"][^'"]+['"]/u, reason: 'missing dependency (Cannot find package)' },
+    { pattern: /Cannot find module ['"][^'"]+['"]/u, reason: 'missing module (Cannot find module)' },
+    { pattern: /\bMODULE_NOT_FOUND\b/u, reason: 'missing module (MODULE_NOT_FOUND)' },
+];
+/** Mask credentials before child output is stored in supervisor state or served over HTTP. */
+function redactSecrets(line) {
+    return line
+        .replace(/([A-Za-z0-9_]*(?:token|secret|password|passwd|api[_-]?key|credential)[A-Za-z0-9_]*)(\s*[:=]\s*)("[^"]*"|'[^']*'|\S+)/giu, (_match, key, separator) => `${key}${separator}***`)
+        .replace(/\b([Bb]earer)\s+[A-Za-z0-9\-._~+/=]{8,}/gu, '$1 ***');
+}
 class Supervisor {
     constructor(options = {}) {
         this.processes = new Map();
@@ -16,6 +39,12 @@ class Supervisor {
         this.configs = new Map();
         this.logs = [];
         this.isShuttingDown = false;
+        this.childOutput = new Map();
+        this.pendingRestarts = new Map();
+        this.intentionalStops = new Set();
+        this.maxRestarts = options.maxRestarts ?? MAX_RESTARTS;
+        this.restartBaseDelayMs = options.restartBaseDelayMs ?? RESTART_BASE_DELAY_MS;
+        this.healthyUptimeMs = options.healthyUptimeMs ?? HEALTHY_UPTIME_MS;
         if (options.handleProcessSignals === false) {
             return;
         }
@@ -111,6 +140,10 @@ class Supervisor {
     }
     async stopAll() {
         this.isShuttingDown = true;
+        for (const [name, timer] of this.pendingRestarts) {
+            clearTimeout(timer);
+            this.pendingRestarts.delete(name);
+        }
         const promises = [];
         for (const name of this.processes.keys()) {
             promises.push(this.stop(name));
@@ -129,9 +162,16 @@ class Supervisor {
             return;
         if (state.status === 'running' || state.status === 'starting')
             return;
+        const pendingRestart = this.pendingRestarts.get(name);
+        if (pendingRestart) {
+            clearTimeout(pendingRestart);
+            this.pendingRestarts.delete(name);
+        }
+        this.intentionalStops.delete(name);
+        this.childOutput.set(name, []);
         console.log(`[Supervisor] Starting ${name}...`);
         this.addLog(name, 'info', 'Service starting');
-        this.updateState(name, { status: 'starting', startTime: Date.now() });
+        this.updateState(name, { status: 'starting', startTime: Date.now(), givenUpReason: undefined });
         const env = config.env ?? process.env;
         const child = (0, node_child_process_1.spawn)(config.command, config.args, {
             stdio: ['ignore', 'pipe', 'pipe'],
@@ -141,6 +181,16 @@ class Supervisor {
         });
         this.processes.set(name, child);
         this.updateState(name, { status: 'running', pid: child.pid });
+        const recordOutput = (line) => {
+            const tail = this.childOutput.get(name);
+            if (!tail) {
+                return;
+            }
+            tail.push(line);
+            if (tail.length > MAX_CHILD_OUTPUT_LINES) {
+                tail.splice(0, tail.length - MAX_CHILD_OUTPUT_LINES);
+            }
+        };
         const prefixLog = (source, data, isError = false) => {
             const output = data.toString();
             const lines = output.split('\n');
@@ -149,13 +199,18 @@ class Supervisor {
                 if (!trimmed) {
                     continue;
                 }
+                // Redact once, at the single point where child output enters supervisor state:
+                // the console, the log ring buffer (served by /service/logs) and the retained
+                // crash tail must not disagree about what the child printed.
+                const text = redactSecrets(trimmed);
+                recordOutput(text);
                 if (isError) {
-                    console.error(`[${source}] ${trimmed}`);
-                    this.addLog(source, 'error', trimmed);
+                    console.error(`[${source}] ${text}`);
+                    this.addLog(source, 'error', text);
                 }
                 else {
-                    console.log(`[${source}] ${trimmed}`);
-                    this.addLog(source, 'info', trimmed);
+                    console.log(`[${source}] ${text}`);
+                    this.addLog(source, 'info', text);
                 }
             }
         };
@@ -168,44 +223,94 @@ class Supervisor {
         child.on('error', (err) => {
             console.error(`[Supervisor] Error spawning ${name}:`, err);
             this.addLog(name, 'error', `Spawn error: ${String(err)}`);
-            this.updateState(name, { status: 'crashed' });
+            this.updateState(name, { status: 'crashed', givenUpReason: `Spawn error: ${String(err)}` });
         });
         child.on('exit', (code, signal) => {
+            const exitedAt = Date.now();
+            const stateBeforeExit = this.states.get(name);
+            const uptimeMs = stateBeforeExit?.startTime ? exitedAt - stateBeforeExit.startTime : 0;
+            const wasManualStop = stateBeforeExit?.status === 'stopped' || this.intentionalStops.has(name);
+            const wasHealthy = uptimeMs >= this.healthyUptimeMs;
+            const consecutiveFailures = wasHealthy ? 0 : (stateBeforeExit?.consecutiveFailures ?? 0) + 1;
+            const outputTail = this.childOutput.get(name) ?? [];
+            const nonRetryable = NON_RETRYABLE_PATTERNS.find(({ pattern }) => outputTail.some((line) => pattern.test(line)));
             console.log(`[Supervisor] ${name} exited with code ${code} signal ${signal}`);
             this.addLog(name, code === 0 ? 'info' : 'error', `Exited with code ${code ?? 'null'} signal ${signal ?? 'null'}`);
-            const currentState = this.states.get(name);
-            const wasManualStop = currentState?.status === 'stopped';
+            this.processes.delete(name);
+            this.childOutput.delete(name);
+            this.intentionalStops.delete(name);
             this.updateState(name, {
                 status: 'stopped',
                 lastExitCode: code ?? undefined,
+                lastExitAt: exitedAt,
+                lastOutput: outputTail,
+                consecutiveFailures,
                 pid: undefined,
             });
-            this.processes.delete(name);
-            // Auto-restart on crash (not on manual stop or shutdown)
-            if (code !== 0 && !wasManualStop && !this.isShuttingDown) {
-                const newState = this.states.get(name);
-                const restartCount = (newState?.restartCount || 0) + 1;
-                if (restartCount <= MAX_RESTARTS) {
-                    this.updateState(name, { restartCount });
-                    console.log(`[Supervisor] Restarting ${name} in 2s... (attempt ${restartCount}/${MAX_RESTARTS})`);
-                    this.addLog(name, 'warn', `Restarting in 2s (attempt ${restartCount}/${MAX_RESTARTS})`);
-                    setTimeout(() => this.start(name), 2000);
-                }
-                else {
-                    console.error(`[Supervisor] ${name} exceeded max restarts (${MAX_RESTARTS}), giving up`);
-                    this.addLog(name, 'error', `Exceeded max restarts (${MAX_RESTARTS})`);
-                }
+            // Auto-restart on crash (not on clean exit, manual stop or shutdown)
+            if (code === 0 || wasManualStop || this.isShuttingDown) {
+                return;
             }
+            if (nonRetryable) {
+                this.giveUp(name, `Unrecoverable child failure: ${nonRetryable.reason}; restart suppressed`, consecutiveFailures);
+                return;
+            }
+            if (consecutiveFailures > this.maxRestarts) {
+                this.giveUp(name, `Exceeded max restarts (budget ${this.maxRestarts}, ${consecutiveFailures} consecutive failures)`, consecutiveFailures);
+                return;
+            }
+            const delay = Math.min(this.restartBaseDelayMs * 2 ** (consecutiveFailures - 1), RESTART_MAX_DELAY_MS);
+            this.updateState(name, { restartCount: (stateBeforeExit?.restartCount ?? 0) + 1 });
+            const attempt = `(${consecutiveFailures}/${this.maxRestarts} consecutive failures)`;
+            console.log(`[Supervisor] Restarting ${name} in ${delay}ms... ${attempt}`);
+            this.addLog(name, 'warn', `Restarting in ${Math.round(delay / 1000)}s ${attempt}`);
+            const timer = setTimeout(() => {
+                this.pendingRestarts.delete(name);
+                this.start(name);
+            }, delay);
+            this.pendingRestarts.set(name, timer);
         });
     }
+    /**
+     * Stop restarting a service and say why. The gateway must not keep advertising itself as
+     * healthy afterwards: readiness derives from supervised state, not from HTTP reachability.
+     */
+    giveUp(name, reason, consecutiveFailures) {
+        console.error(`[Supervisor] ${name}: ${reason}`);
+        this.addLog(name, 'error', `Giving up on ${name}: ${reason}`);
+        this.updateState(name, { status: 'given-up', givenUpReason: reason, consecutiveFailures });
+    }
+    /**
+     * Readiness of the supervised set: every configured child must be running. Managed services
+     * (for example the gateway itself) are lifecycle-owned elsewhere and are not required here.
+     */
+    isReady() {
+        for (const name of this.configs.keys()) {
+            if (this.states.get(name)?.status !== 'running') {
+                return false;
+            }
+        }
+        return true;
+    }
     stop(name) {
         return new Promise((resolve) => {
+            const pendingRestart = this.pendingRestarts.get(name);
+            if (pendingRestart) {
+                // A service waiting out its backoff is not running, but it is not stopped either:
+                // cancel the timer so a stop request cannot be undone by a scheduled restart.
+                clearTimeout(pendingRestart);
+                this.pendingRestarts.delete(name);
+            }
             const child = this.processes.get(name);
             if (!child || !child.pid) {
+                if (this.states.has(name)) {
+                    this.updateState(name, { status: 'stopped', pid: undefined, givenUpReason: undefined });
+                }
                 resolve();
                 return;
             }
             // Mark as stopped first to prevent auto-restart
+            this.intentionalStops.add(name);
             this.updateState(name, { status: 'stopped' });
             this.addLog(name, 'info', 'Stopping service');
             (0, tree_kill_1.default)(child.pid, 'SIGTERM', (err) => {
@@ -230,6 +335,8 @@ class Supervisor {
             this.addLog(name, 'error', 'Timed out waiting for service to stop before restart');
             return false;
         }
+        // An explicit restart follows a deliberate operator action: grant a fresh retry budget.
+        this.updateState(name, { consecutiveFailures: 0, givenUpReason: undefined });
         this.addLog(name, 'info', 'Service restart requested');
         this.start(name);
         return true;

package/dist/supervisor/types.d.ts

@@ -6,7 +6,12 @@ export interface ServiceConfig {
     cwd?: string;
     readyUrl?: string;
 }
-export type ServiceStatus = 'stopped' | 'starting' | 'running' | 'crashed';
+/**
+ * `given-up` means the supervisor stopped restarting the child on purpose (unrecoverable
+ * failure or exhausted retries). It is distinct from `stopped` (intentional stop) and
+ * `crashed` (spawn failed) because a given-up child never returns without operator action.
+ */
+export type ServiceStatus = 'stopped' | 'starting' | 'running' | 'crashed' | 'given-up';
 export interface ServiceState {
     name: string;
     status: ServiceStatus;
@@ -14,6 +19,14 @@ export interface ServiceState {
     startTime?: number;
     uptime?: number;
     lastExitCode?: number;
+    /** Epoch millis of the last child exit, so a stale crash can be told apart from a live one. */
+    lastExitAt?: number;
     restartCount: number;
+    /** Consecutive failed runs; a run that stayed up long enough clears it. */
+    consecutiveFailures?: number;
+    /** Bounded, redacted tail of the child's own output, for diagnosing a crash without shell access. */
+    lastOutput?: string[];
+    /** Why the supervisor stopped restarting this service (set while status is `given-up`). */
+    givenUpReason?: string;
 }
 export type StatusChangeHandler = (name: string, state: ServiceState) => void;

package/dist/test-utils/local-managed-client-p2p-e2e-smoke.js

@@ -66,9 +66,24 @@ async function runLocalManagedClientP2PE2ESmoke(options = {}) {
                 nodeId,
                 baseUrl: `https://${nodeId}.${baseStorageDomain}/`,
             });
+            // The node serves many sessions on one socket, so it resolves the per-session data plane
+            // secret from the signaling API on handshake (audit N03). A session without a secret is
+            // refused there, which is why the smoke client always creates one.
+            const dataPlaneSignaling = (0, reachability_1.createP2PSignalingClient)({
+                apiBaseUrl: signalApi.baseUrl,
+                nodeId,
+                token: nodeToken,
+            });
             const dataPlaneServer = (0, reachability_1.createTcpP2PDataPlaneServer)({
                 handler: (0, reachability_1.createP2PDataPlaneHandler)({ targetBaseUrl: target.baseUrl }),
                 host: p2pHost,
+                secure: {
+                    role: 'server',
+                    resolveSessionSecret: async (sessionId) => {
+                        const session = await dataPlaneSignaling.getP2PSession(sessionId);
+                        return session.dataPlaneSecret;
+                    },
+                },
             });
             await dataPlaneServer.listen(0);
             nodePlan = {

package/dist/tunnel/LocalTunnelProvider.d.ts

@@ -10,6 +10,8 @@ export interface LocalTunnelProviderOptions {
     publicUrl?: string;
     /** cloudflared 可执行文件路径 (默认 'cloudflared') */
     cloudflaredPath?: string;
+    /** Environment used to resolve the client binary; injectable for tests. */
+    env?: Record<string, string | undefined>;
     /** 等待代理发布的毫秒数；超时后状态为 failed，而不是"仍在连接" */
     connectTimeoutMs?: number;
 }
@@ -96,6 +98,11 @@ export declare class LocalTunnelProvider implements TunnelProvider {
  *
  * Both halves are reported: pointing the dashboard at `https://localhost:<port>` while this
  * runtime serves plain HTTP there fails the TLS handshake, and the edge shows only a 502.
+ *
+ * cloudflared logs the configuration it fetched as an escaped JSON string inside one log line
+ * (`config="{\"ingress\":[{\"service\":\"http://localhost:5737\"}]}"`), so the quotes around
+ * the JSON keys arrive backslash-escaped. Unescaping first is what makes this read-back work
+ * against a real connector; a line where the JSON is not escaped is still accepted.
  */
 export declare function readDashboardOrigin(output: string): {
     scheme: string;