@cjhyy/code-shell-server 0.9.48 → 0.9.50

package/dist/mobile-remote/remote-host-manager.d.ts

@@ -21,7 +21,8 @@ export interface RemoteHostStartOptions {
     /**
      * "lan" (default) keeps the existing LAN behaviour unchanged. "tunnel" binds
      * 127.0.0.1 (cloudflared connects to loopback) and inserts a passcode gate in
-     * front of every HTTP route and the WS upgrade. "relay" also requires an
+     * front of ordinary HTTP routes and the WS upgrade. Host-verified Panel asset
+     * capabilities use their own short-lived authorization. "relay" also requires an
      * initialized passcode and a stable HTTPS origin before pairing/WS upgrades.
      */
     mode?: "lan" | "tunnel" | "relay";
@@ -39,6 +40,10 @@ export interface RemoteHostManagerOptions {
     outputJournal?: boolean;
     /** Enable only when the attached selected-session host implements legacy base pages. */
     legacyBasePages?: boolean;
+    /** Enable only when the selected-session reader supports opt-in dense pages. */
+    outputJournalPageFrames?: 2048;
+    /** Selected-session Host implements verified display views and bounded detail parts. */
+    historyView?: boolean;
     onClientEvent: (event: unknown, ws: WebSocket) => void | Promise<void>;
     /**
      * Absolute path to the built mobile app (out/mobile). Defaults to the
@@ -76,6 +81,8 @@ export declare class RemoteHostManager extends EventEmitter {
     private publicBaseUrl?;
     /** Passcode gate, present only in tunnel mode. */
     private passcode?;
+    private socketAccessValidity;
+    private accessSweep?;
     /** Where the built mobile app lives (out/mobile). */
     private readonly mobileRootDir;
     /** Dev proxy target for /mobile (HMR); undefined in prod. */
@@ -122,6 +129,8 @@ export declare class RemoteHostManager extends EventEmitter {
     /** Reply only to the currently authenticated tab; retired/revoked viewers receive nothing. */
     hasAuthenticatedViewer(viewerId: string, deviceId: string): boolean;
     sendToViewer(viewerId: string, event: MobileServerEvent): void;
+    /** Preserve the full worker envelope while retaining exact authenticated-tab routing. */
+    sendRawToViewer(viewerId: string, payload: string): void;
     /** Send a raw JSON-RPC worker line to ONLY one authenticated device. */
     sendRawToDevice(deviceId: string, payload: string): void;
     /** Broadcast a raw line (e.g. a mirrored worker→renderer JSON-RPC line) to
@@ -136,6 +145,7 @@ export declare class RemoteHostManager extends EventEmitter {
      * socket is still delivered. Returns false when retired.
      */
     private sendBounded;
+    private hasSocketAccess;
     private releaseSocket;
     private bindSocketDevice;
     /** Call after revoking/removing a trusted device to release both transports immediately. */

package/dist/mobile-remote/remote-host-manager.js

@@ -10,6 +10,16 @@ import { parseMobileClientEvent } from "./mobile-client-event-validator.js";
 import { isRelayOrigin } from "../remote-relay/protocol.js";
 /** Outbound bytes one paired socket may leave unread before it is retired. */
 const MAX_SOCKET_BACKLOG_BYTES = 4 * 1024 * 1024;
+/** The query suffix ("" or "?…") when the raw request target is exactly the
+ *  root entry, else undefined. The redirect path is fixed, so only the query
+ *  is carried over and it can never form an off-site Location. */
+function rootEntryQuery(target) {
+    if (target === "/")
+        return "";
+    if (target?.startsWith("/?"))
+        return target.slice(1);
+    return undefined;
+}
 /**
  * Pick the Mac's real LAN IPv4 so a phone on the same Wi-Fi can reach the
  * remote host. We bind to a concrete LAN address (NOT 0.0.0.0) per the design's
@@ -57,6 +67,8 @@ export class RemoteHostManager extends EventEmitter {
     publicBaseUrl;
     /** Passcode gate, present only in tunnel mode. */
     passcode;
+    socketAccessValidity = new WeakMap();
+    accessSweep;
     /** Where the built mobile app lives (out/mobile). */
     mobileRootDir;
     /** Dev proxy target for /mobile (HMR); undefined in prod. */
@@ -117,8 +129,8 @@ export class RemoteHostManager extends EventEmitter {
     async startOnce(options) {
         const relay = options.mode === "relay";
         const publicAccess = relay || options.mode === "tunnel";
-        if (relay && !options.passcode?.isSet()) {
-            throw new Error("Relay mode requires an initialized access passcode");
+        if (publicAccess && !options.passcode?.isSet()) {
+            throw new Error(`${relay ? "Relay" : "Tunnel"} mode requires an initialized access passcode`);
         }
         if (relay)
             this.publicBaseUrl = undefined;
@@ -136,60 +148,88 @@ export class RemoteHostManager extends EventEmitter {
                 req.resume();
                 return;
             }
-            // Tunnel mode: a passcode gate sits in front of EVERY route. The gate
-            // either allows (returns true) or writes its own 401/403 challenge.
-            if (gate && !gate.gate(req, res))
-                return;
-            if (req.url === "/health") {
-                res.writeHead(200, { "content-type": "application/json" });
-                res.end(JSON.stringify({ ok: true }));
-                return;
-            }
-            if (req.url?.startsWith("/api/v1/") && this.opts.webApi) {
-                const baseUrl = this.publicBaseUrl ?? this.started?.url;
-                if (!baseUrl) {
-                    res.writeHead(503);
-                    res.end("remote host is starting");
+            const serve = () => {
+                // All ordinary routes retain the tunnel passcode gate. Only a Host-verified
+                // short-lived Panel asset capability may use independent authorization.
+                if (gate && !gate.gate(req, res))
+                    return;
+                if (req.url === "/health") {
+                    res.writeHead(200, { "content-type": "application/json" });
+                    res.end(JSON.stringify({ ok: true }));
                     return;
                 }
-                void this.opts.webApi
-                    .handle(req, res, { baseUrl })
-                    .then((handled) => {
-                    if (!handled && !res.writableEnded) {
-                        res.writeHead(404);
-                        res.end("not found");
+                if (req.url?.startsWith("/api/v1/") && this.opts.webApi) {
+                    const baseUrl = this.publicBaseUrl ?? this.started?.url;
+                    if (!baseUrl) {
+                        res.writeHead(503);
+                        res.end("remote host is starting");
+                        return;
                     }
-                })
-                    .catch(() => {
+                    void this.opts.webApi
+                        .handle(req, res, { baseUrl, isAccessAuthorized: gate?.captureValidity() })
+                        .then((handled) => {
+                        if (!handled && !res.writableEnded) {
+                            res.writeHead(404);
+                            res.end("not found");
+                        }
+                    })
+                        .catch(() => {
+                        if (!res.headersSent)
+                            res.writeHead(500);
+                        if (!res.writableEnded)
+                            res.end("remote request failed");
+                    });
+                    return;
+                }
+                const uploadPath = pathname.match(/^\/api\/mobile\/uploads\/([A-Za-z0-9_-]+)$/);
+                if (uploadPath && this.opts.uploads) {
+                    void this.opts.uploads.acceptPut(uploadPath[1], req, res);
+                    return;
+                }
+                // The mobile app is built/served with vite base "/mobile/", so ALL of its
+                // assets — and in dev, vite's HMR/module URLs — live under the /mobile
+                // prefix. A single prefix route serves prod (static out/mobile) and dev
+                // (proxy to the mobile vite server) symmetrically. Tunnel mode never
+                // proxies dev: Vite's HMR socket and @fs module URLs don't survive a
+                // public trycloudflare hop, so a public tunnel always serves the build.
+                // Match the route family exactly ("/mobile", "/mobile/…", "/mobile?…",
+                // "/mobile#…") — NOT a sibling like "/mobilexyz", which falls to 404.
+                if (req.url && /^\/mobile(?:[/?#]|$)/.test(req.url)) {
+                    serveMobile(req, res, {
+                        rootDir: this.mobileRootDir,
+                        devUrl: publicAccess ? undefined : this.mobileDevUrl,
+                    });
+                    return;
+                }
+                // The bare origin is what people type or share; send it to the app with
+                // the query (e.g. ?pairing=) intact. Match the raw target, not the
+                // parsed pathname: "//other.host/" parses to "/" but must stay a 404.
+                const rootQuery = rootEntryQuery(req.url);
+                if (rootQuery !== undefined && (req.method === "GET" || req.method === "HEAD")) {
+                    res.writeHead(302, { location: `/mobile/${rootQuery}`, "cache-control": "no-store" });
+                    res.end();
+                    return;
+                }
+                res.writeHead(404);
+                res.end("not found");
+            };
+            const webApi = this.opts.webApi;
+            if (gate?.isSet() &&
+                ["GET", "HEAD"].includes(req.method ?? "") &&
+                pathname.startsWith("/api/v1/panel-assets/") &&
+                webApi?.handleCapabilityAsset) {
+                void webApi.handleCapabilityAsset(req, res).then((handled) => {
+                    if (!handled && !res.writableEnded)
+                        serve();
+                }, () => {
                     if (!res.headersSent)
                         res.writeHead(500);
                     if (!res.writableEnded)
-                        res.end("remote request failed");
-                });
-                return;
-            }
-            const uploadPath = pathname.match(/^\/api\/mobile\/uploads\/([A-Za-z0-9_-]+)$/);
-            if (uploadPath && this.opts.uploads) {
-                void this.opts.uploads.acceptPut(uploadPath[1], req, res);
-                return;
-            }
-            // The mobile app is built/served with vite base "/mobile/", so ALL of its
-            // assets — and in dev, vite's HMR/module URLs — live under the /mobile
-            // prefix. A single prefix route serves prod (static out/mobile) and dev
-            // (proxy to the mobile vite server) symmetrically. Tunnel mode never
-            // proxies dev: Vite's HMR socket and @fs module URLs don't survive a
-            // public trycloudflare hop, so a public tunnel always serves the build.
-            // Match the route family exactly ("/mobile", "/mobile/…", "/mobile?…",
-            // "/mobile#…") — NOT a sibling like "/mobilexyz", which falls to 404.
-            if (req.url && /^\/mobile(?:[/?#]|$)/.test(req.url)) {
-                serveMobile(req, res, {
-                    rootDir: this.mobileRootDir,
-                    devUrl: publicAccess ? undefined : this.mobileDevUrl,
+                        res.end("remote asset request failed");
                 });
                 return;
             }
-            res.writeHead(404);
-            res.end("not found");
+            serve();
         });
         // In tunnel mode we must gate the WS handshake too. `noServer` lets us run
         // the passcode check during the HTTP `upgrade` event before completing the
@@ -225,7 +265,9 @@ export class RemoteHostManager extends EventEmitter {
                     socket.destroy();
                     return;
                 }
+                const isAccessAuthorized = gate.captureValidity();
                 this.wss.handleUpgrade(req, socket, head, (ws) => {
+                    this.socketAccessValidity.set(ws, isAccessAuthorized);
                     this.wss.emit("connection", ws, req);
                 });
             });
@@ -241,17 +283,19 @@ export class RemoteHostManager extends EventEmitter {
                 this.emit("host-error", error);
             });
             ws.on("message", (raw) => {
+                if (!this.hasSocketAccess(ws))
+                    return;
                 let parsed;
                 try {
                     parsed = JSON.parse(String(raw));
                 }
                 catch {
-                    ws.send(JSON.stringify({ type: "error", message: "Invalid JSON" }));
+                    this.sendBounded(ws, JSON.stringify({ type: "error", message: "Invalid JSON" }));
                     return;
                 }
                 const event = parseMobileClientEvent(parsed);
                 if (!event) {
-                    ws.send(JSON.stringify({ type: "error", message: "Invalid client event" }));
+                    this.sendBounded(ws, JSON.stringify({ type: "error", message: "Invalid client event" }));
                     return;
                 }
                 // Pairing/auth are handled inline and bind device identity to this
@@ -262,7 +306,7 @@ export class RemoteHostManager extends EventEmitter {
                     reply = this.handleClientEvent(event);
                 }
                 catch {
-                    ws.send(JSON.stringify({ type: "error", message: "Client event failed" }));
+                    this.sendBounded(ws, JSON.stringify({ type: "error", message: "Client event failed" }));
                     return;
                 }
                 if (event.type === "auth.device" && reply?.type === "auth.ok") {
@@ -273,11 +317,11 @@ export class RemoteHostManager extends EventEmitter {
                     this.bindSocketDevice(ws, reply.device.id);
                 }
                 if (reply) {
-                    ws.send(JSON.stringify(reply));
+                    this.sendBounded(ws, JSON.stringify(reply));
                     return;
                 }
                 if (!this.authed.has(ws)) {
-                    ws.send(JSON.stringify({ type: "auth.failed", message: "Not authenticated" }));
+                    this.sendBounded(ws, JSON.stringify({ type: "auth.failed", message: "Not authenticated" }));
                     return;
                 }
                 // Authenticated, non-auth event → hand to the main dispatcher, which
@@ -286,12 +330,12 @@ export class RemoteHostManager extends EventEmitter {
                     const dispatched = this.opts.onClientEvent({ ...event, deviceId: this.authed.get(ws), viewerId: this.viewers.get(ws) }, ws);
                     void Promise.resolve(dispatched).catch(() => {
                         if (ws.readyState === ws.OPEN) {
-                            ws.send(JSON.stringify({ type: "error", message: "Client event failed" }));
+                            this.sendBounded(ws, JSON.stringify({ type: "error", message: "Client event failed" }));
                         }
                     });
                 }
                 catch {
-                    ws.send(JSON.stringify({ type: "error", message: "Client event failed" }));
+                    this.sendBounded(ws, JSON.stringify({ type: "error", message: "Client event failed" }));
                 }
             });
             ws.on("close", () => {
@@ -346,6 +390,17 @@ export class RemoteHostManager extends EventEmitter {
             url: `http://${bindHost}:${port}`,
             mode: options.mode ?? "lan",
         };
+        if (gate) {
+            const sockets = this.wss;
+            // Idle public tabs must also relinquish viewer-owned state after rotation.
+            // Traffic is checked synchronously in both directions, without rehashing
+            // any plaintext or spending the passcode attempt budget.
+            this.accessSweep = setInterval(() => {
+                for (const client of sockets?.clients ?? [])
+                    this.hasSocketAccess(client);
+            }, 1000);
+            this.accessSweep.unref();
+        }
         return this.started;
     }
     /**
@@ -423,7 +478,11 @@ export class RemoteHostManager extends EventEmitter {
                     ? {
                         capabilities: {
                             outputJournal: 1,
+                            ...(this.opts.historyView ? { historyView: 1 } : {}),
                             ...(this.opts.legacyBasePages ? { legacyBasePages: 1 } : {}),
+                            ...(this.opts.outputJournalPageFrames === 2048
+                                ? { outputJournalPageFrames: 2048 }
+                                : {}),
                         },
                     }
                     : {}),
@@ -446,7 +505,11 @@ export class RemoteHostManager extends EventEmitter {
                     ? {
                         capabilities: {
                             outputJournal: 1,
+                            ...(this.opts.historyView ? { historyView: 1 } : {}),
                             ...(this.opts.legacyBasePages ? { legacyBasePages: 1 } : {}),
+                            ...(this.opts.outputJournalPageFrames === 2048
+                                ? { outputJournalPageFrames: 2048 }
+                                : {}),
                         },
                     }
                     : {}),
@@ -473,7 +536,7 @@ export class RemoteHostManager extends EventEmitter {
     /** Reply only to the currently authenticated tab; retired/revoked viewers receive nothing. */
     hasAuthenticatedViewer(viewerId, deviceId) {
         for (const client of this.wss?.clients ?? []) {
-            if (client.readyState === client.OPEN &&
+            if (this.hasSocketAccess(client) &&
                 this.authed.get(client) === deviceId &&
                 this.viewers.get(client) === viewerId)
                 return true;
@@ -481,7 +544,10 @@ export class RemoteHostManager extends EventEmitter {
         return false;
     }
     sendToViewer(viewerId, event) {
-        const payload = JSON.stringify(event);
+        this.sendRawToViewer(viewerId, JSON.stringify(event));
+    }
+    /** Preserve the full worker envelope while retaining exact authenticated-tab routing. */
+    sendRawToViewer(viewerId, payload) {
         for (const client of this.wss?.clients ?? []) {
             if (client.readyState === client.OPEN &&
                 this.authed.has(client) &&
@@ -519,6 +585,8 @@ export class RemoteHostManager extends EventEmitter {
      * socket is still delivered. Returns false when retired.
      */
     sendBounded(client, payload) {
+        if (!this.hasSocketAccess(client))
+            return false;
         if (client.bufferedAmount > 0 &&
             client.bufferedAmount + Buffer.byteLength(payload) > MAX_SOCKET_BACKLOG_BYTES) {
             this.releaseSocket(client);
@@ -528,6 +596,20 @@ export class RemoteHostManager extends EventEmitter {
         client.send(payload);
         return true;
     }
+    hasSocketAccess(client) {
+        if (client.readyState !== client.OPEN)
+            return false;
+        if (this.socketAccessValidity.get(client)?.() !== false)
+            return true;
+        this.releaseSocket(client);
+        // Distinct from paired-device rejection (4401/4403): the browser keeps its
+        // identity and offers a fresh HTTP challenge instead of silently retrying.
+        client.close(4407, "Access passcode changed");
+        const deadline = setTimeout(() => client.terminate(), 1000);
+        deadline.unref();
+        client.once("close", () => clearTimeout(deadline));
+        return false;
+    }
     releaseSocket(ws) {
         const deviceId = this.authed.get(ws);
         const viewerId = this.viewers.get(ws);
@@ -584,6 +666,8 @@ export class RemoteHostManager extends EventEmitter {
     async stopOnce() {
         if (this.starting)
             await this.starting.catch(() => undefined);
+        clearInterval(this.accessSweep);
+        this.accessSweep = undefined;
         this.relayLifetime?.abort();
         this.relayLifetime = undefined;
         const server = this.server;

package/dist/mobile-remote/tunnel-manager.d.ts

@@ -51,6 +51,7 @@ export declare class TunnelManager extends EventEmitter {
     private readonly killGraceMs;
     private readonly killHardTimeoutMs;
     private child?;
+    private cancelPendingStart?;
     /** In-flight teardown of a previous child. Any start() awaits this first so a
      *  new cloudflared never spawns while the old one still owns the metrics port. */
     private pendingTeardown?;

package/dist/mobile-remote/tunnel-manager.js

@@ -49,6 +49,7 @@ export class TunnelManager extends EventEmitter {
     killGraceMs;
     killHardTimeoutMs;
     child;
+    cancelPendingStart;
     /** In-flight teardown of a previous child. Any start() awaits this first so a
      *  new cloudflared never spawns while the old one still owns the metrics port. */
     pendingTeardown;
@@ -102,7 +103,7 @@ export class TunnelManager extends EventEmitter {
             // Force http2 (TCP). cloudflared defaults to QUIC (UDP/7844), which is
             // blocked on many networks (corp Wi-Fi, some carriers) — the connection
             // object registers but never becomes ready, so the phone hits Cloudflare
-            // error 1033. http2 falls back to TCP/443 and reliably connects.
+            // error 1033. HTTP/2 still requires outbound TCP/7844 to the edge.
             "--protocol",
             "http2",
             // Fixed local metrics endpoint so we can poll /ready for edge readiness.
@@ -114,37 +115,55 @@ export class TunnelManager extends EventEmitter {
         this.child = child;
         return new Promise((resolve, reject) => {
             let settled = false;
-            const finishReject = (err) => {
+            const settle = () => {
                 if (settled)
-                    return;
+                    return false;
                 settled = true;
                 clearTimeout(timer);
+                if (this.cancelPendingStart === cancelStart)
+                    this.cancelPendingStart = undefined;
+                return true;
+            };
+            const cancelStart = () => {
+                if (settle())
+                    reject(new Error("隧道启动已取消。"));
+            };
+            const finishReject = (err) => {
+                if (!settle())
+                    return;
                 // Route through the shared teardown so a retried start() awaits this
                 // child's real exit (releasing the metrics port) before re-spawning.
-                void this.beginTeardown();
+                if (this.child === child)
+                    void this.beginTeardown();
                 reject(err);
             };
             const timer = setTimeout(() => {
                 finishReject(new Error("隧道启动失败:15s 内未取得公网地址(超时)"));
             }, this.timeoutMs);
-            const scan = (buf) => {
+            this.cancelPendingStart = cancelStart;
+            const scanTails = { stdout: "", stderr: "" };
+            const scan = (stream, buf) => {
                 if (settled)
                     return;
-                const match = TRYCLOUDFLARE_RE.exec(String(buf));
-                if (!match)
+                const text = scanTails[stream] + String(buf);
+                const match = TRYCLOUDFLARE_RE.exec(text);
+                if (!match) {
+                    // A pipe chunk can end anywhere in the URL. Keep a bounded suffix
+                    // per stream so stdout and stderr cannot combine into a false URL.
+                    scanTails[stream] = text.slice(-256);
                     return;
+                }
                 // URL captured, but the edge connection is NOT necessarily ready yet —
                 // resolving here was the 1033 bug (handing back a dead QR). Stop the
                 // URL scanners and wait for /ready before declaring connected.
-                child.stdout?.off("data", scan);
-                child.stderr?.off("data", scan);
+                child.stdout?.off("data", scanStdout);
+                child.stderr?.off("data", scanStderr);
                 clearTimeout(timer);
                 const url = match[0];
-                this.waitForReady()
+                this.waitForReady(child)
                     .then(() => {
-                    if (settled)
+                    if (this.child !== child || !settle())
                         return;
-                    settled = true;
                     this.connected = true;
                     this.currentUrl = url;
                     this.emit("status", "connected", url);
@@ -153,8 +172,10 @@ export class TunnelManager extends EventEmitter {
                 })
                     .catch((err) => finishReject(err));
             };
-            child.stdout?.on("data", scan);
-            child.stderr?.on("data", scan);
+            const scanStdout = (buf) => scan("stdout", buf);
+            const scanStderr = (buf) => scan("stderr", buf);
+            child.stdout?.on("data", scanStdout);
+            child.stderr?.on("data", scanStderr);
             child.on("error", (err) => {
                 // A superseded child (torn down by a restart / stop-during-start) must
                 // NOT touch shared state — killAndWait owns its lifecycle. Match the exit
@@ -163,8 +184,7 @@ export class TunnelManager extends EventEmitter {
                 if (this.child !== child)
                     return;
                 if (!settled) {
-                    settled = true;
-                    clearTimeout(timer);
+                    settle();
                     this.child = undefined;
                     this.connected = false;
                     this.currentUrl = undefined;
@@ -193,8 +213,7 @@ export class TunnelManager extends EventEmitter {
                     this.emit("status", "disconnected", { code, signal });
                 }
                 else if (!settled) {
-                    settled = true;
-                    clearTimeout(timer);
+                    settle();
                     reject(new Error(`cloudflared 退出(code=${code ?? "?"} signal=${signal ?? "?"})`));
                 }
             });
@@ -205,10 +224,15 @@ export class TunnelManager extends EventEmitter {
      * `readyTimeoutMs`. This is what distinguishes a working tunnel from one that
      * registered a connection but can't actually serve traffic (error 1033).
      */
-    async waitForReady() {
+    async waitForReady(child) {
         const deadline = Date.now() + this.readyTimeoutMs;
         for (;;) {
-            if (this.child && (await this.checkReady(this.metricsPort)))
+            if (this.child !== child || this.stopping)
+                throw new Error("隧道启动已取消。");
+            const ready = await this.checkReady(this.metricsPort);
+            if (this.child !== child || this.stopping)
+                throw new Error("隧道启动已取消。");
+            if (ready)
                 return;
             if (Date.now() >= deadline) {
                 throw new Error("隧道注册失败:公网边缘连接未就绪(可能网络限制,扫码会报 1033)");
@@ -285,6 +309,7 @@ export class TunnelManager extends EventEmitter {
      */
     beginTeardown() {
         this.stopping = true;
+        this.cancelPendingStart?.();
         this.connected = false;
         this.currentUrl = undefined;
         this.stopHealthMonitor();

package/dist/panels/background-service-process.d.ts

@@ -0,0 +1,39 @@
+import type { Readable } from "node:stream";
+import { groupStatus, type ServiceProcessIdentity, type ServiceIdentityInspector } from "./background-service-store.js";
+export declare function safeServiceNodeVersion(version: string): boolean;
+export declare function probeServiceRuntime(executable: string): Promise<string[]>;
+export interface ServiceProcess {
+    identity: ServiceProcessIdentity;
+    send(message: unknown): void;
+    prepare(): Promise<ServiceProcessIdentity>;
+    activate(hello: unknown): void;
+    terminate(timeoutMs: number): Promise<boolean>;
+    /** Guardian stdio closed; use terminate() to confirm the entire group is dead. */
+    exited: Promise<void>;
+}
+/** This private guardian protocol has exactly two messages and one total byte
+ * budget, not an ever-growing line buffer. Reject before any identity syscall. */
+export declare function readServiceCustody(stream: Readable, guardianPid: number, identities: ServiceIdentityInspector): {
+    custody: Promise<ServiceProcessIdentity>;
+    member: Promise<ServiceProcessIdentity>;
+    close: (error?: Error) => void;
+    readonly memberIdentity: ServiceProcessIdentity | undefined;
+    readonly retainedBytes: number;
+};
+/** A guardian's close event only confirms its stdio closed. A signalled native
+ * member may still be executing; only the OS group observation confirms death. */
+export declare function waitForServiceGroupExit(pid: number, timeoutMs: number, observe?: () => ReturnType<typeof groupStatus>, clock?: () => number, yieldTurn?: (delayMs: number) => Promise<void>): Promise<boolean>;
+export declare function spawnServiceProcess(input: {
+    executable: string;
+    entry: string;
+    sha256: string;
+    packageRoot: string;
+    cwd: string;
+    maxLineBytes: number;
+    onLine(message: unknown): void;
+    onExit(error?: string): void;
+}, adapters?: {
+    /** Explicit OS/runtime boundaries for owned-process fault tests; never guest supplied. */
+    identities?: ServiceIdentityInspector;
+    probeRuntime?: typeof probeServiceRuntime;
+}): Promise<ServiceProcess>;