@zhin.js/gateway 0.0.1-bootstrap.0 → 1.1.2

package/lib/supervisor/instance-supervisor.js

@@ -0,0 +1,408 @@
+/**
+ * Instance supervisor (ADR 0054 §3 / §5): spawns the Zhin instance with an IPC control channel
+ * (`serialization: 'advanced'`), waits for its `ready` handshake, stops it with a graceful
+ * `shutdown` message before escalating to SIGTERM / SIGKILL, restarts it on `restart-request`
+ * and on crashes with backoff and storm protection, and captures its stdout / stderr.
+ */
+import { spawn } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import { INSTANCE_BRIDGE_PROTOCOL_VERSION, INSTANCE_CHILD_ENV, IpcInstanceTransport, parseInstanceMessage, } from '@zhin.js/host-http/bridge';
+import { DEFAULT_SHUTDOWN_BUDGET_MS } from '@zhin.js/runtime';
+import { InstanceLogCollector } from './instance-logs.js';
+export const DEFAULT_INSTANCE_READY_TIMEOUT_MS = 60_000;
+export const DEFAULT_INSTANCE_KILL_GRACE_MS = 2_000;
+/** Storm guard: 10 automatic restarts per minute, 3 s apart (ADR 0054 §5). */
+export const MAX_RESTARTS_PER_WINDOW = 10;
+export const RESTART_WINDOW_MS = 60_000;
+export const RESTART_DELAY_MS = 3_000;
+const FAILURE_LOG_TAIL_LINES = 50;
+const STDIO_DRAIN_MS = 250;
+export class InstanceProtocolMismatchError extends Error {
+    instanceVersion;
+    accepted;
+    code = 'ZHIN_INSTANCE_PROTOCOL_MISMATCH';
+    constructor(instanceVersion, accepted) {
+        super(`Instance protocol version ${instanceVersion} is not supported by this gateway (accepts ${accepted.join(', ')}); upgrade zhin.js and @zhin.js/gateway together`);
+        this.instanceVersion = instanceVersion;
+        this.accepted = accepted;
+        this.name = 'InstanceProtocolMismatchError';
+    }
+}
+export class InstanceStartError extends Error {
+    failure;
+    code = 'ZHIN_INSTANCE_START_FAILED';
+    constructor(failure) {
+        super(failure.message);
+        this.failure = failure;
+        this.name = 'InstanceStartError';
+    }
+}
+export class InstanceSupervisor extends EventEmitter {
+    logs;
+    /**
+     * HTTP / WebSocket bridge to the current instance child (ADR 0054 §2). Stable across
+     * restarts: the gateway's HTTP server forwards through it; it is `ready` while a child that
+     * announced its route table runs.
+     */
+    transport;
+    #options;
+    #readyTimeoutMs;
+    #accepted;
+    #state = 'stopped';
+    #child;
+    #starting;
+    #stopping;
+    #backoffTimer;
+    #restartTimes = [];
+    #ready;
+    #startedAt;
+    #lastExit;
+    #lastFailure;
+    /** Bumped by every stop(); a pending automatic restart only proceeds when it is unchanged. */
+    #stopIntent = 0;
+    constructor(options) {
+        super();
+        this.#options = options;
+        this.#readyTimeoutMs = options.readyTimeoutMs;
+        this.#accepted = Object.freeze([...(options.acceptedProtocolVersions ?? [INSTANCE_BRIDGE_PROTOCOL_VERSION])]);
+        this.logs = new InstanceLogCollector(options.logs);
+        this.transport = new IpcInstanceTransport(options.transport);
+        this.logs.subscribe((line) => { this.emit('log', line); });
+    }
+    get state() { return this.#state; }
+    status() {
+        const child = this.#child;
+        return Object.freeze({
+            state: this.#state,
+            ...(child?.process.pid !== undefined ? { pid: child.process.pid } : {}),
+            ...(this.#startedAt !== undefined && this.#state === 'running' ? { startedAt: this.#startedAt } : {}),
+            ...(this.#ready?.generation !== undefined ? { generation: this.#ready.generation } : {}),
+            ...(this.#ready ? { protocolVersion: this.#ready.version } : {}),
+            lastExitCode: this.#lastExit?.code ?? null,
+            lastExitSignal: this.#lastExit?.signal ?? null,
+            ...(this.#lastFailure ? { lastFailure: this.#lastFailure } : {}),
+            recentRestarts: this.#recentRestarts(Date.now()).length,
+        });
+    }
+    /**
+     * Starts the instance and resolves on its `ready`. A manual start resets the storm window.
+     * Rejects with {@link InstanceStartError} / {@link InstanceProtocolMismatchError} when this
+     * attempt fails; automatic restarts after a crash still follow the restart policy.
+     */
+    async start() {
+        if (this.#stopping)
+            await this.#stopping.catch(() => undefined);
+        // A child that is being replaced (requested restart, ready failure) must be gone first.
+        if (this.#child?.terminating)
+            await this.#child.exited;
+        if (this.#state === 'running')
+            return;
+        if (this.#starting)
+            return this.#starting;
+        this.#clearBackoff();
+        this.#restartTimes = [];
+        return this.#spawn();
+    }
+    /** Graceful `shutdown`, then SIGTERM after `timeoutMs`, then SIGKILL after the kill grace. */
+    stop(options = {}) {
+        this.#stopIntent += 1;
+        this.#clearBackoff();
+        const child = this.#child;
+        if (!child) {
+            if (this.#state === 'backoff' || this.#state === 'crashed')
+                this.#setState('stopped');
+            return this.#stopping ?? Promise.resolve();
+        }
+        if (options.force)
+            child.process.kill('SIGKILL');
+        if (this.#stopping)
+            return this.#stopping;
+        this.#setState('stopping');
+        const stopping = this.#terminate(child, options.reason ?? 'stop', options.timeoutMs).then(() => undefined);
+        this.#stopping = stopping.finally(() => { this.#stopping = undefined; });
+        return this.#stopping;
+    }
+    /**
+     * Ready timeout for the next spawns (`gateway.readyTimeout`, re-read by the gateway before each
+     * start, restart and transaction); `undefined` goes back to the constructor option.
+     */
+    setReadyTimeout(ms) {
+        this.#readyTimeoutMs = ms ?? this.#options.readyTimeoutMs;
+    }
+    /** Ready timeout the next spawn uses. */
+    get readyTimeoutMs() {
+        return this.#readyTimeoutMs ?? DEFAULT_INSTANCE_READY_TIMEOUT_MS;
+    }
+    /** Manual restart: stop gracefully, then start (not counted by the storm guard). */
+    async restart(options = {}) {
+        await this.stop({ ...options, reason: options.reason ?? 'restart' });
+        await this.start();
+    }
+    /** Releases timers and the log file; kills a child that is still running. */
+    dispose() {
+        this.#clearBackoff();
+        try {
+            this.#child?.process.kill('SIGKILL');
+        }
+        catch { /* already gone */ }
+        this.transport.detach('Supervisor disposed');
+        this.logs.close();
+        this.removeAllListeners();
+    }
+    #spawn() {
+        const { spawn: spec } = this.#options;
+        const output = this.#options.output ?? 'pipe';
+        this.#ready = undefined;
+        this.#startedAt = undefined;
+        this.#setState('starting');
+        let processHandle;
+        let resolveExited;
+        const exited = new Promise((resolve) => { resolveExited = resolve; });
+        try {
+            processHandle = spawn(spec.command, [...spec.args], {
+                cwd: spec.cwd,
+                // The marker carries the protocol version: the instance refuses an incompatible gateway.
+                env: { ...(spec.env ?? process.env), [INSTANCE_CHILD_ENV]: String(INSTANCE_BRIDGE_PROTOCOL_VERSION) },
+                stdio: [this.#options.input ?? 'ignore', output, output, 'ipc'],
+                serialization: 'advanced',
+                windowsHide: true,
+            });
+        }
+        catch (error) {
+            const failure = this.#failure('spawn-error', `Failed to spawn the instance: ${errorMessage(error)}`, null, null);
+            this.#afterFailedChild(failure, false);
+            return Promise.reject(new InstanceStartError(failure));
+        }
+        const child = { process: processHandle, exited, resolveExited, ready: false, terminating: false };
+        this.#child = child;
+        if (output === 'pipe') {
+            if (processHandle.stdout)
+                this.logs.attach(processHandle.stdout, 'stdout');
+            if (processHandle.stderr)
+                this.logs.attach(processHandle.stderr, 'stderr');
+        }
+        const starting = new Promise((resolve, reject) => {
+            child.settleStart = (error) => {
+                child.settleStart = undefined;
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            };
+        });
+        const guarded = starting.finally(() => {
+            if (this.#starting === guarded)
+                this.#starting = undefined;
+        });
+        this.#starting = guarded;
+        // Callers may ignore automatic-restart attempts; never leave them unhandled.
+        guarded.catch(() => undefined);
+        const readyTimeoutMs = this.readyTimeoutMs;
+        child.readyTimer = setTimeout(() => {
+            if (child.ready || this.#child !== child)
+                return;
+            const failure = this.#failure('ready-timeout', `Instance did not report ready within ${readyTimeoutMs} ms`, null, null);
+            child.failure = failure;
+            child.settleStart?.(new InstanceStartError(failure));
+            void this.#terminate(child, 'ready-timeout');
+        }, readyTimeoutMs);
+        processHandle.on('message', (raw) => { this.#onMessage(child, raw); });
+        // Bridge streams (routes, HTTP, WebSocket) of this child go to the transport.
+        this.transport.attachChildProcess(processHandle);
+        processHandle.once('error', (error) => {
+            // Spawn failures (ENOENT, EACCES) emit `error` and no `exit`.
+            if (processHandle.pid !== undefined && processHandle.exitCode === null && processHandle.signalCode === null)
+                return;
+            child.failure ??= this.#failure('spawn-error', `Failed to spawn the instance: ${error.message}`, null, null);
+            this.#onExit(child, null, null);
+        });
+        // Let stdout / stderr drain so the log tail is complete, but do not wait on `close`: a
+        // grandchild that inherited the pipes could hold them open long after the instance died.
+        const drained = Promise.all([processHandle.stdout, processHandle.stderr].map((stream) => (stream && !stream.readableEnded
+            ? new Promise((resolve) => { stream.once('end', resolve); stream.once('close', resolve); })
+            : undefined)));
+        processHandle.once('exit', (code, signal) => {
+            const settle = () => {
+                clearTimeout(timer);
+                this.#onExit(child, code, signal);
+            };
+            const timer = setTimeout(settle, STDIO_DRAIN_MS);
+            void drained.then(settle);
+        });
+        return guarded;
+    }
+    #onMessage(child, raw) {
+        if (this.#child !== child)
+            return;
+        const message = parseInstanceMessage(raw);
+        if (!message)
+            return;
+        if (message.type === 'ready') {
+            if (child.ready || child.terminating)
+                return;
+            clearTimeout(child.readyTimer);
+            if (!this.#accepted.includes(message.payload.version)) {
+                const error = new InstanceProtocolMismatchError(message.payload.version, this.#accepted);
+                child.failure = this.#failure('protocol-mismatch', error.message, null, null);
+                child.settleStart?.(error);
+                void this.#terminate(child, 'protocol-mismatch');
+                return;
+            }
+            child.ready = true;
+            this.#ready = message.payload;
+            this.#startedAt = Date.now();
+            this.#setState('running');
+            this.emit('ready', message.payload);
+            child.settleStart?.();
+            return;
+        }
+        if (message.type !== 'restart-request')
+            return;
+        this.emit('restart-request', message.payload);
+        if (this.#options.restart?.onRequest === false)
+            return;
+        if (!child.ready || child.terminating || this.#state !== 'running')
+            return;
+        if (!this.#admitRestart()) {
+            child.failure = this.#failure('restart-storm', `Too many restarts within ${this.#windowMs()} ms; the instance stays stopped`, null, null);
+            void this.#terminate(child, 'restart-storm');
+            return;
+        }
+        // Respawned straight from the exit handler, so observers never see a transient `stopped`.
+        child.restartIntent = this.#stopIntent;
+        this.#setState('stopping');
+        void this.#terminate(child, `restart:${message.payload.reason}`);
+    }
+    #onExit(child, code, signal) {
+        if (this.#child !== child)
+            return;
+        clearTimeout(child.readyTimer);
+        clearTimeout(child.termTimer);
+        clearTimeout(child.killTimer);
+        this.logs.flush();
+        this.#child = undefined;
+        const expected = child.terminating;
+        const exit = Object.freeze({ code, signal, expected });
+        this.#lastExit = exit;
+        this.emit('exit', exit);
+        if (child.failure) {
+            const failure = { ...child.failure, exitCode: code, signal };
+            this.#afterFailedChild(Object.freeze(failure), child.failure.reason === 'ready-timeout');
+            child.settleStart?.(new InstanceStartError(failure));
+        }
+        else if (child.restartIntent !== undefined && child.restartIntent === this.#stopIntent) {
+            child.resolveExited(exit);
+            void this.#spawn().catch(() => undefined);
+            return;
+        }
+        else if (expected || (code === 0 && signal === null)) {
+            // Requested stop, or the instance ended on its own cleanly (e.g. `--once`).
+            this.#setState('stopped');
+            child.settleStart?.(new InstanceStartError(this.#failure('exit', 'Instance exited before it was ready', code, signal)));
+        }
+        else {
+            const failure = this.#failure('exit', `Instance exited unexpectedly (code ${code ?? 'none'}${signal ? `, signal ${signal}` : ''})`, code, signal);
+            this.#afterFailedChild(failure, true);
+            child.settleStart?.(new InstanceStartError(failure));
+        }
+        child.resolveExited(exit);
+    }
+    /** Records a failure and either schedules a restart (`backoff`) or stays `crashed`. */
+    #afterFailedChild(failure, restartable) {
+        this.#lastFailure = failure;
+        this.emit('failure', failure);
+        if (restartable && this.#options.restart?.onCrash !== false && this.#admitRestart()) {
+            this.#setState('backoff');
+            this.#backoffTimer = setTimeout(() => {
+                this.#backoffTimer = undefined;
+                if (this.#state === 'backoff')
+                    void this.#spawn().catch(() => undefined);
+            }, this.#options.restart?.delayMs ?? RESTART_DELAY_MS);
+            return;
+        }
+        if (restartable && this.#options.restart?.onCrash !== false) {
+            this.#lastFailure = Object.freeze({
+                ...failure,
+                reason: 'restart-storm',
+                message: `${failure.message}; too many restarts within ${this.#windowMs()} ms, the instance stays crashed`,
+            });
+            this.emit('failure', this.#lastFailure);
+        }
+        this.#setState('crashed');
+    }
+    #terminate(child, reason, timeoutMs) {
+        if (child.terminating)
+            return child.exited;
+        child.terminating = true;
+        clearTimeout(child.readyTimer);
+        const budgetMs = this.#options.shutdownBudgetMs ?? DEFAULT_SHUTDOWN_BUDGET_MS;
+        const waitMs = timeoutMs ?? budgetMs + 1_000;
+        const killGraceMs = this.#options.killGraceMs ?? DEFAULT_INSTANCE_KILL_GRACE_MS;
+        const escalate = () => {
+            if (this.#child !== child)
+                return;
+            try {
+                child.process.kill('SIGTERM');
+            }
+            catch { /* already gone */ }
+            child.killTimer = setTimeout(() => {
+                if (this.#child !== child)
+                    return;
+                try {
+                    child.process.kill('SIGKILL');
+                }
+                catch { /* already gone */ }
+            }, killGraceMs);
+        };
+        if (child.process.connected) {
+            const message = { type: 'shutdown', payload: { reason, budgetMs } };
+            try {
+                child.process.send(message, () => undefined);
+            }
+            catch { /* channel closed */ }
+            child.termTimer = setTimeout(escalate, waitMs);
+        }
+        else {
+            escalate();
+        }
+        return child.exited;
+    }
+    #admitRestart(now = Date.now()) {
+        const recent = this.#recentRestarts(now);
+        if (recent.length >= (this.#options.restart?.maxRestarts ?? MAX_RESTARTS_PER_WINDOW)) {
+            this.#restartTimes = recent;
+            return false;
+        }
+        this.#restartTimes = [...recent, now];
+        return true;
+    }
+    #recentRestarts(now) {
+        const windowMs = this.#windowMs();
+        return this.#restartTimes.filter((time) => now - time < windowMs);
+    }
+    #windowMs() { return this.#options.restart?.windowMs ?? RESTART_WINDOW_MS; }
+    #failure(reason, message, exitCode, signal) {
+        return Object.freeze({
+            reason,
+            message,
+            at: Date.now(),
+            exitCode,
+            signal,
+            logTail: Object.freeze(this.logs.tail(FAILURE_LOG_TAIL_LINES).map((line) => line.line)),
+        });
+    }
+    #clearBackoff() {
+        if (this.#backoffTimer)
+            clearTimeout(this.#backoffTimer);
+        this.#backoffTimer = undefined;
+    }
+    #setState(state) {
+        if (this.#state === state)
+            return;
+        this.#state = state;
+        this.emit('state', this.status());
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/lib/supervisor/run-instance.d.ts

@@ -0,0 +1,35 @@
+import type { StartOptions } from '@zhin.js/runtime';
+import { InstanceSupervisor } from './instance-supervisor.js';
+import type { InstanceLogOptions } from './instance-logs.js';
+/** Default daemon log file (ADR 0054 §3). */
+export declare function defaultInstanceLogFile(root: string): string;
+/** Whether this process is the supervised instance child rather than the supervisor. */
+export declare function isSupervisedInstanceProcess(environment?: Readonly<Record<string, string | undefined>>): boolean;
+/** Preserve process loader configuration when the supervisor creates a child. */
+export declare function supervisedNodeArguments(execArguments?: readonly string[]): readonly string[];
+export interface RunSupervisedInstanceOptions {
+    readonly root: string;
+    readonly options: StartOptions;
+    /** Executable script the child runs; defaults to `process.argv[1]` (the `zhin` CLI). */
+    readonly entry?: string;
+    /** Arguments after the entry; defaults to `process.argv.slice(2)`. */
+    readonly args?: readonly string[];
+    readonly logs?: Omit<InstanceLogOptions, 'file'>;
+    /**
+     * Attaches a component (the gateway HTTP server) to the supervisor before the instance starts;
+     * closed when the run ends. Its `keepAlive()` keeps the run going while it owns the instance's
+     * lifecycle (a Console stop, a dependency transaction).
+     */
+    readonly attach?: (supervisor: InstanceSupervisor) => Promise<SupervisedAttachment>;
+}
+export interface SupervisedAttachment {
+    /** True while a stopped / crashed instance must not end the run. */
+    keepAlive?(): boolean;
+    close(): Promise<void>;
+}
+/**
+ * Runs the instance under supervision and resolves with the exit code this process should use.
+ * Foreground runs share the terminal (`inherit`) and do not restart crashes; `--daemon` captures
+ * output into a rotated log file and restarts crashes with storm protection; `--once` never restarts.
+ */
+export declare function runSupervisedInstance(input: RunSupervisedInstanceOptions): Promise<number>;

package/lib/supervisor/run-instance.js

@@ -0,0 +1,161 @@
+/**
+ * Parent side of `zhin runtime start`: runs the instance under an {@link InstanceSupervisor} until it
+ * stops for good (signal, clean exit, or crash without restart).
+ */
+import { readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { INSTANCE_CHILD_ENV } from '@zhin.js/host-http/bridge';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { isNodeVersionSupported, NODE_ENGINES_HINT } from '../project/node-requirements.js';
+import { InstanceSupervisor } from './instance-supervisor.js';
+const DISABLE_EXPERIMENTAL_WARNING_FLAG = '--disable-warning=ExperimentalWarning';
+const NODE_LOADER_OPTIONS = new Set([
+    '--conditions',
+    '--experimental-loader',
+    '--import',
+    '--loader',
+    '--require',
+    '-C',
+    '-r',
+]);
+/** Default daemon log file (ADR 0054 §3). */
+export function defaultInstanceLogFile(root) {
+    return join(root, '.zhin', 'logs', 'instance.log');
+}
+/** Whether this process is the supervised instance child rather than the supervisor. */
+export function isSupervisedInstanceProcess(environment = process.env) {
+    return Boolean(environment[INSTANCE_CHILD_ENV]);
+}
+/** Preserve process loader configuration when the supervisor creates a child. */
+export function supervisedNodeArguments(execArguments = process.execArgv) {
+    const inherited = [];
+    for (let index = 0; index < execArguments.length; index += 1) {
+        const argument = execArguments[index];
+        const option = argument.split('=', 1)[0];
+        if (!NODE_LOADER_OPTIONS.has(option))
+            continue;
+        inherited.push(argument);
+        if (argument === option) {
+            const value = execArguments[index + 1];
+            if (value !== undefined) {
+                inherited.push(value);
+                index += 1;
+            }
+        }
+    }
+    return Object.freeze([
+        ...inherited,
+        '--experimental-strip-types',
+        DISABLE_EXPERIMENTAL_WARNING_FLAG,
+    ]);
+}
+const KEEP_ALIVE_POLL_MS = 500;
+/**
+ * Runs the instance under supervision and resolves with the exit code this process should use.
+ * Foreground runs share the terminal (`inherit`) and do not restart crashes; `--daemon` captures
+ * output into a rotated log file and restarts crashes with storm protection; `--once` never restarts.
+ */
+export async function runSupervisedInstance(input) {
+    if (!isNodeVersionSupported()) {
+        throw new Error(`zhin runtime start requires Node ${NODE_ENGINES_HINT}; found ${process.versions.node}`);
+    }
+    const entry = input.entry ?? process.argv[1];
+    if (!entry)
+        throw new Error('Cannot determine the zhin runtime executable path');
+    const { root, options } = input;
+    const logger = getLogger('runtime');
+    const pidFile = join(root, '.zhin.pid');
+    const logFile = options.daemon ? (options.logFile ?? defaultInstanceLogFile(root)) : undefined;
+    if (logFile)
+        await mkdir(dirname(logFile), { recursive: true });
+    const supervisor = new InstanceSupervisor({
+        spawn: {
+            command: process.execPath,
+            args: [...supervisedNodeArguments(), entry, ...(input.args ?? process.argv.slice(2))],
+            cwd: root,
+        },
+        output: options.daemon ? 'pipe' : 'inherit',
+        logs: { ...input.logs, file: logFile ?? false },
+        restart: {
+            onCrash: options.daemon && !options.once,
+            onRequest: !options.once,
+        },
+    });
+    if (options.daemon) {
+        writeFileSync(pidFile, String(process.pid));
+        logger.info(formatCompact({
+            op: 'daemon_start', pid: process.pid, log: logFile,
+            hint: `stop: zhin stop 或 kill -TERM ${process.pid}`,
+        }));
+    }
+    supervisor.on('failure', (failure) => {
+        logger.warn(formatCompact({ op: 'instance_failure', reason: failure.reason, message: failure.message }));
+    });
+    supervisor.on('restart-request', (request) => {
+        logger.info(formatCompact({ op: 'instance_restart_request', reason: request.reason }));
+    });
+    let interrupted = false;
+    const onSignal = () => {
+        // A second signal kills the instance without waiting for its graceful stop.
+        const force = interrupted;
+        interrupted = true;
+        void supervisor.stop({ reason: 'signal', force });
+    };
+    const onSighup = () => { if (!options.daemon)
+        onSignal(); };
+    const onExit = () => {
+        supervisor.dispose();
+        removePidFile();
+    };
+    const removePidFile = () => {
+        if (!options.daemon)
+            return;
+        try {
+            if (readFileSync(pidFile, 'utf8').trim() === String(process.pid))
+                rmSync(pidFile, { force: true });
+        }
+        catch { /* already gone */ }
+    };
+    process.on('SIGINT', onSignal);
+    process.on('SIGTERM', onSignal);
+    process.on('SIGHUP', onSighup);
+    process.on('exit', onExit);
+    let attachment;
+    let keepAliveTimer;
+    try {
+        attachment = await input.attach?.(supervisor);
+        const ended = () => (supervisor.state === 'stopped' || supervisor.state === 'crashed')
+            && (interrupted || attachment?.keepAlive?.() !== true);
+        const settled = new Promise((resolve) => {
+            const check = () => {
+                if (ended())
+                    resolve(supervisor.status());
+            };
+            supervisor.on('state', check);
+            if (attachment?.keepAlive) {
+                keepAliveTimer = setInterval(check, KEEP_ALIVE_POLL_MS);
+                keepAliveTimer.unref?.();
+            }
+        });
+        await supervisor.start().catch(() => undefined);
+        const status = ended() ? supervisor.status() : await settled;
+        if (interrupted)
+            return status.lastExitCode ?? 130;
+        if (status.state === 'crashed')
+            return status.lastExitCode || 1;
+        return status.lastExitCode ?? 0;
+    }
+    finally {
+        clearInterval(keepAliveTimer);
+        await attachment?.close().catch((error) => {
+            logger.warn(formatCompact({ op: 'gateway_close_failed', error: error instanceof Error ? error.message : String(error) }));
+        });
+        process.off('SIGINT', onSignal);
+        process.off('SIGTERM', onSignal);
+        process.off('SIGHUP', onSighup);
+        process.off('exit', onExit);
+        supervisor.dispose();
+        removePidFile();
+    }
+}

package/lib/supervisor/terminal-state.d.ts

@@ -0,0 +1,30 @@
+export interface TerminalProbe {
+    readonly platform?: NodeJS.Platform;
+    readonly pid?: number;
+    /** `/proc/<pid>/stat` text (Linux). */
+    readonly readStat?: (pid: number) => string;
+    /** `ps -o pgid=,tpgid= -p <pid>` output (other Unix). */
+    readonly ps?: (pid: number) => string;
+}
+/**
+ * Whether this process is in the terminal's foreground process group. A background job
+ * (`zhin start --foreground &`) must not hand its TTY stdin to the instance: reading it would
+ * stop the instance with SIGTTIN. Unknown (no controlling terminal, probe failed) counts as
+ * foreground, the previous behaviour.
+ */
+export declare function isForegroundProcessGroup(probe?: TerminalProbe): boolean;
+export interface TerminalState {
+    /** Puts the terminal back as it was when captured (e.g. after an instance left it in raw mode). */
+    restore(): void;
+}
+/** Runs `stty` on the inherited terminal; undefined when it fails. */
+export type SttyRunner = (args: readonly string[]) => string | undefined;
+/**
+ * Saves the terminal settings (`stty -g`) so they can be restored once the instance that shares
+ * the TTY exits — a crashed terminal adapter can leave it in raw / no-echo mode. Undefined on
+ * Windows or without a usable `stty`.
+ */
+export declare function captureTerminalState(options?: {
+    readonly platform?: NodeJS.Platform;
+    readonly stty?: SttyRunner;
+}): TerminalState | undefined;