@cjhyy/code-shell-server 0.8.0

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

@@ -0,0 +1,345 @@
+import { createServer } from "node:http";
+import { networkInterfaces } from "node:os";
+import { EventEmitter } from "node:events";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { WebSocketServer } from "ws";
+import { serveMobile } from "./mobile-static.js";
+import { PairingTokenManager } from "./pairing.js";
+/**
+ * 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
+ * §6.5 network-safety rule. Excludes loopback (127.x), link-local (169.254.x),
+ * and common VPN/tunnel ranges (198.18.x carrier-grade test net used by some
+ * VPN clients) so we don't advertise an address the phone can't route to.
+ * Returns undefined if no suitable interface is found.
+ */
+export function resolveLanHost() {
+    const ifaces = networkInterfaces();
+    const candidates = [];
+    for (const addrs of Object.values(ifaces)) {
+        for (const addr of addrs ?? []) {
+            if (addr.family !== "IPv4" || addr.internal)
+                continue;
+            const ip = addr.address;
+            if (ip.startsWith("127.") || ip.startsWith("169.254.") || ip.startsWith("198.18.")) {
+                continue;
+            }
+            candidates.push(ip);
+        }
+    }
+    // Prefer private LAN ranges (192.168.x, 10.x, 172.16-31.x) over anything else.
+    const isPrivate = (ip) => ip.startsWith("192.168.") || ip.startsWith("10.") || /^172\.(1[6-9]|2\d|3[01])\./.test(ip);
+    return candidates.find(isPrivate) ?? candidates[0];
+}
+export class RemoteHostManager extends EventEmitter {
+    opts;
+    server;
+    wss;
+    started;
+    pairing = new PairingTokenManager();
+    /** ws → authenticated device id. A socket absent here is unauthenticated. */
+    authed = new WeakMap();
+    /** Stable identity for each individual tab/socket, independent of device id. */
+    viewers = new WeakMap();
+    nextViewerId = 1;
+    /** deviceId → number of live authenticated sockets (a phone may open more
+     *  than one). A device is "online" while its count is > 0. */
+    onlineCounts = new Map();
+    /** Public base URL (tunnel domain) used by createPairingUrl when set. */
+    publicBaseUrl;
+    /** Passcode gate, present only in tunnel mode. */
+    passcode;
+    /** Where the built mobile app lives (out/mobile). */
+    mobileRootDir;
+    /** Dev proxy target for /mobile (HMR); undefined in prod. */
+    mobileDevUrl;
+    constructor(opts) {
+        super();
+        this.opts = opts;
+        // Bundled main is out/main/index.mjs → mobile app is the sibling out/mobile.
+        const here = dirname(fileURLToPath(import.meta.url));
+        this.mobileRootDir = opts.mobileRootDir ?? resolve(here, "../mobile");
+        this.mobileDevUrl = opts.mobileDevUrl ?? process.env.MOBILE_DEV_URL;
+    }
+    /** Device ids with at least one live socket right now. */
+    onlineDeviceIds() {
+        return [...this.onlineCounts.keys()];
+    }
+    /** Register a live socket for a device; emits `online-change` only when the
+     *  device transitions offline→online (first socket). */
+    markOnline(deviceId) {
+        const prev = this.onlineCounts.get(deviceId) ?? 0;
+        this.onlineCounts.set(deviceId, prev + 1);
+        if (prev === 0)
+            this.emit("online-change", this.onlineDeviceIds());
+    }
+    /** Drop a socket for a device; emits `online-change` only when its last
+     *  socket goes away (online→offline). */
+    markOffline(deviceId) {
+        const prev = this.onlineCounts.get(deviceId) ?? 0;
+        if (prev <= 1) {
+            if (this.onlineCounts.delete(deviceId)) {
+                this.emit("online-change", this.onlineDeviceIds());
+                this.emit("device-offline", deviceId);
+            }
+        }
+        else {
+            this.onlineCounts.set(deviceId, prev - 1);
+        }
+    }
+    async start(options) {
+        if (this.started)
+            return this.started;
+        const tunnel = options.mode === "tunnel";
+        this.passcode = tunnel ? options.passcode : undefined;
+        const gate = this.passcode;
+        const server = createServer((req, res) => {
+            // 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;
+            }
+            const uploadPath = req.url
+                ? new URL(req.url, "http://localhost").pathname.match(/^\/api\/mobile\/uploads\/([A-Za-z0-9_-]+)$/)
+                : null;
+            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: tunnel ? undefined : this.mobileDevUrl,
+                });
+                return;
+            }
+            res.writeHead(404);
+            res.end("not found");
+        });
+        // 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
+        // handshake; in lan mode behaviour is unchanged (the same path/server bind).
+        this.wss = gate
+            ? new WebSocketServer({ noServer: true, maxPayload: 1024 * 1024 })
+            : new WebSocketServer({ server, path: "/ws", maxPayload: 1024 * 1024 });
+        if (gate) {
+            server.on("upgrade", (req, socket, head) => {
+                if (!req.url?.startsWith("/ws")) {
+                    socket.destroy();
+                    return;
+                }
+                if (!gate.allows(req)) {
+                    socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
+                    socket.destroy();
+                    return;
+                }
+                this.wss.handleUpgrade(req, socket, head, (ws) => {
+                    this.wss.emit("connection", ws, req);
+                });
+            });
+        }
+        this.wss.on("connection", (ws) => {
+            const viewerId = `viewer-${this.nextViewerId++}`;
+            this.viewers.set(ws, viewerId);
+            ws.on("message", (raw) => {
+                let event;
+                try {
+                    event = JSON.parse(String(raw));
+                }
+                catch {
+                    ws.send(JSON.stringify({ type: "error", message: "Invalid JSON" }));
+                    return;
+                }
+                // Pairing/auth are handled inline and bind device identity to this
+                // socket. Everything else is gated: an unauthenticated socket cannot
+                // send chat/approval/run/job events (design §6.1).
+                const reply = this.handleClientEvent(event);
+                if (event.type === "auth.device" && reply?.type === "auth.ok") {
+                    if (!this.authed.has(ws))
+                        this.markOnline(reply.device.id);
+                    this.authed.set(ws, reply.device.id);
+                }
+                // Pairing also yields a live, identified socket → count it online.
+                if (event.type === "pair.complete" && reply?.type === "pair.ok") {
+                    if (!this.authed.has(ws))
+                        this.markOnline(reply.device.id);
+                    this.authed.set(ws, reply.device.id);
+                }
+                if (reply) {
+                    ws.send(JSON.stringify(reply));
+                    return;
+                }
+                if (!this.authed.has(ws)) {
+                    ws.send(JSON.stringify({ type: "auth.failed", message: "Not authenticated" }));
+                    return;
+                }
+                // Authenticated, non-auth event → hand to the main dispatcher, which
+                // routes chat/approval into the existing run/permission path.
+                this.opts.onClientEvent({ ...event, deviceId: this.authed.get(ws), viewerId: this.viewers.get(ws) }, ws);
+            });
+            ws.on("close", () => {
+                this.releaseSocket(ws);
+            });
+        });
+        this.server = server;
+        // host: "lan" → resolve the Mac's real LAN IPv4 so a phone on the same
+        // Wi-Fi can reach us. We bind that concrete address (never 0.0.0.0). If no
+        // LAN interface is found, fall back to the requested host (e.g. localhost).
+        const bindHost = tunnel
+            ? "127.0.0.1"
+            : options.host === "lan"
+                ? (resolveLanHost() ?? "127.0.0.1")
+                : options.host;
+        await new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(options.port, bindHost, () => resolve());
+        });
+        const addr = server.address();
+        const port = typeof addr === "object" && addr ? addr.port : options.port;
+        this.started = {
+            host: bindHost,
+            port,
+            url: `http://${bindHost}:${port}`,
+            mode: tunnel ? "tunnel" : "lan",
+        };
+        return this.started;
+    }
+    /**
+     * Override the base URL used to build pairing URLs (tunnel mode points this
+     * at the `https://*.trycloudflare.com` domain so the QR encodes the public
+     * address, not the loopback bind). Pass undefined to clear it.
+     */
+    setPublicBaseUrl(url) {
+        this.publicBaseUrl = url;
+    }
+    createPairingUrl() {
+        if (!this.started)
+            throw new Error("Remote host is not running");
+        const token = this.pairing.createToken();
+        const base = this.publicBaseUrl ?? this.started.url;
+        return {
+            token: token.value,
+            expiresAt: token.expiresAt,
+            url: `${base}/mobile?pairing=${token.value}`,
+        };
+    }
+    /**
+     * Handle pairing/auth client events. Returns a server event for those two
+     * cases (consumed inline by the WS layer) or `undefined` for events the
+     * caller should route elsewhere. Pairing tokens are one-use; auth checks the
+     * trusted-device store (which rejects revoked devices), so the remote host
+     * never executes tools itself — it only gates transport.
+     */
+    handleClientEvent(event) {
+        if (event.type === "pair.complete") {
+            if (!this.pairing.consume(event.token)) {
+                return { type: "pair.failed", message: "Pairing token expired or invalid" };
+            }
+            const device = this.opts.devices.addDevice({
+                name: event.name,
+                secretHash: event.secretHash,
+            });
+            return { type: "pair.ok", device };
+        }
+        if (event.type === "auth.device") {
+            const device = this.opts.devices.authenticate(event.deviceId, event.secretHash);
+            if (!device)
+                return { type: "auth.failed", message: "Device is not trusted" };
+            return { type: "auth.ok", device };
+        }
+        return undefined;
+    }
+    /** Broadcast a server event to every connected, authenticated mobile socket. */
+    broadcast(event) {
+        this.broadcastRaw(JSON.stringify(event));
+    }
+    /** Send a server event to ONLY the sockets belonging to one device. Used for
+     *  per-device replies (chat.accepted, session.list.ok, permission.mode, …) so
+     *  one phone's session/permission state never leaks onto another's screen.
+     *  A device with no live socket (raced a disconnect) is a silent no-op. */
+    sendToDevice(deviceId, event) {
+        const payload = JSON.stringify(event);
+        for (const client of this.wss?.clients ?? []) {
+            if (client.readyState === client.OPEN && this.authed.get(client) === deviceId) {
+                client.send(payload);
+            }
+        }
+    }
+    /** Send a raw JSON-RPC worker line to ONLY one authenticated device. */
+    sendRawToDevice(deviceId, payload) {
+        for (const client of this.wss?.clients ?? []) {
+            if (client.readyState === client.OPEN && this.authed.get(client) === deviceId) {
+                client.send(payload);
+            }
+        }
+    }
+    /** Broadcast a raw line (e.g. a mirrored worker→renderer JSON-RPC line) to
+     *  every authenticated mobile socket. Unauthenticated sockets are skipped so
+     *  a half-paired client never sees session output. */
+    broadcastRaw(payload) {
+        for (const client of this.wss?.clients ?? []) {
+            if (client.readyState === client.OPEN && this.authed.has(client)) {
+                client.send(payload);
+            }
+        }
+    }
+    releaseSocket(ws) {
+        const deviceId = this.authed.get(ws);
+        const viewerId = this.viewers.get(ws);
+        this.authed.delete(ws);
+        this.viewers.delete(ws);
+        if (!deviceId)
+            return;
+        if (viewerId) {
+            this.emit("viewer-offline", { deviceId, viewerId });
+        }
+        this.markOffline(deviceId);
+    }
+    async stop() {
+        const server = this.server;
+        // Forcibly drop live WS sockets first. wss.close() alone waits for clients
+        // to disconnect, so a phone left connected would hang stop() indefinitely.
+        // terminate() severs each immediately.
+        for (const client of this.wss?.clients ?? []) {
+            // Release viewer-owned resources synchronously. The later socket close
+            // event is idempotent because releaseSocket removes its auth binding.
+            this.releaseSocket(client);
+            client.terminate();
+        }
+        this.wss?.close();
+        this.wss = undefined;
+        this.server = undefined;
+        this.started = undefined;
+        this.publicBaseUrl = undefined;
+        this.passcode = undefined;
+        // releaseSocket normally empties this map. Retain a defensive fallback for
+        // manually injected bookkeeping (tests / future non-WS transports).
+        for (const deviceId of this.onlineCounts.keys())
+            this.emit("device-offline", deviceId);
+        this.onlineCounts.clear();
+        await this.opts.uploads?.cancelActiveTransfers();
+        if (!server)
+            return;
+        // server.close() only stops accepting new connections and waits for live
+        // ones to end — a lingering upgraded/keep-alive socket keeps its callback
+        // from ever firing. Destroy any remaining connections so close() resolves.
+        server.closeAllConnections?.();
+        await new Promise((resolve) => server.close(() => resolve()));
+    }
+    status() {
+        return this.started;
+    }
+}

package/dist/mobile-remote/resident-agent.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Normalized event emitted from a resident stream-json claude process. The
+ * raw stream-json is collapsed into a small, render-friendly union that the
+ * room layer persists to messages.jsonl and mirrors to the phone. System
+ * hook/init noise is dropped.
+ */
+export type ResidentAgentEvent = {
+    type: "text";
+    text: string;
+} | {
+    type: "tool";
+    id?: string;
+    tool: string;
+    summary: string;
+    input?: Record<string, unknown>;
+} | {
+    type: "tool_result";
+    id?: string;
+    summary: string;
+    isError: boolean;
+} | {
+    type: "turn_end";
+    reason: string;
+} | {
+    type: "error";
+    error: string;
+} | {
+    type: "exit";
+    code: number | null;
+    signal: string | null;
+} | {
+    type: "approval_request";
+    requestId: string;
+    toolName: string;
+    displayName?: string;
+    input: unknown;
+    description?: string;
+};
+/** A decision for a tool-approval (`can_use_tool`) control request. */
+export type ControlDecision = {
+    behavior: "allow";
+    updatedInput?: unknown;
+} | {
+    behavior: "deny";
+    message: string;
+};
+/**
+ * Build the `control_response` envelope claude expects on stdin for a
+ * `can_use_tool` prompt. Pure + exported so the wire shape is unit-testable.
+ *
+ * Critically: the stdio control protocol's Zod schema requires `updatedInput`
+ * to be a RECORD on the allow branch — an allow decision that omits it makes
+ * claude reject the whole response (ZodError invalid_union) and the tool
+ * silently fails. So we default a missing `updatedInput` to `{}` here, at the
+ * single choke point where every decision becomes wire bytes, regardless of
+ * which caller (renderer, phone, future code) produced it.
+ */
+export declare function buildControlResponse(requestId: string, decision: ControlDecision): {
+    type: string;
+    response: {
+        subtype: string;
+        request_id: string;
+        response: ControlDecision;
+    };
+};
+/**
+ * Parse ONE line of claude stream-json output into zero-or-more normalized
+ * events. Returns [] for lines we intentionally ignore (system/init/hook/
+ * rate_limit) or unparseable lines. Pure + synchronous so it is unit-testable
+ * against recorded output without spawning claude.
+ */
+export declare function parseStreamJsonLine(line: string): ResidentAgentEvent[];
+export interface ResidentAgentOptions {
+    command: string;
+    cwd: string;
+    permissionMode: "default" | "acceptEdits" | "bypassPermissions";
+    resumeSessionId?: string;
+    /** Optional host policy appended to the external agent's system prompt. */
+    appendSystemPrompt?: string;
+    onEvent: (event: ResidentAgentEvent) => void;
+}
+/**
+ * A long-lived claude process in stream-json mode. Feed user turns via send();
+ * normalized events arrive on onEvent. Context is continuous for the lifetime
+ * of the process (same conversation). Stopped explicitly via stop().
+ */
+export declare class ResidentAgentProcess {
+    private readonly opts;
+    private child?;
+    constructor(opts: ResidentAgentOptions);
+    start(): void;
+    /** Feed one user turn. Returns false if the process isn't running. */
+    send(text: string): boolean;
+    /** Reply to a `control_request` (can_use_tool) approval prompt over stdin. */
+    respondControl(requestId: string, decision: ControlDecision): void;
+    isRunning(): boolean;
+    stop(): void;
+}

package/dist/mobile-remote/resident-agent.js

@@ -0,0 +1,216 @@
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { pathWithCommonBins } from "./path-bins.js";
+/**
+ * Build the `control_response` envelope claude expects on stdin for a
+ * `can_use_tool` prompt. Pure + exported so the wire shape is unit-testable.
+ *
+ * Critically: the stdio control protocol's Zod schema requires `updatedInput`
+ * to be a RECORD on the allow branch — an allow decision that omits it makes
+ * claude reject the whole response (ZodError invalid_union) and the tool
+ * silently fails. So we default a missing `updatedInput` to `{}` here, at the
+ * single choke point where every decision becomes wire bytes, regardless of
+ * which caller (renderer, phone, future code) produced it.
+ */
+export function buildControlResponse(requestId, decision) {
+    const normalized = decision.behavior === "allow"
+        ? { behavior: "allow", updatedInput: decision.updatedInput ?? {} }
+        : decision;
+    return {
+        type: "control_response",
+        response: { subtype: "success", request_id: requestId, response: normalized },
+    };
+}
+const TOOL_SUMMARY_KEYS = ["command", "file_path", "path", "url", "pattern", "query"];
+function argsSummary(input) {
+    if (!input)
+        return "";
+    for (const k of TOOL_SUMMARY_KEYS) {
+        const v = input[k];
+        if (typeof v === "string")
+            return v;
+    }
+    return "";
+}
+/**
+ * Parse ONE line of claude stream-json output into zero-or-more normalized
+ * events. Returns [] for lines we intentionally ignore (system/init/hook/
+ * rate_limit) or unparseable lines. Pure + synchronous so it is unit-testable
+ * against recorded output without spawning claude.
+ */
+export function parseStreamJsonLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return [];
+    let msg;
+    try {
+        msg = JSON.parse(trimmed);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    if (msg.type === "control_request" && msg.request?.subtype === "can_use_tool") {
+        return [
+            {
+                type: "approval_request",
+                requestId: String(msg.request_id ?? ""),
+                toolName: String(msg.request?.tool_name ?? "tool"),
+                displayName: typeof msg.request?.display_name === "string" ? msg.request.display_name : undefined,
+                input: msg.request?.input,
+                description: typeof msg.request?.description === "string" ? msg.request.description : undefined,
+            },
+        ];
+    }
+    if (msg.type === "assistant" && Array.isArray(msg.message?.content)) {
+        for (const c of msg.message.content) {
+            if (c.type === "text" && typeof c.text === "string") {
+                out.push({ type: "text", text: c.text });
+            }
+            else if (c.type === "tool_use") {
+                out.push({
+                    type: "tool",
+                    id: typeof c.id === "string" ? c.id : undefined,
+                    tool: c.name ?? "tool",
+                    summary: argsSummary(c.input),
+                    input: c.input && typeof c.input === "object" ? c.input : undefined,
+                });
+            }
+        }
+        return out;
+    }
+    if (msg.type === "user" && Array.isArray(msg.message?.content)) {
+        for (const c of msg.message.content) {
+            if (c.type === "tool_result") {
+                const text = Array.isArray(c.content)
+                    ? c.content.map((p) => (typeof p?.text === "string" ? p.text : "")).join("")
+                    : typeof c.content === "string"
+                        ? c.content
+                        : "";
+                out.push({
+                    type: "tool_result",
+                    id: typeof c.tool_use_id === "string" ? c.tool_use_id : undefined,
+                    summary: text.slice(0, 400),
+                    isError: Boolean(c.is_error),
+                });
+            }
+        }
+        return out;
+    }
+    if (msg.type === "result") {
+        out.push({
+            type: "turn_end",
+            reason: typeof msg.subtype === "string" ? msg.subtype : "completed",
+        });
+        return out;
+    }
+    // system (init/hook), rate_limit_event, etc. → ignored noise.
+    return out;
+}
+/**
+ * A long-lived claude process in stream-json mode. Feed user turns via send();
+ * normalized events arrive on onEvent. Context is continuous for the lifetime
+ * of the process (same conversation). Stopped explicitly via stop().
+ */
+export class ResidentAgentProcess {
+    opts;
+    child;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    start() {
+        if (this.child)
+            return;
+        const args = [
+            "--print",
+            "--verbose",
+            "--input-format",
+            "stream-json",
+            "--output-format",
+            "stream-json",
+            "--permission-prompt-tool",
+            "stdio",
+        ];
+        if (this.opts.appendSystemPrompt) {
+            args.push("--append-system-prompt", this.opts.appendSystemPrompt);
+        }
+        if (this.opts.resumeSessionId) {
+            args.push("--resume", this.opts.resumeSessionId);
+        }
+        args.push("--permission-mode", this.opts.permissionMode);
+        const child = spawn(this.opts.command, args, {
+            cwd: this.opts.cwd,
+            env: { ...process.env, PATH: pathWithCommonBins() },
+            detached: true,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        this.child = child;
+        if (child.stdout) {
+            const rl = createInterface({ input: child.stdout });
+            rl.on("line", (line) => {
+                for (const ev of parseStreamJsonLine(line))
+                    this.opts.onEvent(ev);
+            });
+        }
+        child.stderr?.on("data", (chunk) => {
+            // claude prints non-fatal warnings to stderr; surface as error events
+            // only if they look like real errors (cheap heuristic).
+            const text = String(chunk);
+            if (/error/i.test(text))
+                this.opts.onEvent({ type: "error", error: text.trim().slice(0, 400) });
+        });
+        child.on("error", (err) => {
+            const isMissing = err.code === "ENOENT";
+            this.opts.onEvent({
+                type: "error",
+                error: isMissing
+                    ? `未找到命令 "${this.opts.command}"。请先安装 Claude Code CLI 并确保它在 PATH 中。`
+                    : err.message,
+            });
+        });
+        child.on("exit", (code, signal) => {
+            this.child = undefined;
+            this.opts.onEvent({ type: "exit", code, signal });
+        });
+    }
+    /** Feed one user turn. Returns false if the process isn't running. */
+    send(text) {
+        if (!this.child?.stdin || this.child.stdin.destroyed)
+            return false;
+        const line = JSON.stringify({ type: "user", message: { role: "user", content: text } });
+        this.child.stdin.write(line + "\n");
+        return true;
+    }
+    /** Reply to a `control_request` (can_use_tool) approval prompt over stdin. */
+    respondControl(requestId, decision) {
+        if (!this.child?.stdin || this.child.stdin.destroyed)
+            return;
+        this.child.stdin.write(JSON.stringify(buildControlResponse(requestId, decision)) + "\n");
+    }
+    isRunning() {
+        return Boolean(this.child);
+    }
+    stop() {
+        const child = this.child;
+        this.child = undefined;
+        // Guard pid > 1: process.kill(-1) would SIGTERM every process the user can
+        // reach, and -0 the caller's own group. `!child?.pid` already catches
+        // undefined/0; the `> 1` also rules out the (theoretical) pid-1 case so this
+        // negative-pid group kill is consistent with killProcessGroup's guard.
+        if (!child?.pid || child.pid <= 1) {
+            child?.kill("SIGTERM");
+            return;
+        }
+        try {
+            process.kill(-child.pid, "SIGTERM");
+        }
+        catch {
+            try {
+                child.kill("SIGTERM");
+            }
+            catch {
+                /* already gone */
+            }
+        }
+    }
+}