starmux 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## 0.15.0
+
+### Instance lifecycle
+
+- Version and validate the local instance control protocol independently of package releases.
+- Report `unknown` when control records or channels cannot establish the instance's state; do not mistake a missing control channel for a stopped service.
+- Confirm cleanup before `down` reports success. Repeated stops report `Already stopped`; failed or timed-out cleanup returns a nonzero exit code.
+- Use the same stop confirmation for instance archival and protect successor runs during concurrent operations.
+- Separate confirmed active configuration, saved settings and historical snapshots in CLI and JSON output.
+- Prevent `up` from changing permissions in an unknown state, prevent `doctor` from passing unresolved runtime errors, and show unknown states in the macOS App.
+- Add isolated lifecycle and real CLI regression tests, validated on macOS and NVIDIA NX Linux ARM64.
+
+### Upgrade
+
+Stop each running instance with the currently installed CLI before upgrading, then start it again with the new CLI. This release introduces a versioned instance control contract and does not migrate old runtime directories or support the previous unversioned contract. Replacing installed files does not update an already-running supervisor.
+
+```sh
+starmux ls
+starmux down                 # Default instance
+starmux down -i NAME         # Repeat for other running instances
+npm install -g starmux@0.15.0
+starmux up
+```
+
+Proceed with installation only after stopping succeeds. If the current CLI cannot contact its supervisor, resolve that runtime problem first; a port conflict is not proof of successful shutdown.

package/README.md

@@ -39,6 +39,8 @@ Requires **Node.js 22.12+**.
 npm install -g starmux
 ```
 
+**Upgrading an existing installation?** Stop each running instance with the current CLI (`starmux down`, or `starmux down -i NAME`) before installing the new version, then run `starmux up` again. See the [upgrade instructions](https://github.com/cookyecat/starmux/blob/main/docs/INSTALL.md#upgrade) and [release notes](https://github.com/cookyecat/starmux/blob/main/CHANGELOG.md).
+
 ### 2. Start in your project directory
 
 ```bash

package/dist/src/cli/instances.js

@@ -6,7 +6,7 @@ import { createAccessControl } from '../access-control.js';
 import { createWorkspaceGrants } from '../workspace-grants.js';
 import { createDenyRules } from '../explicit-deny-rules.js';
 import { createPrivateDirectory } from '../platform.js';
-import { instanceStatus, instanceRequest } from '../instance-runtime.js';
+import { instanceStatus, instanceRequest, stopInstance } from '../instance-runtime.js';
 import { atomicPrivate, changeRegistry, configJSONSchema, sourceRevision, configTemplate, validateConfig, withLock, createInstance, exists, fingerprint, instancePaths, loadInstanceConfig, parseConfig, patchInstanceConfig, readRegistry, readTrusted, resolveInstance, saveInstanceConfig, suggestPort } from '../instance-store.js';
 const booleans = new Set(['--json', '--all', '--link', '--archived', '--approve-trusted-developer', '--approve-unrestricted', '--effective', '--allow-loopback-http']);
 function options(args) {
@@ -65,16 +65,17 @@ export async function handle(command, args) {
                         : 'No instances. Run: starmux up\n');
                     return;
                 }
-                const rows = await Promise.all(instances.map(async (s, idx) => {
-                    const raw = filtered[idx];
-                    const cfg = s.active?.config ?? (await loadInstanceConfig(raw).catch(() => null))?.config;
+                const rows = instances.map(s => {
+                    const cfg = s.phase === 'stopped' ? s.saved?.config : s.active?.config;
+                    const saved = s.saved?.config;
                     const mark = s.instanceId === registry.defaultInstanceId ? '*' : ' ';
                     const state = s.archived ? 'archived' : s.configState === 'pending' ? `${s.phase} (pending)` : s.phase;
-                    const mode = cfg?.accessRole === 'trusted' ? 'coding' : (s.workspaceMode ?? 'read-only');
+                    const describe = (value) => !value ? 'unavailable' : value.accessRole === 'trusted' ? 'coding' : value.mode;
+                    const mode = s.phase === 'stopped' ? `${describe(saved)} (saved)` : s.phase === 'unknown' ? `unavailable / ${describe(saved)} (saved)` : s.configState === 'pending' ? `${describe(cfg)} / ${describe(saved)} (saved)` : describe(cfg);
                     const port = String(s.port ?? '—');
-                    const workspace = cfg?.projectRoot ?? s.source.path;
+                    const workspace = cfg?.projectRoot ?? (saved ? `${saved.projectRoot} (saved)` : s.source.path);
                     return { mark, name: s.name, state, mode, port, workspace };
-                }));
+                });
                 const wName = Math.max(4, ...rows.map(r => r.name.length));
                 const wState = Math.max(6, ...rows.map(r => r.state.length));
                 const wMode = Math.max(4, ...rows.map(r => r.mode.length));
@@ -121,9 +122,9 @@ export async function handle(command, args) {
             else if (op === 'default')
                 registry.defaultInstanceId = item.id;
             else if (op === 'archive' || op === 'remove') {
-                const stopped = await instanceRequest(instance, 'stop');
-                if (stopped && stopped.phase !== 'stopped')
-                    throw Error('INSTANCE_STILL_RUNNING');
+                const stopped = await stopInstance(instance);
+                if (stopped.restarted)
+                    throw Error('INSTANCE_RESTARTED: cannot archive a new running instance');
                 item.archived = true;
                 if (registry.defaultInstanceId === item.id)
                     registry.defaultInstanceId = null;
@@ -163,11 +164,12 @@ export async function handle(command, args) {
         }
         if (op === 'show') {
             if (flags.has('--effective')) {
-                const active = (await instanceStatus(instance)).active;
+                const status = await instanceStatus(instance);
+                const active = status.active;
                 if (json)
                     output(active);
                 else if (!active)
-                    process.stdout.write(`Instance ${instance.name} has no active running configuration.\n`);
+                    process.stdout.write(`Instance ${instance.name} has no confirmed active configuration (state: ${status.phase}).\n`);
                 else
                     process.stdout.write(`Instance       ${instance.name} (effective running config)\n` +
                         `Workspace      ${active.config.projectRoot}\n` +
@@ -205,7 +207,7 @@ export async function handle(command, args) {
             return;
         }
         if (op === 'recover') {
-            const snapshot = (await instanceStatus(instance)).active;
+            const snapshot = (await instanceStatus(instance)).lastActive;
             if (!snapshot)
                 throw Error('NO_SUCCESSFUL_CONFIG_SNAPSHOT');
             await validateConfig(snapshot.config);
@@ -291,7 +293,14 @@ export async function handle(command, args) {
             return;
         }
         if (op === 'apply') {
+            const before = await instanceStatus(instance);
+            if (before.phase !== 'running' && before.phase !== 'stopped')
+                throw Error(`INSTANCE_NOT_READY: ${before.runtimeProblem ?? before.phase}`);
             const state = await instanceRequest(instance, 'apply', flags.get('--revision') ?? loaded.revision);
+            if (state && state.phase !== 'running')
+                throw Error('INSTANCE_APPLY_UNVERIFIED');
+            if (!state && before.phase === 'running')
+                throw Error('INSTANCE_CHANGED_DURING_APPLY');
             if (json)
                 output({ result: state ? 'APPLIED' : 'VALID_ON_NEXT_START', instanceId: instance.id, runtime: state });
             else

package/dist/src/cli/starmux-status.js

@@ -23,9 +23,8 @@ async function authentication(instance, status) {
     }
 }
 export async function formatStarmuxStatus(instance, status, config, options = {}) {
-    // Pending edits must never be shown as permissions of the running instance.
-    if (status.phase === 'running')
-        config = status.active?.config;
+    // Only the live supervisor can confirm active permissions.
+    config = status.phase === 'stopped' ? status.saved?.config : status.active?.config;
     const auth = await authentication(instance, status);
     // Omit `-i default` for the default instance to keep everyday single-instance output clean.
     const omitSelector = options.isDefault === true && instance.name === 'default';
@@ -40,23 +39,35 @@ export async function formatStarmuxStatus(instance, status, config, options = {}
         'api-key': `API key (Bearer token; ${auth.activeKeys} active ${auth.activeKeys === 1 ? 'key' : 'keys'})`,
         oauth: 'OAuth (browser sign-in)'
     };
-    const saved = status.phase === 'running' ? ' (saved; live state unavailable)' : ' (saved for next start)';
+    const saved = status.phase === 'stopped' ? ' (saved for next start)' : ' (saved; live state unavailable)';
     const row = (label, value) => '  ' + label.padEnd(16) + value;
     const codingCmd = command('up --code');
     const globalMode = status.phase === 'running' ? status.runtime?.permissionMode === 'global' : !!config && usesGlobalPermissions(config);
-    const mode = !config
+    const describeMode = (value, global) => !value
         ? 'Unavailable'
-        : config.accessRole === 'trusted'
-            ? `${config.writeScope === 'home-only' ? 'Coding (Home sandbox · edits, shell & git)' : 'Coding (OS account · edits, shell & git)'}  (run '${command('up --read')}' to return to read-only)`
-            : config.mode === 'read-write'
+        : value.accessRole === 'trusted'
+            ? value.writeScope === 'home-only' ? 'Coding (Home sandbox · edits, shell & git)' : 'Coding (OS account · edits, shell & git)'
+            : value.mode === 'read-write'
                 ? 'File writes (restricted)'
-                : `Read-only (${globalMode ? 'global · OS account' : 'project scope'})  (run '${codingCmd}' to enable edits & shell)`;
+                : `Read-only (${global ? 'global · OS account' : 'project scope'})`;
+    const switchHint = config && (status.phase === 'running' || status.phase === 'stopped')
+        ? config.accessRole === 'trusted' ? `  (run '${command('up --read')}' to return to read-only)` : `  (run '${codingCmd}' to enable edits & shell)`
+        : '';
+    const mode = describeMode(config, globalMode) + switchHint;
     const title = `${indicator} Starmux is ${status.phase}  (instance: ${instance.name})`;
     const lines = ['', title, row('Instance', instance.id)];
     if (ready && status.port) {
         lines.push(row('Listen', `http://127.0.0.1:${status.port}/mcp  (this computer only)`));
     }
-    lines.push(row('Project', config?.projectRoot ?? 'Unavailable'), row('Mode', mode), row('Auth', auth.mode ? labels[auth.mode] + (ready ? '' : saved) : 'Unavailable'));
+    lines.push(row(status.phase === 'stopped' ? 'Saved project' : 'Project', config?.projectRoot ?? 'Unavailable'), row(status.phase === 'stopped' ? 'Saved mode' : status.phase === 'unknown' || status.configState === 'pending' ? 'Active mode' : 'Mode', mode), row('Auth', auth.mode ? labels[auth.mode] + (ready ? '' : saved) : 'Unavailable'));
+    if (status.phase !== 'stopped' && (status.configState === 'pending' || !status.active)) {
+        const savedConfig = status.saved?.config;
+        lines.push(row('Saved mode', describeMode(savedConfig, !!savedConfig && usesGlobalPermissions(savedConfig)) + (status.configState === 'pending' ? ' (pending)' : '')));
+        if (!status.active)
+            lines.push(row('Saved project', savedConfig?.projectRoot ?? 'Unavailable'));
+    }
+    if (status.runtime)
+        lines.push(row('Runtime', status.runtime.buildVersion));
     if (ready && status.port && auth.mode === 'oauth' && auth.oauth) {
         lines.push(row('Client URL', auth.oauth.resource), row('Issuer', auth.oauth.issuer));
     }

package/dist/src/cli/starmux.js

@@ -8,7 +8,7 @@ import { fileURLToPath } from 'node:url';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
 import { createAccessControl } from '../access-control.js';
-import { instanceStatus, instanceRequest, runInstance } from '../instance-runtime.js';
+import { instanceStatus, instanceRequest, stopInstance, runInstance } from '../instance-runtime.js';
 import { atomicPrivate, availablePort, changeRegistry, configJSONSchema, createInstance, ensureAccessReady, exists, instanceConfigSchema, instancePaths, loadInstanceConfig, parseConfig, patchInstanceConfig, readRegistry, readTrusted, resolveInstance, saveInstanceConfig, suggestPort, validateConfig, usesGlobalPermissions } from '../instance-store.js';
 import { handle } from './instances.js';
 import { packageRoot, desktopCommanderEntry } from '../runtime-paths.js';
@@ -125,6 +125,11 @@ async function configure() {
         instance = await resolveInstance();
     if (instance?.archived)
         fail('Instance is archived. Use starmux config restore -i ' + instance.name);
+    if (command === 'up' && instance) {
+        const state = await instanceStatus(instance);
+        if (state.phase !== 'running' && state.phase !== 'stopped')
+            fail(`Cannot start ${instance.name}: ${state.runtimeProblem ?? state.phase}. Run starmux doctor -i ${instance.id}.`);
+    }
     const loaded = instance ? await loadInstanceConfig(instance) : undefined;
     const writing = flags.write || flags.code;
     if (flags.read && writing)
@@ -160,21 +165,29 @@ async function show(instance) {
         print(status);
         return;
     }
-    const config = status.phase === 'running' ? status.active?.config : (await loadInstanceConfig(instance).catch(() => null))?.config;
+    const config = status.phase === 'stopped' ? status.saved?.config : status.active?.config;
     process.stdout.write(await formatStarmuxStatus(instance, status, config, { isDefault: await isDefaultInstance(instance) }));
 }
 async function start(instance) {
     const state = await instanceStatus(instance);
     if (state.phase === 'running') {
-        if (state.configState === 'pending')
-            await instanceRequest(instance, 'apply', (await loadInstanceConfig(instance)).revision);
+        if (state.configState === 'pending') {
+            const applied = await instanceRequest(instance, 'apply', (await loadInstanceConfig(instance)).revision);
+            if (!applied || applied.phase !== 'running')
+                fail('Configuration was not applied: instance changed while starting. Run starmux status.');
+        }
+        const current = await instanceStatus(instance);
+        if (current.phase !== 'running' || current.health !== 'ok')
+            fail(`Instance is not ready: ${current.runtimeProblem ?? current.health}. Run starmux doctor -i ${instance.id}.`);
         await show(instance);
         return;
     }
+    if (state.phase !== 'stopped')
+        fail(`Cannot start ${instance.name}: ${state.runtimeProblem ?? state.phase}. Run starmux doctor -i ${instance.id}.`);
     await ensureAccessReady(instance);
     const config = (await loadInstanceConfig(instance)).config;
     if (!await availablePort(config.port))
-        fail(`Port ${config.port} is in use. Choose another with starmux up --port PORT.`);
+        fail(`Port ${config.port} is in use. Inspect starmux doctor -i ${instance.id} before changing the port.`);
     if (flags.foreground || string('app-parent-pid')) {
         await runInstance(instance, { json, ...(!json ? { onReady: () => show(instance) } : {}), ...(string('app-parent-pid') ? { appParentPid: Number(string('app-parent-pid')) } : {}) });
         return;
@@ -645,11 +658,13 @@ async function main() {
     if (command === 'status')
         await show(instance);
     else if (command === 'down' || command === 'stop') {
-        await instanceRequest(instance, 'stop');
+        const result = await stopInstance(instance);
         if (json)
-            print({ result: 'STOPPED', instanceId: instance.id });
+            print(result);
+        else if (result.restarted)
+            process.stdout.write(`Stopped the previous run of ${instance.name}; another command has started a new run.\n`);
         else
-            process.stdout.write('Stopped ' + instance.name + '\n');
+            process.stdout.write(`${result.result === 'ALREADY_STOPPED' ? 'Already stopped' : 'Stopped'} ${instance.name}\n`);
     }
     else if (command === 'auth')
         await auth(instance);
@@ -662,23 +677,30 @@ async function main() {
     else if (command === 'doctor') {
         if (Number(process.versions.node.split('.')[0]) < 22 || (process.versions.node.startsWith('22.') && Number(process.versions.node.split('.')[1]) < 12))
             fail('Node 22.12 or newer is required.');
+        const state = await instanceStatus(instance);
+        if (state.configProblem || state.runtimeProblem || state.runtime?.problem)
+            fail(state.configProblem ?? state.runtimeProblem ?? state.runtime.problem);
+        if (state.phase !== 'running' && state.phase !== 'stopped')
+            fail('Instance state is ' + state.phase + '. Inspect starmux logs -i ' + instance.id);
+        if (state.phase === 'running' && state.health !== 'ok')
+            fail('Instance health is ' + state.health + '. Inspect starmux logs -i ' + instance.id);
         await stat(desktopCommanderEntry);
         const loaded = await loadInstanceConfig(instance);
         await ensureAccessReady(instance);
-        const state = await instanceStatus(instance);
-        if (state.phase !== 'running' && !await availablePort(loaded.config.port))
+        if (state.phase === 'stopped' && !await availablePort(loaded.config.port))
             fail('Configured port is in use: ' + loaded.config.port);
         if (json)
             print({ result: 'PASS', node: process.version, instanceId: instance.id, configState: state.configState });
         else {
             const isDef = await isDefaultInstance(instance);
             const access = await (await createAccessControl(instancePaths(instance).access, { initialize: false })).snapshot();
-            const modeLabel = loaded.config.accessRole === 'trusted' ? 'Coding mode' : 'Read-only mode';
+            const effective = state.phase === 'running' ? state.active?.config : loaded.config;
+            const modeLabel = !effective ? 'Mode unavailable' : effective.accessRole === 'trusted' ? 'Coding mode' : effective.mode === 'read-write' ? 'File writes' : 'Read-only mode';
             const authLabel = access.mode === 'ingress' ? 'None (no token required)' : access.mode === 'api-key' ? `API key (${access.credentials.filter(c => c.status === 'active').length} active)` : 'OAuth';
             const portState = state.phase === 'running' ? `Running on 127.0.0.1:${state.port}` : `Stopped · port ${loaded.config.port} available`;
             process.stdout.write(`✓ Runtime            Node ${process.version} & Desktop Commander engine ready\n` +
                 `✓ Service            ${portState}${isDef ? '' : ` (instance: ${instance.name})`}\n` +
-                `✓ Workspace          ${loaded.config.projectRoot} (${modeLabel})\n` +
+                `✓ Workspace          ${effective?.projectRoot ?? 'Unavailable'} (${modeLabel})\n` +
                 `✓ Configuration      ${instance.source.path} (${state.configState})\n` +
                 `✓ Authentication     ${authLabel}\n` +
                 `PASS · Node, dependencies, workspace, configuration, port and authentication.\n`);

package/dist/src/config-schemas.js

@@ -2,4 +2,4 @@ import { z } from 'zod';
 export const grantsSchema = z.object({ version: z.literal(1), homeRead: z.boolean(), outsideRead: z.boolean(), custom: z.array(z.object({ path: z.string(), mode: z.enum(['read-only', 'read-write']) }).strict()) }).strict();
 export const denySchema = z.object({ version: z.literal(1), deniedTools: z.array(z.string()), deniedDirectories: z.array(z.string()) }).strict();
 export const upstreamDefinitionSchema = z.object({ id: z.string(), transport: z.literal('stdio'), command: z.string(), args: z.array(z.string()), env: z.record(z.string()).optional(), allowTools: z.array(z.string()) }).strict();
-export const ownerSchema = z.object({ port: z.number().int(), pid: z.number().int().min(2), token: z.string().regex(/^[a-f0-9]{48}$/), launcher: z.enum(['cli', 'app']), runId: z.string().regex(/^[a-f0-9]{32}$/) }).passthrough();
+export const ownerSchema = z.object({ version: z.literal(1), port: z.number().int(), pid: z.number().int().min(2), token: z.string().regex(/^[a-f0-9]{48}$/), launcher: z.enum(['cli', 'app']), runId: z.string().regex(/^[a-f0-9]{32}$/) }).passthrough();

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";
@@ -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,36 +351,39 @@ 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);
+            })();
         }
     };
 }

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');
+}

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))
@@ -263,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);
@@ -286,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();
@@ -315,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();
@@ -323,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;
@@ -344,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');
                     }
                 })();
@@ -366,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();
@@ -384,13 +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;
+        }
     }
 }

package/dist/src/platform.js

@@ -59,6 +59,9 @@ export function createPrivateDirectory(folder) {
         throw Error('PRIVATE_DIRECTORY_UNSAFE');
 }
 export function controlRoot() {
+    // Local control address contract: keep independent of the package version,
+    // install path, project directory and display name. A branding edit must not
+    // silently move the rendezvous point of an already-running supervisor.
     if (process.platform === 'darwin')
         return `/private/tmp/starmux-${process.getuid()}`;
     const id = windows ? createHash('sha256').update(homedir().toLowerCase()).digest('hex').slice(0, 16) : String(process.getuid());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "starmux",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Connect AI clients to files, terminals and development tools on your own computer.",
   "license": "MIT",
   "homepage": "https://github.com/cookyecat/starmux#readme",
@@ -31,6 +31,7 @@
     "status": "node bin/starmux.mjs status",
     "build": "node scripts/build.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "tsc -p tsconfig.json && node --test tests/*.test.mjs",
     "prepare": "node scripts/prepare.mjs",
     "prepack": "npm run build",
     "sync:upstream": "npm install --save-dev --save-exact @wonderwhy-er/desktop-commander@latest --ignore-scripts && npm run build"
@@ -63,6 +64,7 @@
     "bin/starmux.mjs",
     "scripts/prepare.mjs",
     "LICENSE",
+    "CHANGELOG.md",
     "README.md"
   ]
 }