@undefineds.co/xpod 0.4.19 → 0.4.25

package/dist/cli/commands/agent-fs.js

@@ -0,0 +1,491 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentFsCommand = void 0;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = __importDefault(require("node:path"));
+const package_root_1 = require("../../runtime/package-root");
+const auth_context_1 = require("../lib/auth-context");
+const output_1 = require("../lib/output");
+const install_1 = require("../agent-fs/install");
+const mount_1 = require("../agent-fs/mount");
+const auth_proxy_1 = require("../agent-fs/auth-proxy");
+const native_1 = require("../agent-fs/native");
+const roots_1 = require("../agent-fs/roots");
+const session_view_1 = require("../agent-fs/session-view");
+const launcher_1 = require("../lib/launcher");
+function agentFsOptions(yargs) {
+    return yargs
+        .option('dir', {
+        type: 'string',
+        description: 'Wrapper install/session directory',
+    })
+        .option('root', {
+        type: 'array',
+        string: true,
+        description: 'Managed root mapping localPath=podRoot (repeatable)',
+    })
+        .option('native-rg', {
+        type: 'string',
+        description: 'Pre-resolved native ripgrep path to bake into the wrapper',
+    })
+        .option('session-dir', {
+        type: 'string',
+        description: 'Durable mount session directory',
+    })
+        .option('pod-root', {
+        type: 'string',
+        description: 'Pod container root URL (alias of --server for the helper)',
+    })
+        .option('backend', {
+        type: 'string',
+        description: 'Mount backend: nfs (macOS, userspace) or fuse (Linux)',
+    })
+        .option('mountpoint', {
+        type: 'string',
+        description: 'Mountpoint directory (defaults to <session-dir>/mnt)',
+    })
+        .option('json', {
+        type: 'boolean',
+        default: false,
+        description: 'Output JSON envelope',
+    });
+}
+function rootsFromArgs(argv) {
+    if (!argv.root || argv.root.length === 0) {
+        return (0, roots_1.loadManagedRoots)();
+    }
+    const roots = argv.root.map((entry) => {
+        const separator = entry.indexOf('=');
+        if (separator === -1) {
+            throw new Error(`Invalid --root "${entry}"; expected localPath=podRoot`);
+        }
+        return { localPath: entry.slice(0, separator), podRoot: entry.slice(separator + 1) };
+    });
+    const parsed = (0, roots_1.parseManagedRoots)(roots);
+    if (parsed.length !== roots.length) {
+        throw new Error('Each --root must be an absolute local path and an http(s) Pod root URL');
+    }
+    return parsed;
+}
+function requireDir(argv) {
+    if (!argv.dir) {
+        throw new Error('--dir is required for this subcommand');
+    }
+    return node_path_1.default.resolve(argv.dir);
+}
+const installCommand = {
+    command: 'install',
+    describe: 'Write a session-scoped rg wrapper into a directory',
+    builder: (yargs) => agentFsOptions(yargs),
+    handler: async (argv) => {
+        try {
+            const result = (0, install_1.installRgWrapper)({
+                dir: requireDir(argv),
+                roots: rootsFromArgs(argv),
+                sessionDir: argv['session-dir'] ?? (0, session_view_1.defaultSessionDir)(),
+                ...(argv['native-rg'] ? { nativeRg: node_path_1.default.resolve(argv['native-rg']) } : {}),
+            });
+            if (argv.json) {
+                (0, output_1.writeJsonResult)({ ...result, exports: (0, install_1.renderEnvExports)(result) });
+                return;
+            }
+            console.log(`Installed rg wrapper at ${result.wrapperPath}`);
+            console.log(`Native rg: ${result.nativeRg}`);
+            console.log('Add it to this session with:');
+            for (const line of (0, install_1.renderEnvExports)(result)) {
+                console.log(`  ${line}`);
+            }
+        }
+        catch (error) {
+            (0, output_1.handleCliError)(error, Boolean(argv.json));
+        }
+    },
+};
+const envCommand = {
+    command: 'env',
+    describe: 'Print shell exports for an already installed wrapper directory',
+    builder: (yargs) => agentFsOptions(yargs),
+    handler: async (argv) => {
+        try {
+            const dir = requireDir(argv);
+            const nativeRg = argv['native-rg'] ? node_path_1.default.resolve(argv['native-rg']) : (0, native_1.resolveNativeBinary)('rg', process.env, [dir]);
+            if (!nativeRg) {
+                throw new Error('Could not resolve a native rg binary.');
+            }
+            const exports = (0, install_1.renderEnvExports)({
+                dir,
+                wrapperPath: node_path_1.default.join(dir, 'rg'),
+                nativeRg,
+                launcher: [],
+            });
+            if (argv.json) {
+                (0, output_1.writeJsonResult)({ dir, nativeRg, exports });
+                return;
+            }
+            for (const line of exports) {
+                console.log(line);
+            }
+        }
+        catch (error) {
+            (0, output_1.handleCliError)(error, Boolean(argv.json));
+        }
+    },
+};
+const shellCommand = {
+    command: 'shell',
+    describe: 'Open a shell whose PATH uses the managed rg wrapper for this session',
+    builder: (yargs) => agentFsOptions(yargs),
+    handler: async (argv) => {
+        try {
+            const tempDir = argv.dir ? node_path_1.default.resolve(argv.dir) : (0, node_fs_1.mkdtempSync)(node_path_1.default.join((0, node_os_1.tmpdir)(), 'xpod-agent-fs-'));
+            const result = (0, install_1.installRgWrapper)({
+                dir: tempDir,
+                roots: rootsFromArgs(argv),
+                sessionDir: argv['session-dir'] ?? (0, session_view_1.defaultSessionDir)(),
+                ...(argv['native-rg'] ? { nativeRg: node_path_1.default.resolve(argv['native-rg']) } : {}),
+            });
+            const shell = process.env.SHELL || '/bin/sh';
+            const child = (0, node_child_process_1.spawn)(shell, [], {
+                stdio: 'inherit',
+                env: {
+                    ...process.env,
+                    PATH: `${result.dir}${node_path_1.default.delimiter}${process.env.PATH ?? ''}`,
+                    XPOD_AGENT_FS_WRAPPER_DIR: result.dir,
+                    XPOD_AGENT_FS_NATIVE_RG: result.nativeRg,
+                },
+            });
+            const code = await new Promise((resolve) => child.on('close', (value) => resolve(value ?? 0)));
+            if (!argv.dir) {
+                (0, node_fs_1.rmSync)(tempDir, { recursive: true, force: true });
+            }
+            process.exitCode = code;
+        }
+        catch (error) {
+            (0, output_1.handleCliError)(error, Boolean(argv.json));
+        }
+    },
+};
+function resolvePodRoot(argv) {
+    if (argv['pod-root']) {
+        const root = (0, roots_1.normalizePodRoot)(argv['pod-root']);
+        if (!root) {
+            throw new Error('--pod-root must be an http(s) container URL without credentials, query or fragment');
+        }
+        return root;
+    }
+    const roots = rootsFromArgs(argv);
+    if (roots.length === 0) {
+        throw new Error('A --pod-root (or --root localPath=podRoot) is required to mount');
+    }
+    return roots[0].podRoot;
+}
+function resolveBackend(argv) {
+    const value = (argv.backend ?? (0, mount_1.defaultBackend)());
+    if (value !== 'nfs' && value !== 'fuse') {
+        throw new Error(`Unsupported backend "${value}"; expected nfs or fuse`);
+    }
+    return value;
+}
+function readFirstJsonLine(stream) {
+    return new Promise((resolve, reject) => {
+        let buffer = '';
+        const cleanup = () => {
+            clearTimeout(timeout);
+            stream.removeListener('data', onData);
+            stream.removeListener('error', onError);
+            stream.removeListener('close', onEnd);
+            stream.removeListener('end', onEnd);
+        };
+        const onError = (error) => { cleanup(); reject(error); };
+        const onEnd = () => onError(new Error('auth proxy exited before reporting a port'));
+        const timeout = setTimeout(() => onError(new Error('auth proxy startup timed out')), 15_000);
+        const onData = (chunk) => {
+            buffer += chunk.toString();
+            if (buffer.length > 32_768) {
+                onError(new Error('auth proxy startup response exceeded the limit'));
+                return;
+            }
+            const index = buffer.indexOf('\n');
+            if (index !== -1) {
+                cleanup();
+                resolve(buffer.slice(0, index));
+            }
+        };
+        stream.on('data', onData);
+        stream.once('error', onError);
+        stream.once('close', onEnd);
+        stream.once('end', onEnd);
+    });
+}
+/**
+ * Start the loopback auth proxy as a child process. Its stderr is redirected to a
+ * private session log instead of inheriting the caller's stdio: a long-lived
+ * proxy must never retain a caller's capture pipe (which would delay the
+ * caller's stdout/stderr EOF until the proxy is unmounted). The capability is
+ * only ever written to the proxy's stdout startup line, which is read and
+ * discarded by the parent, never logged.
+ */
+function spawnAuthProxyDaemon(podRoot, sessionDir) {
+    (0, node_fs_1.mkdirSync)(sessionDir, { recursive: true });
+    const [cliExecutable, ...cliArgs] = (0, launcher_1.cliLauncher)();
+    const logFd = (0, node_fs_1.openSync)(node_path_1.default.join(sessionDir, 'proxy.log'), 'a', 0o600);
+    try {
+        return (0, node_child_process_1.spawn)(cliExecutable, [...cliArgs, 'agent-fs', 'proxy', '--pod-root', podRoot], {
+            stdio: ['ignore', 'pipe', logFd],
+        });
+    }
+    finally {
+        (0, node_fs_1.closeSync)(logFd);
+    }
+}
+const proxyCommand = {
+    command: 'proxy',
+    describe: 'Run a loopback auth proxy restricted to one Pod (internal mount bridge)',
+    builder: (yargs) => agentFsOptions(yargs),
+    handler: async (argv) => {
+        try {
+            const podRoot = resolvePodRoot(argv);
+            const auth = await (0, auth_context_1.requireAuthContext)();
+            const proxy = await (0, auth_proxy_1.startAuthProxy)({ podRoot, onShutdown: () => void shutdown() });
+            console.log(JSON.stringify({ origin: proxy.origin, podRoot, identity: auth.webId, capability: proxy.capability }));
+            const shutdown = async () => {
+                await proxy.close();
+                process.exit(0);
+            };
+            process.on('SIGTERM', () => void shutdown());
+            process.on('SIGINT', () => void shutdown());
+            await new Promise(() => undefined);
+        }
+        catch (error) {
+            (0, output_1.handleCliError)(error, Boolean(argv.json));
+        }
+    },
+};
+const mountCommand = {
+    command: 'mount',
+    describe: 'Mount the Pod as an AgentFS filesystem (userspace NFS or Linux FUSE)',
+    builder: (yargs) => agentFsOptions(yargs),
+    handler: async (argv) => {
+        let proxy;
+        try {
+            const backend = resolveBackend(argv);
+            const prerequisites = (0, mount_1.describePrerequisites)(package_root_1.PACKAGE_ROOT, process.env, backend);
+            if (prerequisites.blockers.length > 0) {
+                throw new mount_1.MountUnavailableError(prerequisites);
+            }
+            const sessionDir = argv['session-dir'] ? node_path_1.default.resolve(argv['session-dir']) : (0, session_view_1.defaultSessionDir)();
+            const podRoot = resolvePodRoot(argv);
+            const mountpoint = node_path_1.default.resolve(argv.mountpoint ?? node_path_1.default.join(sessionDir, 'mnt'));
+            (0, node_fs_1.mkdirSync)(mountpoint, { recursive: true });
+            (0, node_fs_1.mkdirSync)(sessionDir, { recursive: true });
+            // Start the loopback auth proxy so the Rust helper never owns credentials
+            // and every Pod request flows through the CLI auth lifecycle.
+            proxy = spawnAuthProxyDaemon(podRoot, sessionDir);
+            const line = await readFirstJsonLine(proxy.stdout);
+            const { origin, capability, identity } = JSON.parse(line);
+            const podPath = new URL(podRoot.endsWith('/') ? podRoot : `${podRoot}/`).pathname;
+            const helperServer = `${origin}${podPath}`;
+            const helper = prerequisites.helperPath;
+            const code = await new Promise((resolve, reject) => {
+                const child = (0, node_child_process_1.spawn)(helper, [
+                    'mount',
+                    '--server', helperServer,
+                    '--mountpoint', mountpoint,
+                    '--backend', backend,
+                    '--session-dir', sessionDir,
+                ], { stdio: 'inherit', env: {
+                        ...process.env, XPOD_AGENTFS_CAPABILITY: capability,
+                        XPOD_AGENTFS_POD_ROOT: podRoot, XPOD_AGENTFS_IDENTITY: identity,
+                    } });
+                child.on('error', reject);
+                child.on('close', (value) => resolve(value ?? 1));
+            });
+            if (code !== 0) {
+                proxy.kill('SIGTERM');
+                process.exitCode = code;
+                return;
+            }
+            (0, node_fs_1.writeFileSync)(node_path_1.default.join(sessionDir, 'proxy.json'), JSON.stringify({ origin, capability }), { mode: 0o600 });
+            proxy.stdout?.destroy();
+            proxy.unref();
+            process.exitCode = 0;
+        }
+        catch (error) {
+            if (proxy) {
+                proxy.kill('SIGTERM');
+            }
+            if (error instanceof mount_1.MountUnavailableError) {
+                if (argv.json) {
+                    (0, output_1.writeJsonResult)({ error: true, code: 'mount_unavailable', ...error.prerequisites });
+                }
+                else {
+                    console.error(error.message);
+                    for (const blocker of error.prerequisites.blockers) {
+                        console.error(`  - ${blocker}`);
+                    }
+                }
+                process.exitCode = 3;
+                return;
+            }
+            if (argv.json) {
+                const message = error instanceof Error ? error.message : String(error);
+                (0, output_1.writeJsonResult)({ error: true, code: 'mount_failed', message, blockers: [message] });
+                process.exitCode = 1;
+                return;
+            }
+            (0, output_1.handleCliError)(error, false);
+        }
+    },
+};
+const unmountCommand = {
+    command: 'unmount',
+    describe: 'Unmount the AgentFS Pod filesystem',
+    builder: (yargs) => agentFsOptions(yargs),
+    handler: async (argv) => {
+        const prerequisites = (0, mount_1.describePrerequisites)(package_root_1.PACKAGE_ROOT);
+        const sessionDir = argv['session-dir'] ? node_path_1.default.resolve(argv['session-dir']) : (0, session_view_1.defaultSessionDir)();
+        if (!prerequisites.helperPresent) {
+            if (argv.json) {
+                (0, output_1.writeJsonResult)({ error: true, code: 'mount_unavailable', ...prerequisites });
+            }
+            else {
+                console.error(`AgentFS Pod helper not built; nothing is mounted.`);
+            }
+            process.exitCode = 3;
+            return;
+        }
+        const mountpoint = node_path_1.default.resolve(argv.mountpoint ?? node_path_1.default.join(sessionDir, 'mnt'));
+        const code = await new Promise((resolve, reject) => {
+            const args = ['unmount'];
+            if (mountpoint) {
+                args.push('--mountpoint', mountpoint);
+            }
+            args.push('--session-dir', sessionDir);
+            const child = (0, node_child_process_1.spawn)(prerequisites.helperPath, args, { stdio: 'inherit' });
+            child.on('error', reject);
+            child.on('close', (value) => resolve(value ?? 1));
+        });
+        if (code === 0) {
+            const controlFile = node_path_1.default.join(sessionDir, 'proxy.json');
+            try {
+                const control = JSON.parse((0, node_fs_1.readFileSync)(controlFile, 'utf8'));
+                const origin = new URL(control.origin);
+                if (origin.protocol !== 'http:' || origin.hostname !== '127.0.0.1' || !origin.port ||
+                    origin.href !== `${origin.origin}/` || !/^[a-f0-9]{64}$/.test(control.capability)) {
+                    throw new Error('invalid auth proxy control record');
+                }
+                const response = await fetch(`${origin.origin}/-/agentfs-proxy/shutdown`, {
+                    method: 'POST', headers: { 'x-xpod-agentfs-capability': control.capability },
+                    signal: AbortSignal.timeout(5000),
+                });
+                if (response.status !== 204) {
+                    throw new Error(`auth proxy shutdown returned ${response.status}`);
+                }
+                (0, node_fs_1.rmSync)(controlFile, { force: true });
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT') {
+                    console.error(`Filesystem unmounted; proxy cleanup failed: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+        }
+        process.exitCode = code;
+    },
+};
+const statusCommand = {
+    command: 'status',
+    describe: 'Report AgentFS Pod prototype prerequisites and pending write-back',
+    builder: (yargs) => agentFsOptions(yargs),
+    handler: async (argv) => {
+        try {
+            const prerequisites = (0, mount_1.describePrerequisites)(package_root_1.PACKAGE_ROOT);
+            const sessionDir = argv['session-dir'] ? node_path_1.default.resolve(argv['session-dir']) : (0, session_view_1.defaultSessionDir)();
+            const pendingCount = (0, session_view_1.observeSession)(sessionDir).pending;
+            const payload = { ...prerequisites, pendingOperations: pendingCount, sessionDir, roots: rootsFromArgs(argv) };
+            if (argv.json) {
+                (0, output_1.writeJsonResult)(payload);
+                return;
+            }
+            const payloadPendingCount = pendingCount;
+            console.log(`platform: ${prerequisites.platform}`);
+            console.log(`helper: ${prerequisites.helperPath ?? '(not built)'}`);
+            console.log(`check binary: ${prerequisites.checkBinaryPath ?? '(not built)'}`);
+            console.log(`fuse: ${prerequisites.fuseAvailable ? 'available' : 'unavailable'}`);
+            console.log(`upstream: ${prerequisites.upstream.repository}@${prerequisites.upstream.commit}`);
+            console.log(`pending operations: ${payloadPendingCount}`);
+            for (const blocker of prerequisites.blockers) {
+                console.log(`blocker: ${blocker}`);
+            }
+        }
+        catch (error) {
+            (0, output_1.handleCliError)(error, Boolean(argv.json));
+        }
+    },
+};
+function sessionCommand(action) {
+    return {
+        command: action,
+        describe: action === 'commit' ? 'Write back the native session overlay to the Pod over authenticated HTTP' :
+            'Reconcile ambiguous requests by reading the Pod; preserve changed remote versions',
+        builder: (yargs) => agentFsOptions(yargs),
+        handler: async (argv) => {
+            let proxy;
+            try {
+                const podRoot = resolvePodRoot(argv);
+                const sessionDir = argv['session-dir'] ? node_path_1.default.resolve(argv['session-dir']) : (0, session_view_1.defaultSessionDir)();
+                const prerequisites = (0, mount_1.describePrerequisites)(package_root_1.PACKAGE_ROOT, process.env, resolveBackend(argv));
+                if (!prerequisites.helperPresent) {
+                    throw new Error(`AgentFS Pod helper not built; cannot ${action}`);
+                }
+                proxy = spawnAuthProxyDaemon(podRoot, sessionDir);
+                const line = await readFirstJsonLine(proxy.stdout);
+                const { origin, capability, identity } = JSON.parse(line);
+                const podPath = new URL(podRoot.endsWith('/') ? podRoot : `${podRoot}/`).pathname;
+                const code = await new Promise((resolve, reject) => {
+                    const child = (0, node_child_process_1.spawn)(prerequisites.helperPath, [
+                        action, '--pod-root', `${origin}${podPath}`, '--session-dir', sessionDir,
+                        ...(action === 'recover' && argv.json ? ['--json'] : []),
+                    ], { stdio: 'inherit', env: {
+                            ...process.env, XPOD_AGENTFS_CAPABILITY: capability,
+                            XPOD_AGENTFS_POD_ROOT: podRoot, XPOD_AGENTFS_IDENTITY: identity,
+                        } });
+                    child.on('error', reject);
+                    child.on('close', (value) => resolve(value ?? 1));
+                });
+                proxy.kill('SIGTERM');
+                process.exitCode = code;
+            }
+            catch (error) {
+                if (proxy) {
+                    proxy.kill('SIGTERM');
+                }
+                (0, output_1.handleCliError)(error, Boolean(argv.json));
+            }
+        },
+    };
+}
+const commitCommand = sessionCommand('commit');
+const recoverCommand = sessionCommand('recover');
+exports.agentFsCommand = {
+    command: 'agent-fs',
+    describe: 'Agent directory HTTP backend wrappers (rg) and AgentFS Pod mount prototype',
+    builder: (yargs) => yargs
+        .command(installCommand)
+        .command(envCommand)
+        .command(shellCommand)
+        .command(proxyCommand)
+        .command(mountCommand)
+        .command(unmountCommand)
+        .command(statusCommand)
+        .command(commitCommand)
+        .command(recoverCommand)
+        .demandCommand(1, 'Please specify an agent-fs subcommand')
+        .help(),
+    handler: () => undefined,
+};
+//# sourceMappingURL=agent-fs.js.map

package/dist/cli/commands/start.d.ts

@@ -13,26 +13,19 @@ export declare const startCommand: CommandModule<object, StartArgs>;
 /**
  * Where remote-forwarded traffic lands on this machine.
  *
- * Order: explicit `XPOD_GATEWAY_INGRESS_PORT` → the active SakuraFrp tunnel's assigned local
- * port → an OS-assigned loopback port. The first two are strict, because a tunnel that
- * forwards to a specific port cannot follow us somewhere else.
+ * The decision (explicit pin → the active profile's console declaration → the gateway-derived
+ * entry) lives in `src/runtime/ingress-port.ts`, together with the strict "taken means taken"
+ * check and the occupant naming. This only reports the outcome, so the startup banner says
+ * whether the entry was pinned, adopted from a console, or derived from the gateway port.
  */
-/**
- * The port a remote tunnel forwards to: the Gateway's tunnel entry.
- *
- * It is derived from the Gateway port by the same rule the runtime uses, so the CLI can hand
- * it to the managed edge agent before the runtime binds it. A console that forwards somewhere
- * else is a mismatch the tunnel provider reports from its own read-back - the runtime never
- * moves its gate to match a console.
- */
-export declare function resolveIngressPort(provisionedConfig: {
-    tunnelProfiles?: Array<{
-        id: string;
+export declare function describeIngressDecision(ingress: {
+    port: number;
+    source: string;
+    declared?: {
         provider: string;
-        credentialEnvKey?: string;
-    }>;
-    tunnelActiveProfileId?: string;
-}, mainPort: number): Promise<number>;
+        readBack: string;
+    };
+}): string;
 export declare function resolveCliOidcIssuer(env: Record<string, string | undefined>, provisionedIssuer?: string, edition?: string): string | undefined;
 export declare function resolveManagedEdgeAgentConfig(config: Pick<ReturnType<typeof loadConfigFromEnv>, 'cloudApiEndpoint' | 'nodeId' | 'nodeToken'>, gatewayPort: number, ingressPort?: number, runtimeEnv?: Record<string, string | undefined>): {
     signalEndpoint: string;

package/dist/cli/commands/start.js

@@ -4,7 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.startCommand = void 0;
-exports.resolveIngressPort = resolveIngressPort;
+exports.describeIngressDecision = describeIngressDecision;
 exports.resolveCliOidcIssuer = resolveCliOidcIssuer;
 exports.resolveManagedEdgeAgentConfig = resolveManagedEdgeAgentConfig;
 exports.resolveChildDatabaseUrl = resolveChildDatabaseUrl;
@@ -16,7 +16,7 @@ const fs_1 = __importDefault(require("fs"));
 const global_logger_factory_1 = require("global-logger-factory");
 const supervisor_1 = require("../../supervisor");
 const runtime_1 = require("../../runtime");
-const SakuraFrpTunnelProvider_1 = require("../../tunnel/SakuraFrpTunnelProvider");
+const ingress_port_1 = require("../../runtime/ingress-port");
 const css_process_1 = require("../../runtime/css-process");
 const oidc_issuer_1 = require("../../runtime/oidc-issuer");
 const AuthMode_1 = require("../../authorization/AuthMode");
@@ -107,17 +107,30 @@ exports.startCommand = {
         const cssPort = await (0, runtime_1.getFreePortForWildcard)(requestedCssPort);
         const requestedApiPort = resolveServicePort(process.env.API_PORT, cssPort + 1, new Set([mainPort, cssPort]));
         const apiPort = await (0, runtime_1.getFreePortForWildcard)(requestedApiPort);
-        // Remote forwarding (managed tunnels, P2P data plane) terminates on this machine, so
-        // its origin is a dedicated ingress port instead of the gateway port: the Gateway
-        // never treats requests accepted there as local. An explicit override is honoured;
-        // otherwise the OS assigns a loopback port, because neighbouring ports may already
-        // belong to another service this deployment planned.
-        // The port is a fact of whichever tunnel forwards to us: an explicit override pins it,
-        // and the SakuraFrp console's own 本地端口 is read back from the provider, so the
-        // operator never types the same number twice. Only an unmanaged ingress is ephemeral.
-        // A pinned port is taken as-is: silently moving it would leave the tunnel pointing at a
-        // port nobody listens on.
-        const ingressPort = await resolveIngressPort(provisionedConfig, mainPort);
+        // Remote forwarding (managed tunnels, P2P data plane) terminates on this machine, so its
+        // origin is a dedicated ingress port instead of the gateway port: the Gateway never treats
+        // requests accepted there as local.
+        //
+        // Order (see `resolveIngressPort`): an explicit `XPOD_GATEWAY_INGRESS_PORT` wins; otherwise
+        // the *active* profile's provider console decides — for a console-owned tunnel the runtime
+        // adopts the port that console already declares (SakuraFrp's `local_port`, the Cloudflare
+        // dashboard's remote configuration read back through the connector) instead of asking the
+        // operator to edit the console; only an entry nobody declares is derived from the gateway
+        // port (gateway+3..+9).
+        //
+        // Both strict sources are strict: a port that somebody else holds fails the start with the
+        // occupant named (pid, command line, cwd), and nothing is ever signalled or silently moved
+        // to another port - the tunnel forwards to a number, so it must find this runtime there.
+        const ingress = await (0, ingress_port_1.resolveIngressPort)({
+            mainPort,
+            env: process.env,
+            profiles: provisionedConfig.tunnelProfiles ?? [],
+            ...(provisionedConfig.tunnelActiveProfileId
+                ? { activeProfileId: provisionedConfig.tunnelActiveProfileId }
+                : {}),
+            reservedPorts: [mainPort, cssPort, apiPort],
+        });
+        const ingressPort = ingress.port;
         // Published so the API can tell the operator which address a tunnel must forward to.
         process.env.XPOD_GATEWAY_INGRESS_PORT = String(ingressPort);
         const runtimeRoot = path_1.default.join(process.cwd(), '.xpod/runtime/legacy-css');
@@ -143,6 +156,7 @@ exports.startCommand = {
         console.log(`  Gateway: ${baseUrl} (${argv.host}:${mainPort})`);
         console.log(`  CSS (internal): http://localhost:${cssPort}`);
         console.log(`  API (internal): http://localhost:${apiPort}`);
+        console.log(`  Tunnel entry: http://127.0.0.1:${ingressPort} — ${describeIngressDecision(ingress)}`);
         if (externalOidcIssuer) {
             console.log(`  SP mode: Cloud IdP = ${externalOidcIssuer}`);
         }
@@ -235,32 +249,19 @@ exports.startCommand = {
 /**
  * Where remote-forwarded traffic lands on this machine.
  *
- * Order: explicit `XPOD_GATEWAY_INGRESS_PORT` → the active SakuraFrp tunnel's assigned local
- * port → an OS-assigned loopback port. The first two are strict, because a tunnel that
- * forwards to a specific port cannot follow us somewhere else.
+ * The decision (explicit pin → the active profile's console declaration → the gateway-derived
+ * entry) lives in `src/runtime/ingress-port.ts`, together with the strict "taken means taken"
+ * check and the occupant naming. This only reports the outcome, so the startup banner says
+ * whether the entry was pinned, adopted from a console, or derived from the gateway port.
  */
-/**
- * The port a remote tunnel forwards to: the Gateway's tunnel entry.
- *
- * It is derived from the Gateway port by the same rule the runtime uses, so the CLI can hand
- * it to the managed edge agent before the runtime binds it. A console that forwards somewhere
- * else is a mismatch the tunnel provider reports from its own read-back - the runtime never
- * moves its gate to match a console.
- */
-async function resolveIngressPort(provisionedConfig, mainPort) {
-    const port = await (0, runtime_1.findGatewayIngressPort)(mainPort);
-    const active = provisionedConfig.tunnelProfiles?.find((profile) => profile.id === provisionedConfig.tunnelActiveProfileId) ?? provisionedConfig.tunnelProfiles?.find((profile) => profile.provider === 'sakura_frp');
-    if (active?.provider === 'sakura_frp') {
-        const credential = active.credentialEnvKey
-            ? process.env[active.credentialEnvKey] ?? process.env.SAKURA_TUNNEL_TOKEN
-            : process.env.SAKURA_TUNNEL_TOKEN;
-        const assigned = await (0, SakuraFrpTunnelProvider_1.resolveSakuraAssignedLocalPort)(credential);
-        if (assigned !== undefined && assigned !== port) {
-            (0, global_logger_factory_1.getLoggerFor)('XpodStart').warn(`The Sakura console forwards to local port ${assigned}, but this runtime's tunnel entry is ${port}; `
-                + `update the tunnel's local port in the console to ${port}`);
-        }
+function describeIngressDecision(ingress) {
+    if (ingress.source === 'explicit') {
+        return `pinned by XPOD_GATEWAY_INGRESS_PORT`;
+    }
+    if (ingress.source === 'console-declared' && ingress.declared) {
+        return `adopted from the ${ingress.declared.provider} console (${ingress.declared.readBack})`;
     }
-    return port;
+    return 'derived from the gateway port (gateway+3..+9)';
 }
 function resolveCliOidcIssuer(env, provisionedIssuer, edition) {
     const explicit = (0, oidc_issuer_1.resolveExternalOidcIssuer)(env);

package/dist/cli/commands/stop.js

@@ -39,11 +39,17 @@ exports.stopCommand = {
         }
         try {
             const res = await fetch(`${baseUrl}/service/status`);
-            if (!res.ok) {
+            // 503 means the gateway is reachable but degraded (a supervised child is down or gave up).
+            // Stopping a half-dead instance must stay possible, so only other failures are fatal.
+            const degraded = res.status === 503;
+            if (!res.ok && !degraded) {
                 throw new output_1.CliCommandError('server_not_reachable', 'Service not reachable or already stopped.', 1, {
                     status: res.status,
                 });
             }
+            if (degraded && !argv.json) {
+                console.log('Instance is degraded (a supervised service is not running); stopping it anyway.');
+            }
             const statuses = (await res.json());
             const running = statuses.filter((s) => s.status === 'running');
             if (running.length === 0) {