starmux 0.13.1 → 0.15.0

package/dist/src/instance-runtime.js

@@ -1,17 +1,17 @@
 import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
 import { createServer, createConnection } from 'node:net';
 import { fork } from 'node:child_process';
-import { mkdir, rm, readFile, open, lstat } from 'node:fs/promises';
+import { mkdir, rm, open } from 'node:fs/promises';
+import { setTimeout as pause } from 'node:timers/promises';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 import { homedir } from 'node:os';
-import { z } from 'zod';
+import { INSTANCE_CONTROL_VERSION, instanceOwnerSchema, activeConfigSchema, runtimeStateSchema, controlRequestSchema, controlReplySchema, checkInstanceProtocol } from './instance-control-protocol.js';
 import { controlRoot, createPrivateDirectory, childEnvKeys, windows } from './platform.js';
-import { acquireControl } from './global-core-control.js';
+import { acquireControl, inspectControlOwner } from './global-core-control.js';
 import { runtimeIdentity } from './runtime-identity.js';
 import { atomicPrivate, changeRegistry, availablePort, ensureAccessReady, exists, instanceEnv, instancePaths, loadInstanceConfig, prepareUpstreams, readTrusted, resolveInstance } from './instance-store.js';
-const metadataSchema = z.object({ instanceId: z.string().uuid(), runId: z.string().regex(/^[a-f0-9]{32}$/), pid: z.number().int().min(2), token: z.string().regex(/^[a-f0-9]{64}$/), launcher: z.enum(['cli', 'app']), appParentPid: z.number().int().nullable() }).strict();
-function runtimePaths(id) {
+export function runtimePaths(id) {
     const root = path.join(controlRoot(), 'i-' + id);
     const socket = windows ? '\\\\.\\pipe\\gateway-instance-' + createHash('sha256').update(root).digest('hex').slice(0, 28) : path.join(root, 'control.sock');
     return { root, socket, meta: path.join(root, 'owner.json') };
@@ -29,21 +29,21 @@ async function ownerFor(instance) {
     const p = runtimePaths(instance.id);
     if (!await exists(p.root))
         return null;
-    const owner = metadataSchema.parse(JSON.parse(await readTrusted(p.meta)));
+    const raw = JSON.parse(await readTrusted(p.meta));
+    checkInstanceProtocol(raw);
+    const owner = instanceOwnerSchema.parse(raw);
     if (owner.instanceId !== instance.id)
         throw Error('INSTANCE_CONTROL_IDENTITY_INVALID');
     return owner;
 }
-export async function instanceRequest(instance, method, revision) {
-    const owner = await ownerFor(instance);
-    if (!owner || !alive(owner.pid))
-        return null;
+async function exchange(instance, owner, method, revision, timeoutMs = method === 'apply' ? 65000 : 2000) {
     const nonce = randomBytes(24).toString('hex');
-    const body = JSON.stringify({ method, revision: revision ?? null, runId: owner.runId, nonce });
+    const body = JSON.stringify({ protocolVersion: INSTANCE_CONTROL_VERSION, method, revision: revision ?? null, runId: owner.runId, nonce });
     return new Promise((resolve, reject) => {
         const socket = createConnection(runtimePaths(instance.id).socket);
         let raw = '';
-        socket.setTimeout(method === 'status' ? 2000 : 65000, () => socket.destroy(Error('INSTANCE_CONTROL_TIMEOUT')));
+        const timer = setTimeout(() => socket.destroy(Error('INSTANCE_CONTROL_TIMEOUT')), timeoutMs);
+        socket.once('close', () => clearTimeout(timer));
         socket.on('error', reject);
         socket.on('connect', () => socket.end(JSON.stringify({ body, proof: signature(owner.token, body) }) + '\n'));
         socket.on('data', data => { raw += String(data); if (raw.length > 524288)
@@ -51,14 +51,18 @@ export async function instanceRequest(instance, method, revision) {
         socket.on('end', () => {
             try {
                 const reply = JSON.parse(raw);
-                if (!equal(reply.proof, signature(owner.token, nonce + reply.body)))
+                if (typeof reply.body !== 'string' || !equal(reply.proof, signature(owner.token, nonce + reply.body)))
                     throw Error('INSTANCE_CONTROL_REPLY_UNTRUSTED');
-                const data = JSON.parse(reply.body);
+                const parsed = JSON.parse(reply.body);
+                checkInstanceProtocol(parsed);
+                const data = controlReplySchema.parse(parsed);
                 if (data.error)
                     throw Error(data.error);
                 if (data.state.instanceId !== instance.id || data.state.runId !== owner.runId)
                     throw Error('INSTANCE_CONTROL_IDENTITY_CHANGED');
-                resolve(data.state);
+                if (data.result !== (method === 'stop' ? 'STOP_ACCEPTED' : 'STATE'))
+                    throw Error('INSTANCE_CONTROL_REPLY_INVALID');
+                resolve(data);
             }
             catch (e) {
                 reject(e);
@@ -66,64 +70,139 @@ export async function instanceRequest(instance, method, revision) {
         });
     });
 }
+export async function instanceRequest(instance, method, revision) {
+    const owner = await ownerFor(instance);
+    if (!owner || !alive(owner.pid))
+        return null;
+    return (await exchange(instance, owner, method, revision)).state;
+}
+async function snapshot(file, schema) {
+    try {
+        return schema.parse(JSON.parse(await readTrusted(file)));
+    }
+    catch {
+        return null;
+    }
+}
 export async function instanceStatus(instance, home = homedir()) {
     let runtime = null;
     let runtimeProblem = null;
+    let owner = null;
     try {
-        runtime = await instanceRequest(instance, 'status');
+        owner = await ownerFor(instance);
+        if (owner && alive(owner.pid))
+            runtime = (await exchange(instance, owner, 'status')).state;
     }
     catch (e) {
         runtimeProblem = e.message;
     }
-    let saved = null;
+    let loaded = null;
     let configProblem = null;
     try {
-        saved = await loadInstanceConfig(instance);
+        loaded = await loadInstanceConfig(instance);
     }
     catch (e) {
         configProblem = e.message;
     }
-    let lastRuntime = null;
-    if (!runtime)
-        try {
-            lastRuntime = JSON.parse(await readTrusted(path.join(instancePaths(instance, home).snapshots, 'last-runtime.json')));
-        }
-        catch { }
-    if (!runtime && lastRuntime?.problem)
-        runtimeProblem ??= lastRuntime.problem;
+    const saved = loaded ? { config: loaded.config, revision: loaded.revision, effectiveRevision: loaded.effectiveRevision, sourcePath: loaded.source.path } : null;
+    const snapshots = instancePaths(instance, home).snapshots;
+    const lastRun = await snapshot(path.join(snapshots, 'last-runtime.json'), runtimeStateSchema);
+    const lastActive = await snapshot(path.join(snapshots, 'active.json'), activeConfigSchema);
     let health = 'not-running';
     let accessMode = null;
     let lastToolCallAt = null;
+    if (!runtime && !runtimeProblem) {
+        // Historical ports are hints for detecting a lost control channel, never
+        // authority to stop a process or claim a configuration is currently active.
+        const ports = new Set([owner?.port, saved?.config.port, lastActive?.config.port].filter((p) => p !== undefined));
+        for (const port of ports) {
+            if (!await availablePort(port)) {
+                runtimeProblem = 'INSTANCE_CONTROL_UNAVAILABLE: port ' + port + ' is in use; ownership is unconfirmed';
+                break;
+            }
+            try {
+                const lease = inspectControlOwner(port);
+                if (lease && alive(lease.pid)) {
+                    runtimeProblem = 'INSTANCE_CONTROL_UNAVAILABLE: live port lease ' + port;
+                    break;
+                }
+            }
+            catch (e) {
+                runtimeProblem = e.message;
+                break;
+            }
+        }
+    }
     if (runtime?.phase === 'running' && runtime.port) {
         try {
             const response = await fetch(`http://127.0.0.1:${runtime.port}/healthz`, { signal: AbortSignal.timeout(1500) });
             const data = await response.json();
             health = response.ok && data.status === 'ok' && data.instanceId === instance.id ? 'ok' : 'unrecognized';
             accessMode = data.accessMode ?? null;
-            const activity = await fetch(`http://127.0.0.1:${runtime.port}/activity.json`, { signal: AbortSignal.timeout(1000) }).then(r => r.json());
-            lastToolCallAt = typeof activity.lastToolCallAt === 'string' ? activity.lastToolCallAt : null;
+            if (health === 'ok')
+                try {
+                    const activity = await fetch(`http://127.0.0.1:${runtime.port}/activity.json`, { signal: AbortSignal.timeout(1000) }).then(r => r.json());
+                    lastToolCallAt = typeof activity.lastToolCallAt === 'string' ? activity.lastToolCallAt : null;
+                }
+                catch { /* Activity is optional; it must not turn a healthy service into an outage. */ }
         }
         catch {
             health = 'unreachable';
         }
     }
-    let active = runtime?.active ?? null;
-    if (!active)
-        try {
-            active = JSON.parse(await readTrusted(path.join(instancePaths(instance, home).snapshots, 'active.json')));
-        }
-        catch { }
+    const active = runtime?.active ?? null;
+    const phase = runtime?.phase ?? (runtimeProblem ? 'unknown' : 'stopped');
+    if (phase === 'unknown')
+        health = 'unknown';
     const configState = configProblem ? (configProblem.includes('ENOENT') ? 'missing' : 'invalid') : runtime?.phase === 'running' ? (saved?.effectiveRevision === active?.effectiveRevision ? 'applied' : 'pending') : 'on-next-start';
     return { schemaVersion: 1, event: 'GATEWAY_STATUS', instanceId: instance.id, name: instance.name, archived: instance.archived, source: instance.source,
-        phase: runtime?.phase ?? (runtimeProblem ? 'error' : 'stopped'), configState, configProblem, runtimeProblem, runtime,
+        phase, configState, configProblem, runtimeProblem, runtime, saved, lastActive, lastRun,
         port: runtime?.port ?? saved?.config.port ?? null, configuredPort: saved?.config.port ?? null, active, revision: saved?.revision ?? null,
         health, accessMode, lastToolCallAt, profile: instance.legacy ?? 'setup', installed: false, registered: false,
-        label: instance.name, workspaceMode: runtime?.active?.config.mode ?? saved?.config.mode ?? null,
-        writeScope: runtime?.active?.config.writeScope ?? saved?.config.writeScope ?? null, coreControl: runtime?.phase === 'running' ? 'RUNNING' : 'unavailable',
-        coreLauncher: runtime?.launcher ?? 'unknown', coreOwnerPid: runtime?.pid ?? null, listenerPid: runtime?.pid ?? null,
-        executionMode: runtime?.phase === 'running' ? (runtime.executionMode === 'background' ? 'background' : 'foreground-owned') : 'stopped', loginAutostart: 'disabled',
+        label: instance.name, workspaceMode: active?.config.mode ?? (phase === 'stopped' ? saved?.config.mode : null) ?? null,
+        writeScope: active?.config.writeScope ?? (phase === 'stopped' ? saved?.config.writeScope : null) ?? null, coreControl: runtime?.phase === 'running' ? 'RUNNING' : 'unavailable',
+        coreLauncher: runtime?.launcher ?? 'unknown', coreOwnerPid: runtime?.pid ?? null,
+        executionMode: runtime ? (runtime.executionMode === 'background' ? 'background' : 'foreground-owned') : phase === 'stopped' ? 'stopped' : 'unknown', loginAutostart: 'disabled',
         connectionState: health === 'ok' ? (lastToolCallAt ? 'local-ready-activity-recorded' : 'local-ready-remote-unverified') : health, requiredAccess: instance.requiredAccess };
 }
+export async function stopInstance(instance, home = homedir(), options = {}) {
+    const timeoutMs = options.timeoutMs ?? 65000;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0)
+        throw Error('INSTANCE_STOP_TIMEOUT_INVALID');
+    const deadline = Date.now() + timeoutMs;
+    const owner = await ownerFor(instance);
+    if (!owner || !alive(owner.pid)) {
+        const status = await instanceStatus(instance, home);
+        if (status.phase !== 'stopped')
+            throw Error(status.runtimeProblem ?? 'INSTANCE_STOP_UNVERIFIED');
+        return { result: 'ALREADY_STOPPED', instanceId: instance.id, runId: null, restarted: false };
+    }
+    await exchange(instance, owner, 'stop', undefined, Math.max(1, Math.min(2000, deadline - Date.now())));
+    const lastFile = path.join(instancePaths(instance, home).snapshots, 'last-runtime.json');
+    // The terminal snapshot is committed only after worker/lease/socket cleanup.
+    // Do not use a free port or a dead PID alone as proof of successful shutdown.
+    while (Date.now() < deadline) {
+        let current;
+        try {
+            current = await ownerFor(instance);
+        }
+        catch (e) {
+            if (e.code === 'ENOENT') {
+                await pause(25);
+                continue;
+            }
+            throw e;
+        }
+        const lastRun = await snapshot(lastFile, runtimeStateSchema);
+        if (lastRun?.runId === owner.runId && lastRun.phase === 'stopped' && current?.runId !== owner.runId) {
+            return { result: 'STOPPED', instanceId: instance.id, runId: owner.runId, restarted: current !== null };
+        }
+        if (lastRun?.runId === owner.runId && lastRun.phase === 'error')
+            throw Error('INSTANCE_STOP_FAILED: ' + lastRun.problem);
+        await pause(Math.min(50, Math.max(1, deadline - Date.now())));
+    }
+    throw Error('INSTANCE_STOP_TIMEOUT: cleanup was not confirmed; run starmux doctor');
+}
 export async function runInstance(instance, options = {}) {
     const home = options.home ?? homedir();
     const parent = options.appParentPid;
@@ -133,9 +212,10 @@ export async function runInstance(instance, options = {}) {
         throw Error('INSTANCE_ARCHIVED');
     const initial = await loadInstanceConfig(instance);
     await ensureAccessReady(await resolveInstance(instance.id, home), home);
+    const identity = await runtimeIdentity();
     const p = runtimePaths(instance.id);
     createPrivateDirectory(controlRoot());
-    const owner = { instanceId: instance.id, runId: randomBytes(16).toString('hex'), pid: process.pid, token: randomBytes(32).toString('hex'), launcher: parent ? 'app' : 'cli', appParentPid: parent ?? null };
+    const owner = { protocolVersion: INSTANCE_CONTROL_VERSION, port: initial.config.port, instanceId: instance.id, runId: randomBytes(16).toString('hex'), pid: process.pid, token: randomBytes(32).toString('hex'), launcher: parent ? 'app' : 'cli', appParentPid: parent ?? null };
     await changeRegistry(async (registry) => {
         const registered = registry.instances.find(i => i.id === instance.id);
         if (!registered || registered.archived)
@@ -165,14 +245,15 @@ export async function runInstance(instance, options = {}) {
         }
         await atomicPrivate(p.meta, JSON.stringify(owner));
     }, home);
-    const identity = await runtimeIdentity();
-    const state = { instanceId: instance.id, runId: owner.runId, pid: process.pid, launcher: owner.launcher, appParentPid: parent ?? null, executionMode: options.background ? 'background' : 'foreground', phase: 'starting', port: null, active: null, problem: null, ...identity };
+    const state = { protocolVersion: INSTANCE_CONTROL_VERSION, instanceId: instance.id, runId: owner.runId, pid: process.pid, launcher: owner.launcher, appParentPid: parent ?? null, executionMode: options.background ? 'background' : 'foreground', phase: 'starting', port: null, active: null, problem: null, ...identity };
     let worker = null;
     let portLease = null;
     let server = null;
     let ending = false;
     let expectedWorkerExit = false;
     let sequence = Promise.resolve();
+    let stopRequest = null;
+    const clients = new Set();
     let finish;
     const finished = new Promise(r => { finish = r; });
     const serialize = (fn) => { const next = sequence.then(fn); sequence = next.catch(() => { }); return next; };
@@ -189,22 +270,40 @@ export async function runInstance(instance, options = {}) {
         if (!child)
             return;
         expectedWorkerExit = true;
-        await new Promise(resolve => {
+        await new Promise((resolve, reject) => {
             if (child.exitCode !== null || child.signalCode !== null) {
                 resolve();
                 return;
             }
             let forced = false;
-            const timer = setTimeout(() => { forced = true; child.kill('SIGKILL'); }, 8000);
-            child.once('exit', () => { clearTimeout(timer); if (forced)
-                state.problem = 'WORKER_STOP_FORCED'; resolve(); });
+            const finish = (error) => { clearTimeout(grace); clearTimeout(deadline); child.off('exit', exited); child.off('error', failed); error ? reject(error) : resolve(); };
+            const exited = () => { if (forced)
+                state.problem = 'WORKER_STOP_FORCED'; finish(); };
+            const failed = (error) => finish(error);
+            const grace = setTimeout(() => { forced = true; try {
+                child.kill('SIGKILL');
+            }
+            catch (e) {
+                finish(e);
+            } }, 8000);
+            const deadline = setTimeout(() => finish(Error('INSTANCE_WORKER_STOP_TIMEOUT')), 12000);
+            child.once('exit', exited);
+            child.once('error', failed);
             if (child.connected)
-                child.send({ type: 'gateway-stop' });
+                child.send({ type: 'gateway-stop' }, error => { if (error && child.exitCode === null && child.signalCode === null)
+                    try {
+                        child.kill('SIGTERM');
+                    }
+                    catch (e) {
+                        finish(e);
+                    } });
             else
                 child.kill('SIGTERM');
         });
         worker = null;
         expectedWorkerExit = false;
+        state.active = null;
+        state.port = null;
     }
     async function shutdown(reason) {
         if (ending)
@@ -215,11 +314,24 @@ export async function runInstance(instance, options = {}) {
         await stopWorker();
         await portLease?.release();
         portLease = null;
-        state.phase = 'stopped';
         state.port = null;
-        emit('INSTANCE_STOPPED');
         finish();
     }
+    function requestStop(reason) {
+        if (!stopRequest) {
+            stopRequest = serialize(() => shutdown(reason));
+            void stopRequest.catch(async (error) => {
+                state.phase = 'error';
+                state.problem = 'INSTANCE_STOP_FAILED: ' + error.message;
+                emit('INSTANCE_ERROR');
+                try {
+                    await atomicPrivate(path.join(instancePaths(instance, home).snapshots, 'last-runtime.json'), JSON.stringify(state));
+                }
+                catch { }
+            });
+        }
+        return stopRequest;
+    }
     async function startWorker(config, lease) {
         await ensureAccessReady(await resolveInstance(instance.id, home), home);
         if (!await availablePort(config.config.port))
@@ -228,10 +340,10 @@ export async function runInstance(instance, options = {}) {
         for (const key of childEnvKeys)
             if (process.env[key])
                 env[key] = process.env[key];
-        Object.assign(env, instanceEnv(instance, config.config, home), { MAC_MCP_INTERNAL_SETUP_OWNER_PID: String(process.pid), MAC_MCP_INTERNAL_SETUP_RUN_ID: lease.owner.runId, MAC_MCP_INTERNAL_SETUP_TOKEN: lease.owner.token });
+        Object.assign(env, instanceEnv(instance, config.config, home), { STARMUX_INTERNAL_SETUP_OWNER_PID: String(process.pid), STARMUX_INTERNAL_SETUP_RUN_ID: lease.owner.runId, STARMUX_INTERNAL_SETUP_TOKEN: lease.owner.token });
         const upstreamFile = await prepareUpstreams(instance, config.config, home);
         if (upstreamFile)
-            env.MAC_MCP_UPSTREAMS_FILE = upstreamFile;
+            env.STARMUX_UPSTREAMS_FILE = upstreamFile;
         const log = path.join(instancePaths(instance, home).logs, 'core.log');
         if (await exists(log))
             await readTrusted(log, true, 32 * 1024 * 1024);
@@ -254,6 +366,7 @@ export async function runInstance(instance, options = {}) {
             child.on('message', ready);
         });
         state.active = config;
+        state.permissionMode = env.STARMUX_PERMISSION_MODE === 'global' ? 'global' : 'workspace';
         state.port = config.config.port;
         state.phase = 'running';
         lease.markRunning();
@@ -262,13 +375,13 @@ export async function runInstance(instance, options = {}) {
             state.phase = 'error';
             state.problem = 'INSTANCE_WORKER_EXITED';
             emit('INSTANCE_ERROR');
-            void serialize(() => shutdown('INSTANCE_WORKER_EXITED'));
+            void requestStop('INSTANCE_WORKER_EXITED');
         } });
         emit('INSTANCE_RUNNING');
     }
     const active = (loaded) => ({ config: loaded.config, revision: loaded.revision, effectiveRevision: loaded.effectiveRevision, sourcePath: loaded.source.path });
     async function apply(revision) {
-        if (ending)
+        if (ending || stopRequest)
             throw Error('INSTANCE_STOPPING');
         const current = await resolveInstance(instance.id, home);
         const next = await loadInstanceConfig(current);
@@ -285,7 +398,7 @@ export async function runInstance(instance, options = {}) {
             if (!await availablePort(next.config.port))
                 throw Error('PORT_IN_USE: ' + next.config.port);
             candidateLease = await acquireControl(next.config.port, { launcher: owner.launcher });
-            candidateLease.onStop(async () => { void serialize(shutdown); return 'STOPPED'; });
+            candidateLease.onStop(() => requestStop());
         }
         state.phase = 'starting';
         await stopWorker();
@@ -314,7 +427,7 @@ export async function runInstance(instance, options = {}) {
             throw Error(state.problem);
         }
     }
-    const signal = () => { void serialize(shutdown); };
+    const signal = () => { void requestStop(); };
     const parentTimer = parent ? setInterval(() => { if (process.ppid !== parent)
         signal(); }, 400) : null;
     parentTimer?.unref();
@@ -322,6 +435,8 @@ export async function runInstance(instance, options = {}) {
     process.on('SIGINT', signal);
     try {
         server = createServer({ allowHalfOpen: true }, socket => {
+            clients.add(socket);
+            socket.once('close', () => clients.delete(socket));
             socket.setTimeout(65000, () => socket.destroy());
             let raw = '';
             let handled = false;
@@ -343,21 +458,25 @@ export async function runInstance(instance, options = {}) {
                         const envelope = JSON.parse(raw);
                         if (typeof envelope.body !== 'string' || !equal(envelope.proof, signature(owner.token, envelope.body)))
                             throw Error('CONTROL_DENIED');
-                        const req = JSON.parse(envelope.body);
-                        nonce = req.nonce;
-                        if (req.runId !== owner.runId || !/^[a-f0-9]{48}$/.test(nonce))
+                        const parsed = JSON.parse(envelope.body);
+                        // Recover the nonce before validating the version so an authenticated
+                        // caller receives an explicit protocol error rather than a bad proof.
+                        if (parsed && typeof parsed === 'object' && 'nonce' in parsed && typeof parsed.nonce === 'string')
+                            nonce = parsed.nonce;
+                        checkInstanceProtocol(parsed);
+                        const req = controlRequestSchema.parse(parsed);
+                        if (req.runId !== owner.runId)
                             throw Error('CONTROL_DENIED');
-                        if (req.method === 'stop')
-                            await serialize(shutdown);
-                        else if (req.method === 'apply')
+                        if (req.method === 'apply')
                             await serialize(() => apply(req.revision));
-                        else if (req.method !== 'status')
-                            throw Error('CONTROL_INVALID_METHOD');
-                        const body = JSON.stringify({ state });
-                        socket.end(JSON.stringify({ body, proof: signature(owner.token, nonce + body) }) + '\n');
+                        const body = JSON.stringify({ protocolVersion: INSTANCE_CONTROL_VERSION, state, result: req.method === 'stop' ? 'STOP_ACCEPTED' : 'STATE' });
+                        socket.end(JSON.stringify({ body, proof: signature(owner.token, nonce + body) }) + '\n', () => {
+                            if (req.method === 'stop')
+                                void requestStop();
+                        });
                     }
                     catch (error) {
-                        const body = JSON.stringify({ state, error: error.message });
+                        const body = JSON.stringify({ protocolVersion: INSTANCE_CONTROL_VERSION, state, result: 'STATE', error: error.message });
                         socket.end(JSON.stringify({ body, proof: signature(owner.token, nonce + body) }) + '\n');
                     }
                 })();
@@ -365,7 +484,7 @@ export async function runInstance(instance, options = {}) {
         });
         await new Promise((resolve, reject) => { server.once('error', reject); server.listen(p.socket, () => resolve()); });
         portLease = await acquireControl(initial.config.port, { launcher: owner.launcher });
-        portLease.onStop(async () => { void serialize(shutdown); return 'STOPPED'; });
+        portLease.onStop(() => requestStop());
         await serialize(() => startWorker(active(initial), portLease));
         if (options.onReady)
             await options.onReady();
@@ -383,14 +502,34 @@ export async function runInstance(instance, options = {}) {
             clearInterval(parentTimer);
         process.off('SIGTERM', signal);
         process.off('SIGINT', signal);
-        await stopWorker();
-        await portLease?.release();
-        if (server)
-            await new Promise(resolve => server.close(() => resolve()));
-        await atomicPrivate(path.join(instancePaths(instance, home).snapshots, 'last-runtime.json'), JSON.stringify(state));
-        const current = await ownerFor(instance);
-        if (current?.runId === owner.runId)
-            await rm(p.root, { recursive: true, force: true });
+        try {
+            await stopWorker();
+            await portLease?.release();
+            if (server)
+                await new Promise((resolve, reject) => {
+                    const timer = setTimeout(() => { for (const client of clients)
+                        client.destroy(); }, 1500);
+                    server.close(error => { clearTimeout(timer); error ? reject(error) : resolve(); });
+                });
+            if (ending)
+                state.phase = 'stopped';
+            // Commit completion last. A stop acknowledgement only means accepted;
+            // readers require this snapshot AND release of this run's owner record.
+            await atomicPrivate(path.join(instancePaths(instance, home).snapshots, 'last-runtime.json'), JSON.stringify(state));
+            const current = await ownerFor(instance);
+            if (current?.runId === owner.runId)
+                await rm(p.root, { recursive: true, force: true });
+            if (state.phase === 'stopped')
+                emit('INSTANCE_STOPPED');
+        }
+        catch (error) {
+            state.phase = 'error';
+            state.problem = 'INSTANCE_CLEANUP_FAILED: ' + error.message;
+            try {
+                await atomicPrivate(path.join(instancePaths(instance, home).snapshots, 'last-runtime.json'), JSON.stringify(state));
+            }
+            catch { }
+            throw error;
+        }
     }
 }
-//# sourceMappingURL=instance-runtime.js.map

package/dist/src/instance-store.js

@@ -10,8 +10,10 @@ import { z } from 'zod';
 import { zodToJsonSchema } from 'zod-to-json-schema';
 import { validateConfiguredUpstreams } from './configured-mcp-upstreams.js';
 import { createPrivateDirectory, ownedByUser } from './platform.js';
-import { checkSetupValues, setupRuntimeEnv } from './release1-onboarding.js';
+import { supportedHost } from './platform.js';
+import { createProjectPolicy } from './project-workspace-policy.js';
 import { createAccessControl } from './access-control.js';
+import { createAccountAccessPolicy } from './account-access-policy.js';
 const nameSchema = z.string().trim().min(1).max(80).regex(/^[^\x00-\x1f\x7f/\\]+$/);
 const sourceSchema = z.object({ kind: z.enum(['managed', 'linked']), path: z.string() }).strict();
 export const instanceSchema = z.object({ id: z.string().uuid(), name: nameSchema, source: sourceSchema, archived: z.boolean().default(false),
@@ -118,17 +120,6 @@ export function parseConfig(text) {
         const prefix = text.slice(0, e.offset);
         throw Error(`CONFIG_JSON_INVALID line ${prefix.split('\n').length}, column ${e.offset - (prefix.lastIndexOf('\n') + 1) + 1}: ${printParseErrorCode(e.error)}`);
     }
-    // Import the three historical onboarding formats without changing their authority.
-    if (value && typeof value === 'object' && 'version' in value) {
-        const legacy = value;
-        if (![1, 2, 3].includes(Number(legacy.version)))
-            throw Error('CONFIG_VERSION_UNSUPPORTED');
-        const allowed = new Set(['version', 'projectRoot', 'mode', 'connection', 'port', 'accessRole', 'writeScope']);
-        if (Object.keys(legacy).some(k => !allowed.has(k)))
-            throw Error('CONFIG_UNKNOWN_LEGACY_FIELD');
-        value = { schemaVersion: 1, projectRoot: legacy.projectRoot, mode: legacy.mode, connection: legacy.connection, port: legacy.port,
-            accessRole: legacy.version === 1 ? 'restricted' : legacy.accessRole, writeScope: legacy.version === 3 ? 'home-only' : 'unrestricted' };
-    }
     const result = instanceConfigSchema.safeParse(value);
     if (!result.success)
         throw Error('CONFIG_INVALID: ' + result.error.issues.map(i => `${i.path.join('.') || 'config'}: ${i.message}`).join('; '));
@@ -138,8 +129,19 @@ export async function validateConfig(config) {
     const { accessRole, writeScope } = config;
     if (writeScope === 'home-only' && (accessRole !== 'trusted' || config.upstreams.length || config.gitMode !== 'off'))
         throw Error('CONFIG_INVALID writeScope: home-only requires trusted mode without extra upstreams or Gateway Git');
-    const legacy = { projectRoot: config.projectRoot, mode: config.mode, port: config.port, connection: config.connection === 'local' ? 'https' : config.connection };
-    await checkSetupValues(accessRole === 'restricted' && config.mode === 'read-write' ? { ...legacy, version: 1 } : writeScope === 'home-only' ? { ...legacy, version: 3, accessRole, writeScope } : { ...legacy, version: 2, accessRole });
+    supportedHost();
+    instanceConfigSchema.parse(config);
+    if (!path.isAbsolute(config.projectRoot))
+        throw Error('CONFIG_INVALID projectRoot: absolute path required');
+    if (accessRole === 'trusted' && config.mode !== 'read-write')
+        throw Error('CONFIG_ACCESS_ROLE_MISMATCH');
+    if (writeScope === 'home-only' && process.platform !== 'darwin')
+        throw Error('HOME_WRITE_SANDBOX_PLATFORM_UNSUPPORTED');
+    if (usesGlobalPermissions(config))
+        await createAccountAccessPolicy(config.projectRoot, config.mode);
+    else
+        await createProjectPolicy({ root: config.projectRoot, mode: config.mode,
+            developerCommands: accessRole === 'trusted' ? 'trusted-project' : 'presets', allowTrustedHomeRoot: accessRole === 'trusted' });
     validateConfiguredUpstreams({ version: 1, upstreams: config.upstreams.map(({ envRefs, ...u }) => ({ ...u, env: Object.fromEntries(Object.keys(envRefs).map(k => [k, 'reference'])) })) });
     return config;
 }
@@ -185,7 +187,7 @@ export async function createInstance(name, options = {}, home = homedir()) {
         const id = randomUUID();
         const root = path.join(instancesRoot(home), 'instances', id);
         const instance = instanceSchema.parse({ id, name, archived: false, requiredAccess: options.requiredAccess ?? 'ingress',
-            source: { kind: options.link ? 'linked' : 'managed', path: options.link ? input : path.join(root, 'config.jsonc') }, ...(options.legacy ? { legacy: options.legacy } : {}) });
+            source: { kind: options.link ? 'linked' : 'managed', path: options.link ? input : path.join(root, 'config.jsonc') } });
         createPrivateDirectory(path.join(instancesRoot(home), 'instances'));
         createPrivateDirectory(root);
         for (const dir of ['state', 'logs', 'snapshots'])
@@ -193,7 +195,7 @@ export async function createInstance(name, options = {}, home = homedir()) {
         try {
             await atomicPrivate(path.join(instancesRoot(home), 'gateway.schema.json'), JSON.stringify(configJSONSchema(), null, 2) + '\n');
             if (!options.link) {
-                const original = text && !('version' in parse(text)) ? text : configTemplate(config);
+                const original = text ?? configTemplate(config);
                 await atomicPrivate(instance.source.path, applyEdits(original, modify(original, ['$schema'], '../../gateway.schema.json', { formattingOptions: { insertSpaces: true, tabSize: 2 } })));
             }
             registry.instances.push(instance);
@@ -234,13 +236,18 @@ export async function patchInstanceConfig(instance, patch, revision, home = home
         text = applyEdits(text, modify(text, [key], value, { formattingOptions: { insertSpaces: true, tabSize: 2 } }));
     return saveInstanceConfig(instance, text, revision, home);
 }
+export function usesGlobalPermissions(config) {
+    return config.writeScope === 'unrestricted' &&
+        (config.accessRole === 'restricted' && config.mode === 'read-only' || config.accessRole === 'trusted' && config.mode === 'read-write');
+}
 export function instanceEnv(instance, config, home = homedir()) {
-    const legacy = { projectRoot: config.projectRoot, mode: config.mode, port: config.port, connection: config.connection === 'local' ? 'https' : config.connection,
-        ...(config.accessRole === 'restricted' && config.mode === 'read-write' ? { version: 1 } : config.writeScope === 'home-only' ? { version: 3, accessRole: config.accessRole, writeScope: 'home-only' } : { version: 2, accessRole: config.accessRole }) };
     const p = instancePaths(instance, home);
-    return { ...setupRuntimeEnv(legacy), MAC_MCP_ACCESS_FILE: p.access, MAC_MCP_GRANTS_FILE: p.grants, MAC_MCP_DENY_FILE: p.deny,
-        MAC_MCP_GIT_MODE: config.gitMode, MAC_MCP_WORKTREE_MODE: config.worktreeMode, MAC_MCP_INSTANCE_ID: instance.id, MAC_MCP_INSTANCE_NAME: instance.name,
-        MAC_MCP_PRIVATE_ACTIVITY_OBSERVER: '1' };
+    return { STARMUX_PROJECT_ROOT: config.projectRoot, STARMUX_PROJECT_PORT: String(config.port),
+        STARMUX_WORKSPACE_MODE: config.mode, STARMUX_DEV_COMMANDS: config.accessRole === 'trusted' ? 'trusted-project' : 'presets',
+        STARMUX_DC_ACCESS_MODE: config.accessRole === 'trusted' ? 'native' : 'workspace', STARMUX_DC_WRITE_SCOPE: config.writeScope,
+        STARMUX_ACCESS_FILE: p.access, STARMUX_GRANTS_FILE: p.grants, STARMUX_DENY_FILE: p.deny,
+        STARMUX_GIT_MODE: config.gitMode, STARMUX_WORKTREE_MODE: config.worktreeMode, STARMUX_INSTANCE_ID: instance.id, STARMUX_INSTANCE_NAME: instance.name,
+        STARMUX_PRIVATE_ACTIVITY_OBSERVER: '1', STARMUX_PERMISSION_MODE: usesGlobalPermissions(config) ? 'global' : 'workspace' };
 }
 export async function ensureAccessReady(instance, home = homedir()) {
     const access = await createAccessControl(instancePaths(instance, home).access);
@@ -266,4 +273,3 @@ export async function prepareUpstreams(instance, config, home = homedir()) {
     await atomicPrivate(file, JSON.stringify({ version: 1, upstreams: definitions }));
     return file;
 }
-//# sourceMappingURL=instance-store.js.map

package/dist/src/instance-worker.js

@@ -2,8 +2,7 @@ import { verifyInternalSetupWorker } from './global-core-control.js';
 import { runGateway } from './dc-workspace-http.js';
 if (!process.send)
     throw Error('INSTANCE_WORKER_REQUIRES_SUPERVISOR');
-verifyInternalSetupWorker({ port: Number(process.env.MAC_MCP_PROJECT_PORT), ownerPid: Number(process.env.MAC_MCP_INTERNAL_SETUP_OWNER_PID),
-    runId: process.env.MAC_MCP_INTERNAL_SETUP_RUN_ID, token: process.env.MAC_MCP_INTERNAL_SETUP_TOKEN });
+verifyInternalSetupWorker({ port: Number(process.env.STARMUX_PROJECT_PORT), ownerPid: Number(process.env.STARMUX_INTERNAL_SETUP_OWNER_PID),
+    runId: process.env.STARMUX_INTERNAL_SETUP_RUN_ID, token: process.env.STARMUX_INTERNAL_SETUP_TOKEN });
 await runGateway();
 process.send({ type: 'gateway-ready' });
-//# sourceMappingURL=instance-worker.js.map

package/dist/src/invocation.js

@@ -61,7 +61,7 @@ export function createInvocationPipeline(options) {
         catch (error) {
             const reason = errorCode(error) || 'DENY_RULE_CHECK_FAILED';
             audit({ event: 'TOOL_EXPLICITLY_DENIED', requestId: request.requestId, tool: invocation.name, reason });
-            return { isError: true, content: [{ type: 'text', text: reason + ': Review filters on the Mac owner Dashboard /filters' }] };
+            return { isError: true, content: [{ type: 'text', text: reason + ': Review filters on the local owner Dashboard /filters' }] };
         }
         const result = await options.dispatch(invocation, request);
         for (const hook of hooks) {
@@ -77,4 +77,3 @@ export function createInvocationPipeline(options) {
         return result; // original MCP result, including unknown extension fields
     };
 }
-//# sourceMappingURL=invocation.js.map