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

package/lib/http/plugin-switch-rpc.js

@@ -0,0 +1,214 @@
+/**
+ * The Console's global plugin switch, answered by the gateway (ADR 0054 §4, ADR 0050 §4):
+ * `plugin:set-enabled` and `feature.set-enabled` with `level: 'global'` both write
+ * `disable_plugins`, which is plugin lifecycle rather than a feature switch. The gateway
+ * intercepts them on `POST {base}/console/request` before anything is forwarded, authorizes them
+ * with `plugin.manage` (the shared permission map refines `feature.set-enabled` by level), and
+ * runs the enable / disable transaction of {@link GatewayPackageService.setEnabled}: stop the
+ * instance → write `disable_plugins` → start it, restoring the file and the old instance on
+ * failure. `feature.set-enabled` below the global level is forwarded to the instance untouched.
+ *
+ * Replies keep the shapes the instance used to send, so a published Console keeps working:
+ * - `plugin:set-enabled`: `{ success, instanceKey, enabled, disabled, restartRequired, message }`;
+ * - `feature.set-enabled`: `ConsoleFeatureWriteResult` (`saved` / `unchanged`) with the
+ *   configuration revision after the write and the override warnings of the new state.
+ * Both add `transaction` (the gateway transaction result). A failed or rolled-back transaction
+ * answers the RPC's error envelope (`success: false`, `code`, `error`) with `transaction`.
+ */
+import { join } from 'node:path';
+import { auditActor, authorizeConsoleRpc, jsonResponse, rpcAuditDetail, rpcAuditTarget, } from '@zhin.js/host-http';
+import { FEATURE_RPC, PLUGIN_RPC, isGlobalFeatureSwitch, } from '@zhin.js/console-protocol';
+import { DEFAULT_ROOT_CONFIG_FILE_NAME, FEATURE_OVERRIDES_KEY } from '@zhin.js/plugin-runtime';
+import { collectFeatureOverrideWarnings, createConfigDocument } from '@zhin.js/runtime';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { GatewayError } from '../packages/errors.js';
+import { findConfigFile } from '../project/config-file.js';
+const logger = getLogger('gateway');
+/** Top-level plugin instance alias (the global switch only applies to top-level instances). */
+const INSTANCE_KEY = /^[a-z0-9][a-z0-9-]*$/u;
+/** Whether the gateway answers this Console RPC message itself (the global plugin switch). */
+export function isGatewayPluginSwitch(message) {
+    return message.type === PLUGIN_RPC.SET_ENABLED || isGlobalFeatureSwitch(message);
+}
+export function createGatewayPluginSwitchRpc(options) {
+    const readConfig = options.readConfig ?? (async () => {
+        const file = join(options.projectRoot, findConfigFile(options.projectRoot) ?? DEFAULT_ROOT_CONFIG_FILE_NAME);
+        const { revision, document } = await createConfigDocument(file).read();
+        return { revision, document: document };
+    });
+    return Object.freeze({
+        owns: (type) => type === PLUGIN_RPC.SET_ENABLED || type === FEATURE_RPC.SET_ENABLED,
+        claims: isGatewayPluginSwitch,
+        async handle(message, context, registry) {
+            const noStore = { 'cache-control': 'no-store' };
+            const type = String(message.type ?? '');
+            const requestId = message.requestId;
+            const principal = context.principal;
+            if (!principal) {
+                return jsonResponse(401, { success: false, code: 'unauthorized', error: 'Invalid or missing token', requestId }, noStore);
+            }
+            // plugin.manage: `plugin:set-enabled` is mapped to it, `feature.set-enabled` is refined by level.
+            const decision = authorizeConsoleRpc(principal, message);
+            const audit = (outcome) => {
+                try {
+                    registry.accessProvider?.audit?.({
+                        actor: auditActor(principal),
+                        action: `rpc:${type}`.slice(0, 256),
+                        ...(decision.allowed && rpcAuditTarget(decision.rule) ? { target: rpcAuditTarget(decision.rule) } : {}),
+                        outcome,
+                        detail: rpcAuditDetail(message),
+                        ...(context.remoteAddress ? { ip: context.remoteAddress } : {}),
+                    });
+                }
+                catch { /* audit never breaks a request */ }
+            };
+            if (!decision.allowed) {
+                audit('denied');
+                return jsonResponse(403, { success: false, code: decision.code, error: decision.error, requestId }, noStore);
+            }
+            const reply = type === PLUGIN_RPC.SET_ENABLED
+                ? await setPluginEnabled(message, principal, options, readConfig)
+                : await setFeatureGlobal(message, principal, options, readConfig);
+            audit(reply.status < 400 && reply.body.success !== false ? 'ok' : reply.status === 403 ? 'denied' : 'error');
+            return jsonResponse(reply.status, { ...reply.body, requestId }, noStore);
+        },
+    });
+}
+/** `plugin:set-enabled` `{ instanceKey, enabled }` (top-level fields, as the Console sends them). */
+async function setPluginEnabled(message, principal, options, readConfig) {
+    const type = PLUGIN_RPC.SET_ENABLED;
+    const instanceKey = typeof message.instanceKey === 'string' ? message.instanceKey.trim() : '';
+    const enabled = message.enabled;
+    if (!instanceKey || typeof enabled !== 'boolean')
+        return error(400, 'invalid_input', 'instanceKey and boolean enabled are required', type);
+    const outcome = await runSwitch(instanceKey, enabled, principal, options, type);
+    if ('reply' in outcome)
+        return outcome.reply;
+    const { result } = outcome;
+    const config = await readConfig().catch(() => undefined);
+    const key = result.plugin?.instanceKey ?? instanceKey;
+    const changed = result.plugin?.changed === true;
+    return {
+        status: 200,
+        body: {
+            success: true,
+            type,
+            data: {
+                success: true,
+                instanceKey: key,
+                enabled,
+                disabled: disabledPlugins(config?.document),
+                // The gateway restarted the instance for a change (it already is back): the Console re-syncs.
+                restartRequired: changed,
+                message: switchMessage(key, enabled, changed),
+                transaction: result,
+            },
+        },
+    };
+}
+/** `feature.set-enabled` with `level: 'global'`, payload in `data` (or on the message). */
+async function setFeatureGlobal(message, principal, options, readConfig) {
+    const type = FEATURE_RPC.SET_ENABLED;
+    const data = message.data;
+    const input = (data && typeof data === 'object' && !Array.isArray(data) ? data : message);
+    const plugin = input.plugin;
+    if (typeof plugin !== 'string' || !plugin)
+        return error(400, undefined, '缺少 plugin', type);
+    if (input.key !== undefined && input.key !== '')
+        return error(400, undefined, 'global 层不需要 key', type);
+    if (!INSTANCE_KEY.test(plugin)) {
+        return error(400, undefined, plugin.includes('/') ? '全局开关只适用于顶层插件实例' : 'plugin 必须是插件实例别名', type);
+    }
+    if (typeof input.enabled !== 'boolean')
+        return error(400, undefined, 'enabled 必须是布尔值', type);
+    const enabled = input.enabled;
+    const outcome = await runSwitch(plugin, enabled, principal, options, type);
+    if ('reply' in outcome)
+        return outcome.reply;
+    const { result } = outcome;
+    const config = await readConfig().catch((failure) => {
+        logger.warn(formatCompact({ op: 'gateway_plugin_switch_config_read_failed', error: failure instanceof Error ? failure.message : String(failure) }));
+        return undefined;
+    });
+    const revision = config?.revision ?? '';
+    const changed = result.plugin?.changed === true;
+    if (!changed) {
+        return { status: 200, body: { success: true, type, data: Object.freeze({ status: 'unchanged', revision, warnings: Object.freeze([]), transaction: result }) } };
+    }
+    return {
+        status: 200,
+        body: {
+            success: true,
+            type,
+            data: Object.freeze({
+                status: 'saved',
+                revision,
+                // The instance was restarted by the gateway transaction (it already is back).
+                restartRequired: true,
+                warnings: config ? overrideWarnings(config.document, plugin) : Object.freeze([]),
+                message: switchMessage(plugin, enabled, true),
+                transaction: result,
+            }),
+        },
+    };
+}
+/** Runs the transaction; a refusal or a failed / rolled-back transaction becomes an error reply. */
+async function runSwitch(plugin, enabled, principal, options, type) {
+    if (!options.packages)
+        return { reply: error(503, 'unavailable', '插件启停不可用：网关未管理依赖', type) };
+    let result;
+    try {
+        result = await options.packages.setEnabled({ plugin }, enabled, { principal });
+    }
+    catch (failure) {
+        if (failure instanceof GatewayError) {
+            return {
+                reply: error(failure.status, failure.code, failure.message, type, {
+                    ...(failure.details?.errors ? { errors: failure.details.errors } : {}),
+                    ...(failure.details?.missingEnv ? { missingEnv: failure.details.missingEnv } : {}),
+                }),
+            };
+        }
+        logger.warn(formatCompact({ op: 'gateway_plugin_switch_failed', plugin, error: failure instanceof Error ? failure.message : String(failure) }));
+        return { reply: error(500, 'internal', '插件启停失败', type) };
+    }
+    if (result.ok)
+        return { result };
+    const action = enabled ? '启用' : '停用';
+    const text = result.status === 'rollbackFailed'
+        ? `${action} ${plugin} 失败，且回滚未完成：${result.rollbackError ?? '未知错误'}（原因：${result.error ?? '未知错误'}）`
+        : `${action} ${plugin} 失败，已回滚：${result.error ?? '未知错误'}`;
+    return {
+        reply: error(500, result.status === 'rollbackFailed' ? 'rollback_failed' : 'transaction_failed', text, type, {
+            transaction: result,
+            ...(result.errors?.length ? { errors: result.errors } : {}),
+            ...(result.missingEnv?.length ? { missingEnv: result.missingEnv } : {}),
+        }),
+    };
+}
+function error(status, code, message, type, extra = {}) {
+    return { status, body: { success: false, ...(code ? { code } : {}), error: message, type, ...extra } };
+}
+function switchMessage(plugin, enabled, changed) {
+    const action = enabled ? '启用' : '停用';
+    return changed ? `${plugin} 已${action}，实例已由管理网关重启` : `${plugin} 已处于${action}状态`;
+}
+function disabledPlugins(document) {
+    const list = document?.disable_plugins;
+    return Object.freeze(Array.isArray(list) ? list.filter((item) => typeof item === 'string') : []);
+}
+/** The global plugin switch's warnings about the plugin's own overrides (as the instance computed them). */
+function overrideWarnings(document, plugin) {
+    const block = document[plugin];
+    const overrides = block && typeof block === 'object' && !Array.isArray(block) ? block[FEATURE_OVERRIDES_KEY] : undefined;
+    if (overrides === undefined)
+        return Object.freeze([]);
+    try {
+        const enabled = !disabledPlugins(document).includes(plugin);
+        return Object.freeze(collectFeatureOverrideWarnings(document, plugin, overrides, enabled)
+            .map(({ code, path, message }) => Object.freeze({ code, path, message })));
+    }
+    catch {
+        return Object.freeze([]);
+    }
+}

package/lib/http/run-gateway.d.ts

@@ -0,0 +1,43 @@
+import { type ResolvedHttpConfig } from '@zhin.js/host-http';
+import type { LocalGatewayInfo } from '../local/protocol.js';
+import { type InstanceRestartPolicy } from '../supervisor/instance-supervisor.js';
+import { type RunSupervisedInstanceOptions } from '../supervisor/run-instance.js';
+import { type RunningGateway } from './start-gateway.js';
+/** Set on the instance when its output is echoed to an interactive terminal (TTY-style logging). */
+export declare const INSTANCE_INTERACTIVE_ENV = "ZHIN_INSTANCE_INTERACTIVE";
+export interface RunGatewayOptions extends Omit<RunSupervisedInstanceOptions, 'attach'> {
+    /** Overrides the project's `http` block (tests). */
+    readonly http?: ResolvedHttpConfig;
+    /** Local control socket; `false` disables it. Default: `.zhin/gateway.sock` / the named pipe. */
+    readonly localSocket?: false | {
+        readonly path?: string;
+        readonly uid?: () => number | undefined;
+    };
+    /** Echo instance output to this process. Default: not in `--daemon` mode. */
+    readonly echo?: boolean;
+    /** Handle SIGINT / SIGTERM / SIGHUP. Default true. */
+    readonly signals?: boolean;
+    /** Overrides the crash / storm policy (default: ADR 0054 §5, restarts off with `--once`). */
+    readonly restart?: InstanceRestartPolicy;
+    /** Called once the gateway serves HTTP and the local socket. */
+    readonly onReady?: (gateway: RunningGatewayProcess) => void;
+}
+export interface RunningGatewayProcess {
+    readonly gateway: RunningGateway;
+    readonly info: LocalGatewayInfo;
+    /** Ends the run (as `gateway.shutdown` does). */
+    shutdown(exitCode?: number): void;
+}
+/** `@zhin.js/gateway` version. */
+export declare function gatewayVersion(): string;
+/** Console link in the ADR 0053 format: `?apiBaseUrl=`, the token only after `#`. */
+export declare function consoleLink(origin: string, token?: string): string;
+/**
+ * Whether the instance gets the gateway's stdin: a foreground gateway whose stdin is a TTY and
+ * that is the terminal's foreground job (a background job's child reading the TTY gets SIGTTIN).
+ */
+export declare function foregroundStdin(daemon: boolean, stdin?: {
+    readonly isTTY?: boolean;
+}, foregroundGroup?: () => boolean): boolean;
+/** Runs the gateway until it is shut down; resolves with the exit code for this process. */
+export declare function runGateway(input: RunGatewayOptions): Promise<number>;

package/lib/http/run-gateway.js

@@ -0,0 +1,268 @@
+/**
+ * The gateway process (ADR 0054 §1 / §5 / §6): `zhin start` / `zhin runtime start` / `pnpm dev`.
+ * Long-lived: the instance crashing, entering `crashed` after a restart storm, or being stopped
+ * from the Console / CLI does not end it. It ends on SIGINT / SIGTERM (both processes stop) or
+ * `gateway.shutdown` on the local control socket. Only `--once` (CI) still ends with the instance.
+ */
+import { randomBytes } from 'node:crypto';
+import { readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdir, rm } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { REMOTE_CONSOLE_ORIGIN } from '@zhin.js/host-http';
+import { GATEWAY_SOCKET_ENV } from '@zhin.js/host-http/bridge';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { instanceStatus } from '../packages/rpc.js';
+import { createLocalRpcHandler } from '../local/handler.js';
+import { LocalControlServer, LocalSocketError, probeLocalSocket } from '../local/local-socket.js';
+import { gatewayInfoFile, gatewaySocketPath, isNamedPipe } from '../local/paths.js';
+import { readGatewayInfo, removeGatewayInfo, writeGatewayInfo } from '../local/state-file.js';
+import { isNodeVersionSupported, NODE_ENGINES_HINT } from '../project/node-requirements.js';
+import { InstanceSupervisor } from '../supervisor/instance-supervisor.js';
+import { defaultInstanceLogFile, supervisedNodeArguments } from '../supervisor/run-instance.js';
+import { captureTerminalState, isForegroundProcessGroup } from '../supervisor/terminal-state.js';
+import { startGateway } from './start-gateway.js';
+/** Set on the instance when its output is echoed to an interactive terminal (TTY-style logging). */
+export const INSTANCE_INTERACTIVE_ENV = 'ZHIN_INSTANCE_INTERACTIVE';
+let cachedVersion;
+/** `@zhin.js/gateway` version. */
+export function gatewayVersion() {
+    if (cachedVersion)
+        return cachedVersion;
+    try {
+        const manifest = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+        cachedVersion = typeof manifest.version === 'string' ? manifest.version : '0.0.0';
+    }
+    catch {
+        cachedVersion = '0.0.0';
+    }
+    return cachedVersion;
+}
+/** Console link in the ADR 0053 format: `?apiBaseUrl=`, the token only after `#`. */
+export function consoleLink(origin, token) {
+    const url = `${REMOTE_CONSOLE_ORIGIN}/?apiBaseUrl=${encodeURIComponent(origin)}`;
+    return token ? `${url}#token=${encodeURIComponent(token)}` : url;
+}
+/**
+ * Whether the instance gets the gateway's stdin: a foreground gateway whose stdin is a TTY and
+ * that is the terminal's foreground job (a background job's child reading the TTY gets SIGTTIN).
+ */
+export function foregroundStdin(daemon, stdin = process.stdin, foregroundGroup = isForegroundProcessGroup) {
+    return !daemon && stdin.isTTY === true && foregroundGroup();
+}
+/**
+ * The local control endpoint of this run. Windows named pipes get a fresh random name component
+ * (Node cannot set a DACL on them; see `windowsPipeName`), so a second gateway on the project is
+ * detected through the pipe the state file records instead of a name clash.
+ */
+async function localEndpoint(root, platform = process.platform) {
+    if (platform !== 'win32')
+        return gatewaySocketPath(root, { platform });
+    const recorded = await readGatewayInfo(root);
+    if (recorded && isNamedPipe(recorded.socket) && await probeLocalSocket(recorded.socket).catch(() => 'live') === 'live') {
+        throw new LocalSocketError('in_use', `另一个网关正在使用 ${recorded.socket}`);
+    }
+    return gatewaySocketPath(root, { platform, nonce: randomBytes(8).toString('hex') });
+}
+/** Strips the `zhin runtime start` / `zhin start` prefix of the instance arguments. */
+function startArguments(args) {
+    if (args[0] === 'runtime' && args[1] === 'start')
+        return args.slice(2);
+    if (args[0] === 'start')
+        return args.slice(1);
+    return args;
+}
+/** Runs the gateway until it is shut down; resolves with the exit code for this process. */
+export async function runGateway(input) {
+    if (!isNodeVersionSupported()) {
+        throw new Error(`zhin 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 executable path');
+    const { root, options } = input;
+    const logger = getLogger('gateway');
+    const args = [...(input.args ?? process.argv.slice(2))];
+    const daemon = options.daemon;
+    const echo = input.echo ?? !daemon;
+    const interactive = echo && process.stdout.isTTY === true;
+    const logFile = options.logFile ?? defaultInstanceLogFile(root);
+    await mkdir(dirname(logFile), { recursive: true });
+    const socketPath = input.localSocket === false ? undefined : input.localSocket?.path ?? await localEndpoint(root);
+    // Keyed proof the CLI checks before it talks to the endpoint (only in the 0600 state file).
+    const handshakeKey = randomBytes(32).toString('hex');
+    const shareTerminal = foregroundStdin(daemon);
+    // The instance may leave the shared terminal raw / without echo when it exits or crashes.
+    const terminal = shareTerminal ? captureTerminalState() : undefined;
+    // gateway.readyTimeout: startGateway re-reads it before every start, restart and transaction.
+    const supervisor = new InstanceSupervisor({
+        spawn: {
+            command: process.execPath,
+            args: [...supervisedNodeArguments(), entry, ...args],
+            cwd: root,
+            env: {
+                ...process.env,
+                // The instance keeps the Agent's file / shell tools away from the owner endpoint.
+                ...(socketPath ? { [GATEWAY_SOCKET_ENV]: socketPath } : {}),
+                ...(interactive ? { [INSTANCE_INTERACTIVE_ENV]: '1', FORCE_COLOR: process.env.FORCE_COLOR ?? '1' } : {}),
+            },
+        },
+        output: 'pipe',
+        // Foreground on a TTY: the instance reads the terminal (terminal adapters); never in the background.
+        input: shareTerminal ? 'inherit' : 'ignore',
+        logs: { ...input.logs, file: logFile },
+        // The gateway outlives the instance (ADR 0054 §5); `--once` is a single check run.
+        restart: { onCrash: !options.once, onRequest: !options.once, ...input.restart },
+    });
+    if (echo) {
+        supervisor.on('log', (line) => {
+            (line.stream === 'stderr' ? process.stderr : process.stdout).write(`${line.line}\n`);
+        });
+    }
+    supervisor.on('state', (status) => {
+        if (terminal && (status.state === 'stopped' || status.state === 'crashed' || status.state === 'backoff'))
+            terminal.restore();
+        logger.info(formatCompact({ op: 'instance_state', state: status.state, ...(status.pid ? { pid: status.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 }));
+    });
+    const control = socketPath
+        ? await LocalControlServer.open({
+            path: socketPath,
+            handshakeKey,
+            // No other gateway serves the project: a state file left by a dead one is stale.
+            beforeListen: () => rm(gatewayInfoFile(root), { force: true }),
+            ...(input.localSocket && input.localSocket.uid ? { uid: input.localSocket.uid } : {}),
+        }).catch((error) => { supervisor.dispose(); throw error; })
+        : undefined;
+    let gateway;
+    try {
+        gateway = await startGateway({
+            projectRoot: root,
+            environment: options.environment,
+            ...(input.http ? { http: input.http } : {}),
+            supervisor,
+            transport: () => supervisor.transport,
+        });
+    }
+    catch (error) {
+        await control?.close();
+        supervisor.dispose();
+        throw error;
+    }
+    let resolveEnd;
+    const ended = new Promise((resolve) => { resolveEnd = resolve; });
+    let ending = false;
+    const shutdown = (exitCode = 0) => {
+        if (ending)
+            return;
+        ending = true;
+        logger.info(formatCompact({ op: 'gateway_stop' }));
+        resolveEnd(exitCode);
+    };
+    const addresses = gateway.http.addresses;
+    const info = Object.freeze({
+        pid: process.pid,
+        ports: Object.freeze(addresses.map((address) => address.port)),
+        origins: Object.freeze(addresses.map((address) => address.origin)),
+        socket: socketPath ?? '',
+        startedAt: Date.now(),
+        version: gatewayVersion(),
+        mode: daemon ? 'daemon' : 'foreground',
+        args: Object.freeze([...startArguments(args)]),
+        logFile,
+    });
+    const infoResult = () => Object.freeze({
+        gateway: info,
+        instance: instanceStatus(supervisor.status()),
+        consoleInitialized: gateway.http.tokenRegistry.initialized(),
+    });
+    control?.setHandler(createLocalRpcHandler({
+        dispatch: gateway.rpc,
+        ...(gateway.packages ? { packages: gateway.packages } : {}),
+        ...(gateway.console ? { console: gateway.console.localAdmin } : {}),
+        info: infoResult,
+        shutdown: () => shutdown(0),
+        http: (request) => gateway.http.localRequest(request),
+    }));
+    const pidFile = join(root, '.zhin.pid');
+    try {
+        writeFileSync(pidFile, String(process.pid));
+    }
+    catch { /* informational */ }
+    if (socketPath) {
+        await writeGatewayInfo(root, { ...info, handshakeKey }).catch((error) => {
+            logger.warn(formatCompact({ op: 'gateway_info_write_failed', error: error instanceof Error ? error.message : String(error) }));
+        });
+    }
+    const origin = info.origins[0];
+    logger.info(formatCompact({
+        op: 'gateway_listening', pid: process.pid, ...(origin ? { http: origin } : {}),
+        ...(socketPath ? { socket: socketPath } : {}), log: logFile,
+    }));
+    if (origin && !options.once)
+        logger.info(`Console: ${consoleLink(origin)}`);
+    let interrupted = 0;
+    const onSignal = (signal) => {
+        interrupted += 1;
+        // A second signal kills the instance without waiting for its graceful stop.
+        if (interrupted > 1)
+            void supervisor.stop({ reason: 'signal', force: true });
+        shutdown(signal === 'SIGINT' ? 130 : 0);
+    };
+    const onSighup = () => { if (!daemon)
+        onSignal('SIGHUP'); };
+    const onExit = () => {
+        supervisor.dispose();
+        terminal?.restore();
+        removePidFile();
+    };
+    const removePidFile = () => {
+        try {
+            if (readFileSync(pidFile, 'utf8').trim() === String(process.pid))
+                rmSync(pidFile, { force: true });
+        }
+        catch { /* already gone */ }
+    };
+    const signals = input.signals !== false;
+    if (signals) {
+        process.on('SIGINT', onSignal);
+        process.on('SIGTERM', onSignal);
+        process.on('SIGHUP', onSighup);
+    }
+    process.on('exit', onExit);
+    // `--once`: the run ends with the instance's single generation (CI check).
+    if (options.once) {
+        const check = (status = supervisor.status()) => {
+            if ((status.state === 'stopped' || status.state === 'crashed') && !gateway.ownsInstanceLifecycle()) {
+                shutdown(status.state === 'crashed' ? status.lastExitCode || 1 : status.lastExitCode ?? 0);
+            }
+        };
+        void gateway.instanceStarted.then(() => {
+            supervisor.on('state', check);
+            check();
+        });
+    }
+    input.onReady?.({ gateway, info, shutdown });
+    try {
+        return await ended;
+    }
+    finally {
+        await gateway.close().catch((error) => {
+            logger.warn(formatCompact({ op: 'gateway_close_failed', error: error instanceof Error ? error.message : String(error) }));
+        });
+        await control?.close().catch(() => undefined);
+        if (socketPath)
+            await removeGatewayInfo(root).catch(() => undefined);
+        if (signals) {
+            process.off('SIGINT', onSignal);
+            process.off('SIGTERM', onSignal);
+            process.off('SIGHUP', onSighup);
+        }
+        process.off('exit', onExit);
+        removePidFile();
+    }
+}

package/lib/http/start-gateway.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Gateway composition (ADR 0054 §1): the HTTP server and the instance supervisor, joined by a
+ * pluggable instance transport (the bridge supplies the IPC one). CLI wiring lives elsewhere.
+ */
+import { type ResolvedHttpConfig, type TokenRegistry } from '@zhin.js/host-http';
+import type { InstanceTransport } from '@zhin.js/host-http/bridge';
+import { InstanceSupervisor, type InstanceSupervisorOptions } from '../supervisor/instance-supervisor.js';
+import { GatewayPackageService } from '../packages/service.js';
+import { type GatewayRpcDispatcher } from '../packages/rpc.js';
+import { type GatewayConsole, type GatewayConsoleInstancePort, type GatewayConsoleOptions } from './gateway-console.js';
+import { GatewayHttpServer } from './gateway-http-server.js';
+/**
+ * A transport the gateway owns; `dispose` runs on gateway close. The Console module also uses the
+ * optional {@link GatewayConsoleInstancePort} methods (plugin catalog, instance audit,
+ * `principal-revoked`) when the transport has them (`IpcInstanceTransport` does).
+ */
+export interface GatewayInstanceTransport extends InstanceTransport, GatewayConsoleInstancePort {
+    dispose?(): void | Promise<void>;
+    /** Told the bound listener addresses after listen (the instance's `HttpHost.address`). */
+    setAddresses?(addresses: readonly import('@zhin.js/host-http').HttpHostAddress[]): void;
+}
+export interface InstanceTransportFactoryContext {
+    readonly supervisor: InstanceSupervisor;
+    readonly projectRoot: string;
+}
+export type InstanceTransportFactory = (context: InstanceTransportFactoryContext) => GatewayInstanceTransport;
+export interface StartGatewayOptions {
+    readonly projectRoot: string;
+    /** Selects `.env.<environment>` for `http.*` placeholders. Default `development`. */
+    readonly environment?: string;
+    /** Overrides the `http` block of the project config. */
+    readonly http?: ResolvedHttpConfig;
+    /** Instance supervision; pass a supervisor to own its construction. */
+    readonly supervisor: InstanceSupervisorOptions | InstanceSupervisor;
+    readonly transport: InstanceTransportFactory;
+    /** Console authentication registry (the Console module installs its access provider on it). */
+    readonly tokenRegistry?: TokenRegistry;
+    /**
+     * Console access control in the gateway (project database, `/auth/*`, `iam.*`, setup,
+     * onboarding, terminal, audit). Default on; `false` leaves only the bootstrap token (tests).
+     */
+    readonly console?: false | Omit<GatewayConsoleOptions, 'server' | 'projectRoot' | 'environment' | 'instance' | 'restartInstance'>;
+    /** Longest wait for the project database before listening anyway (default 10 s). */
+    readonly databaseWaitMs?: number;
+    readonly retryAfterSeconds?: number;
+    readonly maxRequestBodyBytes?: number;
+    /** Start the instance after the server listens. Default true; a failed start keeps the gateway up. */
+    readonly startInstance?: boolean;
+    /**
+     * Dependency transactions (`gateway.packages.*`). Default: a {@link GatewayPackageService} on
+     * the project root over the supervisor; `false` disables the package RPC.
+     */
+    readonly packages?: GatewayPackageService | false;
+    /**
+     * `gateway.readyTimeout` for dependency transactions when the project sets none (see
+     * {@link loadGatewaySettings}). Default 60 s.
+     */
+    readonly readyTimeoutMs?: number;
+    /**
+     * Reads the project's `gateway` block. Called before every instance start / restart (Console,
+     * CLI, automatic restart after a crash) and every dependency transaction, so a changed
+     * `gateway.readyTimeout` applies without restarting the gateway. Default
+     * {@link loadGatewaySettings} on the project root; `false` reads nothing.
+     */
+    readonly settings?: false | (() => Promise<GatewaySettings>);
+}
+export interface RunningGateway {
+    readonly http: GatewayHttpServer;
+    readonly supervisor: InstanceSupervisor;
+    readonly transport: GatewayInstanceTransport;
+    readonly packages: GatewayPackageService | undefined;
+    /** Console access control; undefined with `console: false`. */
+    readonly console: GatewayConsole | undefined;
+    /** The gateway RPC (`gateway.packages.*`, `gateway.instance.*`), shared with the local socket. */
+    readonly rpc: GatewayRpcDispatcher;
+    /**
+     * True while the gateway owns the instance's lifecycle: a dependency transaction runs, or the
+     * Console stopped the instance (a run must not end because of it).
+     */
+    ownsInstanceLifecycle(): boolean;
+    /** Resolves when the first instance start attempt settled (never rejects). */
+    readonly instanceStarted: Promise<void>;
+    /** Stops the instance, then closes the listeners. */
+    close(): Promise<void>;
+}
+/**
+ * Reads and resolves the project's `http` config the same way the instance used to. Only the
+ * `http` block is read: plugin declarations are not validated here, so a config the instance
+ * rejects still leaves the Console reachable.
+ */
+export declare function loadGatewayHttpConfig(projectRoot: string, environment?: string): Promise<ResolvedHttpConfig>;
+/** The project's `gateway` block (ADR 0054 §4 / §5). */
+export interface GatewaySettings {
+    /** `gateway.readyTimeout` (seconds) in ms; undefined: the built-in 60 s. */
+    readonly readyTimeoutMs?: number;
+}
+/**
+ * Reads the `gateway` block. An invalid value is logged and ignored (the instance rejects the
+ * config on its own); like {@link loadGatewayHttpConfig}, it never keeps the gateway down.
+ */
+export declare function loadGatewaySettings(projectRoot: string): Promise<GatewaySettings>;
+export declare function startGateway(options: StartGatewayOptions): Promise<RunningGateway>;
+/** Thrown when the gateway would serve an open Host on a network address. */
+export declare class OpenHostOnNetworkError extends Error {
+    readonly host: string;
+    readonly code = "ZHIN_OPEN_HOST_ON_NETWORK";
+    constructor(host: string);
+}
+/**
+ * An open Host (no bootstrap token, no owner yet) holds every permission and is only meant for
+ * this machine. The per-request loopback check cannot see through a same-host reverse proxy that
+ * adds no forwarding header, so a network-facing `http.host` must not start open (ADR 0049 §1).
+ */
+export declare function assertNotOpenOnNetwork(http: ResolvedHttpConfig, registry: TokenRegistry): void;