starmux 0.13.1 → 0.15.0

package/dist/src/global-core-control.js

@@ -1,6 +1,7 @@
 import { ownedByUser, createPrivateDirectory, controlRoot, windows } from "./platform.js";
 import { ownerSchema } from "./config-schemas.js";
 import { GatewayError, errorCode, isSafeInteger, parseJSON, record } from "./validation.js";
+const CONTROL_VERSION = 1;
 // One Core / two equal frontends. Owner-only local supervisor control.
 // The socket is never an MCP/public endpoint, and never signals a discovered PID.
 import crypto from "node:crypto";
@@ -17,7 +18,7 @@ export function controlPaths(port, root = controlRoot()) {
         deny("CORE_INVALID_PORT");
     const lock = path.join(root, `core-${port}.lease`);
     return { root, lock, recovery: lock + ".recovery",
-        meta: path.join(lock, "owner.json"), socket: windows ? `\\\\.\\pipe\\mac-mcp-gateway-${crypto.createHash("sha256").update(path.resolve(lock).toLowerCase()).digest("hex").slice(0, 32)}` : path.join(lock, "control.sock") };
+        meta: path.join(lock, "owner.json"), socket: windows ? `\\\\.\\pipe\\starmux-${crypto.createHash("sha256").update(path.resolve(lock).toLowerCase()).digest("hex").slice(0, 32)}` : path.join(lock, "control.sock") };
 }
 function secureDir(p, create = false) {
     if (create)
@@ -39,7 +40,10 @@ function readOwner(paths) {
     const d = fs.readFileSync(paths.meta);
     if (d.length > 1024)
         deny("CORE_CONTROL_METADATA_INVALID");
-    const checked = ownerSchema.safeParse(parseJSON(d.toString("utf8")));
+    const metadata = record(parseJSON(d.toString("utf8")), "CORE_CONTROL_METADATA_INVALID");
+    if (metadata.version !== CONTROL_VERSION)
+        deny("CORE_CONTROL_PROTOCOL_UNSUPPORTED");
+    const checked = ownerSchema.safeParse(metadata);
     if (!checked.success)
         deny("CORE_CONTROL_METADATA_INVALID");
     const owner = checked.data;
@@ -71,7 +75,7 @@ async function exchange(paths, owner, method, timeoutMs = 11500) {
                 resolve(result);
         };
         client.once("connect", () => client.write(JSON.stringify({
-            version: 1, ...(windows ? { nonce, proof: proof(owner.token, nonce + ":" + owner.runId + ":" + method) } : { token: owner.token }), runId: owner.runId, method
+            version: CONTROL_VERSION, ...(windows ? { nonce, proof: proof(owner.token, nonce + ":" + owner.runId + ":" + method) } : { token: owner.token }), runId: owner.runId, method
         }) + "\n"));
         client.on("data", d => {
             body += d.toString("utf8");
@@ -83,8 +87,10 @@ async function exchange(paths, owner, method, timeoutMs = 11500) {
                 const reply = record(parseJSON(body.split("\n")[0]));
                 if (windows && reply.proof !== proof(owner.token, nonce + ":" + String(reply.result)))
                     throw Error("CORE_CONTROL_REPLY_UNAUTHENTICATED");
-                if (reply.runId !== owner.runId || !["RUNNING", "STARTING", "STOPPED",
-                    "STOP_FAILED"].includes(String(reply.result)))
+                if (reply.version !== CONTROL_VERSION || reply.result === "PROTOCOL_UNSUPPORTED")
+                    throw Error("CORE_CONTROL_PROTOCOL_UNSUPPORTED");
+                if (reply.runId !== owner.runId || !["RUNNING", "STARTING", "STOPPING", "STOPPED",
+                    "STOP_ACCEPTED", "STOP_FAILED"].includes(String(reply.result)))
                     throw Error("CORE_CONTROL_REPLY_INVALID");
                 finish(null, { result: String(reply.result), runId: owner.runId, launcher: owner.launcher });
             }
@@ -153,35 +159,70 @@ function cleanStale(paths) {
         catch { }
     }
 }
-export async function connectOwner(port, { root } = {}) {
+export function inspectControlOwner(port, { root } = {}) {
     const paths = controlPaths(port, root);
-    let owner;
     try {
-        owner = readOwner(paths);
+        return readOwner(paths);
     }
     catch (e) {
-        if (["ENOENT"].includes(errorCode(e) || ""))
+        if (errorCode(e) === "ENOENT" && !fs.existsSync(paths.lock))
             return null;
         throw e;
     }
+}
+export async function connectOwner(port, { root } = {}) {
+    const paths = controlPaths(port, root);
+    const owner = inspectControlOwner(port, { root });
+    if (!owner || !alive(owner.pid))
+        return null;
     const result = await exchange(paths, owner, "status", 1500);
     return { owner, result };
 }
-export async function globalStop(port, { root } = {}) {
+export async function globalStop(port, { root, timeoutMs = 65000 } = {}) {
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0)
+        deny("CORE_STOP_TIMEOUT_INVALID");
     const paths = controlPaths(port, root);
     let owner;
     try {
         owner = readOwner(paths);
     }
     catch (e) {
-        if (errorCode(e) === "ENOENT")
+        if (errorCode(e) === "ENOENT" && !fs.existsSync(paths.lock))
             return { result: "NO_CONTROL_OWNER" };
         throw e;
     }
-    const result = await exchange(paths, owner, "stop");
-    if (result.result !== "STOPPED")
+    const deadline = Date.now() + timeoutMs;
+    const result = await exchange(paths, owner, "stop", Math.min(11500, timeoutMs));
+    if (result.result !== "STOP_ACCEPTED")
         deny("CORE_STOP_UNVERIFIED");
-    return { result: "STOPPED", launcher: owner.launcher, ownerPid: owner.pid };
+    // The acknowledgment only accepts the request. Completion belongs to this
+    // lease, not to whatever may bind the same port after it has been released.
+    while (Date.now() < deadline) {
+        try {
+            const current = readOwner(paths);
+            if (current.runId !== owner.runId)
+                return { result: "STOPPED", launcher: owner.launcher, ownerPid: owner.pid, restarted: true };
+            try {
+                const state = await exchange(paths, owner, "status", Math.min(250, Math.max(1, deadline - Date.now())));
+                if (state.result === "STOP_FAILED")
+                    deny("CORE_STOP_FAILED");
+            }
+            catch (e) {
+                // Closing the control listener is part of releasing the lease.
+                if (!["ENOENT", "ECONNREFUSED", "ECONNRESET", "EPIPE"].includes(errorCode(e) ?? "") &&
+                    !["CORE_CONTROL_EOF", "CORE_CONTROL_TIMEOUT"].includes(e instanceof Error ? e.message : ""))
+                    throw e;
+            }
+        }
+        catch (e) {
+            if (errorCode(e) !== "ENOENT")
+                throw e;
+            if (!fs.existsSync(paths.lock))
+                return { result: "STOPPED", launcher: owner.launcher, ownerPid: owner.pid, restarted: false };
+        }
+        await delay(Math.min(50, Math.max(1, deadline - Date.now())));
+    }
+    deny("CORE_STOP_TIMEOUT");
 }
 export async function acquireControl(port, { root, launcher = "cli" } = {}) {
     if (!["cli", "app"].includes(launcher))
@@ -226,18 +267,21 @@ export async function acquireControl(port, { root, launcher = "cli" } = {}) {
             deny("CORE_CONTROL_CLAIM_TIMEOUT");
     }
     secureDir(paths.lock);
-    const owner = { version: 1, port, pid: process.pid, launcher,
+    const owner = { version: CONTROL_VERSION, port, pid: process.pid, launcher,
         token: crypto.randomBytes(24).toString("hex"),
         runId: crypto.randomBytes(16).toString("hex") };
     fs.writeFileSync(paths.meta, JSON.stringify(owner), { mode: 0o600, flag: "wx" });
-    let onStop = null, phase = "STARTING";
+    let onStop = null, phase = "STARTING", stopAccepted = false;
     const clients = new Set();
     const server = net.createServer(socket => {
         clients.add(socket);
         socket.setTimeout(12000, () => socket.destroy());
+        socket.on("error", () => { });
         socket.once("close", () => clients.delete(socket));
-        let raw = "";
-        socket.on("data", async (chunk) => {
+        let raw = "", handled = false;
+        socket.on("data", chunk => {
+            if (handled)
+                return;
             raw += chunk.toString("utf8");
             if (raw.length > 2048) {
                 socket.destroy();
@@ -246,7 +290,7 @@ export async function acquireControl(port, { root, launcher = "cli" } = {}) {
             if (!raw.includes("\n"))
                 return;
             const line = raw.split("\n")[0];
-            raw = "";
+            handled = true;
             let request;
             try {
                 request = record(parseJSON(line));
@@ -255,24 +299,30 @@ export async function acquireControl(port, { root, launcher = "cli" } = {}) {
                 socket.destroy();
                 return;
             }
-            if (request.version !== 1 ||
-                (windows ? typeof request.nonce !== "string" || request.nonce.length !== 48 || request.proof !== proof(owner.token, request.nonce + ":" + owner.runId + ":" + String(request.method)) : request.token !== owner.token) ||
+            if ((windows ? typeof request.nonce !== "string" || request.nonce.length !== 48 || request.proof !== proof(owner.token, request.nonce + ":" + owner.runId + ":" + String(request.method)) : request.token !== owner.token) ||
                 request.runId !== owner.runId) {
                 socket.destroy();
                 return;
             }
-            let result = "STOP_FAILED";
-            if (request.method === "status")
+            let result = "STOP_FAILED", startStop = false;
+            if (request.version !== CONTROL_VERSION)
+                result = "PROTOCOL_UNSUPPORTED";
+            else if (request.method === "status")
                 result = phase;
             else if (request.method === "stop" && onStop) {
-                try {
-                    result = await onStop();
-                }
-                catch {
-                    result = "STOP_FAILED";
+                if (phase !== "STOP_FAILED") {
+                    result = "STOP_ACCEPTED";
+                    startStop = !stopAccepted;
+                    stopAccepted = true;
+                    phase = "STOPPING";
                 }
             }
-            socket.end(JSON.stringify({ result, runId: owner.runId, launcher: owner.launcher, ...(windows ? { proof: proof(owner.token, String(request.nonce) + ":" + result) } : {}) }) + "\n");
+            socket.end(JSON.stringify({ version: CONTROL_VERSION, result, runId: owner.runId, launcher: owner.launcher, ...(windows ? { proof: proof(owner.token, String(request.nonce) + ":" + result) } : {}) }) + "\n", () => {
+                // Never await shutdown on its own control connection: release() waits
+                // for these sockets to close. Acceptance and completion are distinct.
+                if (startStop)
+                    void Promise.resolve().then(() => onStop()).catch(() => { phase = "STOP_FAILED"; });
+            });
         });
     });
     try {
@@ -301,41 +351,44 @@ export async function acquireControl(port, { root, launcher = "cli" } = {}) {
         catch { }
         throw e;
     }
-    let closing = false;
+    let releasePromise = null;
     return {
         owner,
         markRunning() { phase = "RUNNING"; },
         markStopped() { phase = "STOPPED"; },
         onStop(fn) { onStop = fn; },
-        async release() {
-            if (closing)
-                return;
-            closing = true;
-            // Response sockets close before the lease disappears.
-            await new Promise(resolve => {
-                server.close(resolve);
-                setTimeout(() => { for (const s of clients)
-                    s.destroy(); }, 1200).unref();
-            });
-            if (readOwner(paths).runId !== owner.runId)
-                deny("CORE_CONTROL_LEASE_CHANGED");
-            // node:net automatically unlinks a Unix socket on server.close().
-            // A second unlink is not required and must not abort lease cleanup.
-            try {
-                if (!windows)
-                    fs.unlinkSync(paths.socket);
-            }
-            catch (e) {
-                if (errorCode(e) !== "ENOENT")
-                    throw e;
-            }
-            fs.unlinkSync(paths.meta);
-            fs.rmdirSync(paths.lock);
+        release() {
+            return releasePromise ??= (async () => {
+                // Response sockets close before the lease disappears.
+                await new Promise((resolve, reject) => {
+                    const timer = setTimeout(() => { for (const s of clients)
+                        s.destroy(); }, 1200);
+                    timer.unref();
+                    server.close(error => { clearTimeout(timer); if (error)
+                        reject(error);
+                    else
+                        resolve(); });
+                });
+                if (readOwner(paths).runId !== owner.runId)
+                    deny("CORE_CONTROL_LEASE_CHANGED");
+                // node:net automatically unlinks a Unix socket on server.close().
+                // A second unlink is not required and must not abort lease cleanup.
+                try {
+                    if (!windows)
+                        fs.unlinkSync(paths.socket);
+                }
+                catch (e) {
+                    if (errorCode(e) !== "ENOENT")
+                        throw e;
+                }
+                fs.unlinkSync(paths.meta);
+                fs.rmdirSync(paths.lock);
+            })();
         }
     };
 }
 // Private worker handoff for the setup profile. This is a same-UID
-// supervisor identity check, not an OS boundary against the Mac owner.
+// supervisor identity check, not an OS boundary against the local owner.
 export function verifyInternalSetupWorker({ port, ownerPid, runId, token }) {
     const paths = controlPaths(port);
     const owner = readOwner(paths);
@@ -345,4 +398,3 @@ export function verifyInternalSetupWorker({ port, ownerPid, runId, token }) {
         deny("CORE_SETUP_WORKER_NOT_SUPERVISED");
     return true;
 }
-//# sourceMappingURL=global-core-control.js.map

package/dist/src/home-write-sandbox.js

@@ -47,4 +47,3 @@ export async function sandboxedDesktopSpawn({ home, nodeBinary, entryArgs, binar
         args: ["-p", homeWriteProfile(h), nodeBinary, ...entryArgs]
     };
 }
-//# sourceMappingURL=home-write-sandbox.js.map

package/dist/src/http-host-policy.js

@@ -0,0 +1,20 @@
+/** Host is an HTTP authority, not a URL; do not normalize alternate IP spellings or userinfo. */
+export function isAllowedGatewayHost(req, listenerPort, route) {
+    // Node keeps only one Host in headers; inspect rawHeaders to reject duplicates too.
+    let hostCount = 0;
+    for (let i = 0; i < req.rawHeaders.length; i += 2)
+        if (req.rawHeaders[i]?.toLowerCase() === 'host')
+            hostCount++;
+    const host = req.headers.host;
+    if (hostCount !== 1 || !host || listenerPort === null)
+        return false;
+    // Owner pages and discovery retain their existing listener-specific boundary.
+    if (route !== '/mcp')
+        return host === `127.0.0.1:${listenerPort}` || host === `localhost:${listenerPort}`;
+    // SSH forwards TCP bytes unchanged, including the client's local Host port.
+    // Keep the hostname allowlist and validate the entire authority, including its port.
+    const match = /^(?:127\.0\.0\.1|localhost)(?::([0-9]{1,5}))?$/i.exec(host);
+    if (!match || match[0] !== host)
+        return false;
+    return match[1] === undefined || (Number(match[1]) >= 1 && Number(match[1]) <= 65535);
+}

package/dist/src/instance-control-protocol.js

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+import { instanceConfigSchema } from './instance-store.js';
+// Version the local control contract independently of npm releases. Unknown
+// versions fail explicitly; additional descriptive fields are safe to ignore.
+export const INSTANCE_CONTROL_VERSION = 1;
+const runId = z.string().regex(/^[a-f0-9]{32}$/);
+export const instanceOwnerSchema = z.object({
+    protocolVersion: z.literal(INSTANCE_CONTROL_VERSION), instanceId: z.string().uuid(), runId,
+    pid: z.number().int().min(2), port: z.number().int().min(1024).max(65535),
+    token: z.string().regex(/^[a-f0-9]{64}$/), launcher: z.enum(['cli', 'app']), appParentPid: z.number().int().nullable()
+});
+export const activeConfigSchema = z.object({ config: instanceConfigSchema, revision: z.string(), effectiveRevision: z.string(), sourcePath: z.string() });
+export const runtimeStateSchema = z.object({
+    protocolVersion: z.literal(INSTANCE_CONTROL_VERSION), instanceId: z.string().uuid(), runId, pid: z.number().int().min(2),
+    launcher: z.enum(['cli', 'app']), appParentPid: z.number().int().nullable(), executionMode: z.enum(['foreground', 'background']).optional(),
+    permissionMode: z.enum(['global', 'workspace']).optional(), phase: z.enum(['starting', 'running', 'stopping', 'stopped', 'error']),
+    port: z.number().int().min(1024).max(65535).nullable(), active: activeConfigSchema.nullable(), problem: z.string().nullable(),
+    coreProgram: z.string(), buildVersion: z.string()
+});
+export const controlRequestSchema = z.object({ protocolVersion: z.literal(INSTANCE_CONTROL_VERSION), method: z.enum(['status', 'stop', 'apply']),
+    revision: z.string().nullable(), runId, nonce: z.string().regex(/^[a-f0-9]{48}$/) });
+export const controlReplySchema = z.object({ protocolVersion: z.literal(INSTANCE_CONTROL_VERSION), state: runtimeStateSchema,
+    result: z.enum(['STATE', 'STOP_ACCEPTED']), error: z.string().optional() });
+export function checkInstanceProtocol(value) {
+    if (!value || typeof value !== 'object' || !('protocolVersion' in value) || value.protocolVersion !== INSTANCE_CONTROL_VERSION)
+        throw Error('INSTANCE_CONTROL_PROTOCOL_UNSUPPORTED');
+}