starmux 0.13.1 → 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/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Mac MCP Gateway contributors
+Copyright (c) 2026 Starmux contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -24,7 +24,7 @@ Cloud AI assistants (like **ChatGPT Web**, **Claude**, **Codex**, or **WorkBuddy
 
 - **Batteries-Included Workspace Tools:** Powered by a built-in [Desktop Commander](https://github.com/wonderwhy-er/DesktopCommanderMCP) engine (installed automatically via npm). Out of the box, your AI can read/write files, search code, run Shell commands, and manage Git.
 - **Code on Any Host (macOS, Linux, Windows & Edge Devices):** Many AI clients (like **ChatGPT Desktop** or **WorkBuddy**) have no native Linux or ARM64 client. Because Starmux runs anywhere **Node.js 22.12+** runs—including **macOS**, **Linux (`x64` / `arm64`)**, **NVIDIA Jetson**, headless servers, and **Windows**—you can use your favorite AI client on your main computer or browser to develop directly on any target machine.
-- **Safe by Default:** Starts in strict **Read-Only** mode (`starmux up`). Explicitly opt into **Coding Mode** (`starmux up --code`) only when you want AI to edit files or run terminal commands.
+- **Two Clear Permission Modes:** Starts in global **Read-Only** mode (`starmux up`): AI can read files your OS account and the upstream server permit, while writes and arbitrary execution are blocked. Explicitly opt into **Coding Mode** (`starmux up --code`) to use native tools with your OS account permissions.
 - **Your Network, Your Keys:** No vendor-hosted relay required. Protect your gateway with Bearer **API Keys**, browser-based **OAuth**, or your existing **Tunnel / Reverse Proxy** access controls. Revoke access instantly at any time.
 
 ---
@@ -39,12 +39,14 @@ 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
 cd /path/to/your/project
 
-# Option A: Safe read-only mode (default — inspect files & code)
+# Option A: Global read-only mode (default — inspect files & code)
 starmux up
 
 # Option B: Full coding mode (edit files, run Shell & Git)
@@ -53,28 +55,18 @@ starmux up --code
 
 Starmux initializes itself and runs in the background on port `18893` (coding mode asks for confirmation the first time):
 
-```text
-● Starmux is running
-  Listen          http://127.0.0.1:18893/mcp  (this computer only)
-  Workspace       /path/to/your/project
-  Mode            Read-only  (run 'starmux up --code' to enable edits & shell)
-  Auth            None (no token required)
-  Runtime         Background · continues after this terminal closes
-
-Connect an AI client (MCP settings)
-  Transport       Streamable HTTP
-  URL (Local)     http://127.0.0.1:18893/mcp  (AI client on this computer)
-  URL (Remote)    https://<your-domain-or-tunnel>/mcp  (via protected HTTPS proxy or tunnel -> 127.0.0.1:18893)
-  Authentication  None  (optional Bearer API key: starmux auth key "My AI Client")
-
-Commands
-  Verify          starmux verify
-  Auth & keys     starmux auth
-  Dashboard       starmux dashboard  (view & copy settings in browser)
-  Logs            starmux logs -f
-  Stop            starmux down
+Switch back from Coding mode with
+
+```
+starmux up --read
 ```
 
+Add `-i NAME` for a named instance. Both `up` and `status` show the mode-switch command.
+
+`Project` provides context for relative file paths in Read-only mode; it does not restrict access to that directory. Read-only applies across the computer wherever the OS account and upstream server permit reading. Coding forwards native operations with the account's permissions. Neither mode uses Starmux directory grants or path exclusions.
+
+In Read-only mode, `read_multiple_files` supports up to 20 files and 4 MiB of combined file sizes per batch. Missing files retain Desktop Commander's per-file errors alongside successful contents. Oversized batches return `BATCH_READ_COUNT_LIMIT` or `BATCH_READ_SIZE_LIMIT` with guidance to split the request.
+
 ### 3. Add Starmux to your AI client
 
 Need a Bearer API key for remote access? Generate one first (optional for local use):
@@ -176,7 +168,7 @@ See [Client Compatibility](docs/CLIENTS.md) and [Remote Setup](docs/REMOTE_SETUP
 
 ---
 
-## Everyday CLI & Multi-Workspace
+## Everyday CLI & Multiple Instances
 
 Manage your gateway with simple, human-friendly commands:
 
@@ -190,11 +182,11 @@ starmux logs -f         # Stream live gateway logs
 starmux down            # Stop the gateway (alias: stop)
 ```
 
-After initialization, `starmux up` reuses your saved workspace. Use `starmux up .` to switch it to your current directory, or pass `--foreground` to keep the process in your terminal.
+After initialization, `starmux up` reuses your instance's saved project context. Use `starmux up .` to change it to your current directory, or pass `--foreground` to keep the process in your terminal. Only a new instance defaults to the current directory when no path is supplied.
 
-### Advanced: Running multiple workspaces (`-i`)
+### Advanced: Running multiple instances (`-i`)
 
-*(Optional)* By default, Starmux manages a single `default` workspace so you never have to pass extra flags. When you need to expose multiple projects simultaneously or run different permission modes on the same machine, pass `-i <name>` to create isolated instances with their own ports, credentials, policies, and logs:
+*(Optional)* By default, Starmux manages a single `default` instance so you never have to pass extra flags. To use different project contexts or permission modes on the same machine, pass `-i <name>` to create instances with their own ports, credentials, configuration, and logs. Instances share the OS account; they are not filesystem sandboxes:
 
 ```bash
 starmux up ~/work/repo-a -i work --code
@@ -238,8 +230,8 @@ Explore the `docs/` guides by topic:
   - [Access Control & API Keys](docs/ACCESS_CONTROL.md) — Creating/revoking Bearer API keys, expiration policies, and using the local Web Access Console.
   - [ChatGPT Web & OAuth 2.0](docs/OAUTH.md) & [Connect ChatGPT](docs/CONNECT_CHATGPT.md) — Configuring Keycloak OAuth 2.0 + PKCE and OpenAI Secure MCP Tunnel.
 - **⚙️ Advanced Configuration & Security**
-  - [Multi-Instance & JSONC Config](docs/INSTANCES.md) — Managing multiple isolated workspaces, hot-reloading `config.jsonc`, mounting extra `stdio` MCP upstreams, and secrets.
-  - [Security & Workspace Permissions](docs/SECURITY.md) — Understanding Read-Only vs. Coding Mode, directory grants, tool deny rules, and macOS privacy boundaries.
+  - [Multi-Instance & JSONC Config](docs/INSTANCES.md) — Managing instances, hot-reloading `config.jsonc`, mounting extra `stdio` MCP upstreams, and secrets.
+  - [Security & Permissions](docs/SECURITY.md) — Understanding global Read-Only vs. Coding Mode, upstream permissions, and macOS privacy boundaries.
   - [Client Compatibility](docs/CLIENTS.md) & [Platform Details](docs/PLATFORMS.md) — Tested AI client matrix and macOS / Linux / Windows runtime specifics.
 - **🛠️ Reference & Project**
   - [Documentation Index](docs/README.md) · [Installation](docs/INSTALL.md) · [Contributing](CONTRIBUTING.md)

package/dist/src/access-control.js

@@ -12,7 +12,7 @@ const schema = z.object({ version: z.literal(1), mode: z.enum(['ingress', 'api-k
     oauth: oauthConfigSchema.optional(), oauthConnections: z.array(oauthConnectionSchema).max(512).default([]) }).strict();
 const digest = (value) => createHash('sha256').update(value).digest('hex');
 const equal = (a, b) => a.length === b.length && timingSafeEqual(Buffer.from(a), Buffer.from(b));
-export const defaultAccessFile = () => process.env.MAC_MCP_ACCESS_FILE || path.join(homedir(), '.config', 'starmux', 'access-v1.json');
+export const defaultAccessFile = () => process.env.STARMUX_ACCESS_FILE || path.join(homedir(), '.config', 'starmux', 'access-v1.json');
 const active = (c) => !c.revokedAt && (!c.expiresAt || Date.parse(c.expiresAt) > Date.now());
 export async function createAccessControl(file = defaultAccessFile(), options = {}) {
     if (!path.isAbsolute(file))
@@ -222,4 +222,3 @@ export async function createAccessControl(file = defaultAccessFile(), options =
     }
     return { file, snapshot, create, setMode, revoke, authenticate, ownerToken, authorized, configureOAuth, revokeOAuth, oauthSettings };
 }
-//# sourceMappingURL=access-control.js.map

package/dist/src/access-dashboard.js

@@ -8,8 +8,8 @@ const e = (s) => String(s ?? '').replace(/[&<>"']/g, c => ({ '&': '&amp;', '<':
 export function accessPage(state, created) {
     const form = (op, fields, label) => `<form method="post" action="/access"><input type="hidden" name="op" value="${op}">${fields}<label>Owner management token <input type="password" name="token" required autocomplete="off"></label><button>${label}</button></form>`;
     return `<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>Starmux · Access Control</title><style>body{font:16px system-ui;max-width:960px;margin:40px auto;padding:0 24px;background:#f5f7fa;color:#243249}section{background:white;border:1px solid #dae0e8;border-radius:12px;padding:24px;margin:20px 0}input,select,button{font:inherit;padding:8px;margin:8px}label{display:block}code{overflow-wrap:anywhere}td,th{text-align:left;padding:10px;border-bottom:1px solid #ddd}table{width:100%}</style><h1>Starmux · Access Control</h1>
-  <p><a href="/dashboard">Dashboard</a> · <a href="/permissions">Workspace permissions</a></p>
-  <section><h2>${state.mode === 'ingress' ? 'None (local or ingress-managed)' : state.mode === 'oauth' ? 'OAuth' : 'Bearer API Key'}</h2><p>Permission: Owner default. Credentials do not change workspace, tool or operating-system permissions.</p><p>${state.mode === 'ingress' ? 'Starmux does not verify a token. Restrict remote access through your HTTPS proxy or tunnel.' : 'Every MCP request requires an active credential. Missing, invalid, expired or revoked credentials are rejected.'}</p>
+  <p><a href="/dashboard">Dashboard</a></p>
+  <section><h2>${state.mode === 'ingress' ? 'None (local or ingress-managed)' : state.mode === 'oauth' ? 'OAuth' : 'Bearer API Key'}</h2><p>Credentials do not change the instance’s mode or operating-system permissions.</p><p>${state.mode === 'ingress' ? 'Starmux does not verify a token. Restrict remote access through your HTTPS proxy or tunnel.' : 'Every MCP request requires an active credential. Missing, invalid, expired or revoked credentials are rejected.'}</p>
   <table><tr><th>MCP Client Field</th><th>Value to Copy</th></tr>
   <tr><td>Transport</td><td><code>Streamable HTTP</code></td></tr>
   <tr><td>URL (Local)</td><td><code>http://127.0.0.1:&lt;PORT&gt;/mcp</code></td></tr>
@@ -74,4 +74,3 @@ export async function accessPost(req, access) {
         return { status: 400 };
     }
 }
-//# sourceMappingURL=access-dashboard.js.map

package/dist/src/account-access-policy.js

@@ -0,0 +1,54 @@
+import { realpath, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { GatewayError, errorCode } from './validation.js';
+import { prepareBatchRead } from './batch-read-policy.js';
+// Reviewed Desktop Commander operations. Tool annotations are hints, not an
+// authorization boundary; unknown tools cannot opt themselves into read-only.
+const readOnlyTools = new Set(['health_check', 'get_config', 'read_file', 'read_multiple_files',
+    'list_directory', 'get_file_info', 'start_search', 'get_more_search_results', 'stop_search',
+    'list_searches', 'read_process_output', 'list_sessions', 'list_processes', 'get_usage_stats', 'get_recent_tool_calls']);
+export const isReadOnlyTool = (name) => readOnlyTools.has(name);
+export async function createAccountAccessPolicy(root, mode = 'read-only') {
+    if (!path.isAbsolute(root))
+        throw new GatewayError('ROOT_REQUIRED');
+    const base = await realpath(root);
+    if (!(await stat(base)).isDirectory())
+        throw new GatewayError('NOT_DIRECTORY');
+    function absolute(raw) {
+        if (typeof raw !== 'string' || !raw || raw.includes('\0'))
+            throw new GatewayError('INVALID_PATH');
+        const expanded = raw === '~' ? homedir() : raw.startsWith('~/') ? path.join(homedir(), raw.slice(2)) : raw;
+        return path.resolve(base, expanded);
+    }
+    const policy = {
+        root: base, mode, developerCommands: 'off',
+        async validateGitPath() { throw new GatewayError('READ_ONLY_MODE'); },
+        async prepare(name, args = {}) {
+            if (!isReadOnlyTool(name))
+                throw new GatewayError('READ_ONLY_MODE');
+            if (name === 'read_multiple_files')
+                return prepareBatchRead(args, policy.prepare);
+            if (['read_file', 'list_directory', 'get_file_info', 'start_search'].includes(name)) {
+                let target = absolute(args.path);
+                if (name === 'read_file') {
+                    // Canonicalize existing links for accurate batch byte accounting, while
+                    // letting upstream retain its native missing-file errors.
+                    try {
+                        target = await realpath(target);
+                        const info = await stat(target);
+                        if (info.isFile() && info.size > 1024 * 1024)
+                            throw new GatewayError('FILE_TOO_LARGE');
+                    }
+                    catch (error) {
+                        if (errorCode(error) !== 'ENOENT')
+                            throw error;
+                    }
+                }
+                return { name, arguments: { ...args, path: target } };
+            }
+            return { name, arguments: args };
+        }
+    };
+    return Object.freeze(policy);
+}

package/dist/src/authorized-workspace-roots.js

@@ -74,4 +74,3 @@ export function createAuthorizedWorkspacePolicy({ basePolicy, linkedGitWorktrees
         }
     });
 }
-//# sourceMappingURL=authorized-workspace-roots.js.map

package/dist/src/batch-read-policy.js

@@ -0,0 +1,30 @@
+import { lstat } from 'node:fs/promises';
+import { GatewayError, errorCode } from './validation.js';
+// Validate every file before forwarding any part of a batch upstream.
+export async function prepareBatchRead(args, prepare) {
+    if (!args || Object.keys(args).some(key => key !== 'paths') || !Array.isArray(args.paths) ||
+        args.paths.length < 1 || args.paths.some(p => typeof p !== 'string'))
+        throw new GatewayError('BATCH_READ_ARGUMENTS_DENIED');
+    if (args.paths.length > 20)
+        throw new GatewayError('BATCH_READ_COUNT_LIMIT');
+    const paths = [];
+    let bytes = 0;
+    for (const raw of args.paths) {
+        const invocation = await prepare('read_file', { path: raw });
+        const target = invocation.arguments?.path;
+        if (typeof target !== 'string')
+            throw new GatewayError('BATCH_READ_PATH_INVALID');
+        const st = await lstat(target).catch(error => {
+            // Authorization already succeeded. Keep missing paths in the upstream
+            // batch so Desktop Commander can report ENOENT beside successful reads.
+            if (errorCode(error) === 'ENOENT')
+                return null;
+            throw error;
+        });
+        bytes += st?.size ?? 0;
+        if (bytes > 4 * 1024 * 1024)
+            throw new GatewayError('BATCH_READ_SIZE_LIMIT');
+        paths.push(target);
+    }
+    return { name: 'read_multiple_files', arguments: { paths } };
+}

package/dist/src/cli/instances.js

@@ -1,4 +1,3 @@
-import { createInterface } from 'node:readline/promises';
 import { spawn } from 'node:child_process';
 import { readFile, writeFile, mkdtemp, rm, realpath } from 'node:fs/promises';
 import { tmpdir, homedir } from 'node:os';
@@ -7,9 +6,9 @@ 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, runInstance } from '../instance-runtime.js';
-import { atomicPrivate, changeRegistry, configJSONSchema, sourceRevision, configTemplate, createInstance, exists, fingerprint, instanceConfigSchema, instanceEnv, instancePaths, instancesRoot, loadInstanceConfig, parseConfig, patchInstanceConfig, readRegistry, readTrusted, resolveInstance, saveInstanceConfig, suggestPort, validateConfig, withLock } from '../instance-store.js';
-const booleans = new Set(['--json', '--all', '--link', '--archived', '--approve-trusted-developer', '--approve-unrestricted', '--confirm', '--effective', '--allow-loopback-http']);
+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) {
     const flags = new Map();
     const positional = [];
@@ -44,75 +43,10 @@ function requireApprovals(config, flags) {
     if (config.accessRole === 'trusted' && process.platform !== 'darwin' && !flags.has('--approve-unrestricted'))
         throw Error('UNRESTRICTED_APPROVAL_REQUIRED: add --approve-unrestricted');
 }
-async function wizard(flags, current) {
-    let project = flags.get('--project') ?? current?.projectRoot;
-    let role = flags.get('--access-role') ?? current?.accessRole ?? 'restricted';
-    let port = Number(flags.get('--port') ?? current?.port ?? await suggestPort());
-    if (!project) {
-        if (!process.stdin.isTTY)
-            throw Error('PROJECT_REQUIRED: use --project /absolute/directory');
-        const rl = createInterface({ input: process.stdin, output: process.stderr });
-        try {
-            project = await rl.question('Work directory: ');
-            role = (await rl.question('Capability (restricted / trusted) [restricted]: ')) || 'restricted';
-            if (role === 'trusted' && (await rl.question('Enable native tools and Shell as your OS account? Type yes: ')) === 'yes') {
-                flags.set('--approve-trusted-developer', 'true');
-                if (process.platform !== 'darwin')
-                    flags.set('--approve-unrestricted', 'true');
-            }
-            port = Number((await rl.question(`Local port [${port}]: `)) || port);
-        }
-        finally {
-            rl.close();
-        }
-    }
-    const config = instanceConfigSchema.parse({ ...current, schemaVersion: 1, projectRoot: await realpath(path.resolve(project)), port,
-        accessRole: role, mode: current?.accessRole === role ? current.mode : role === 'trusted' ? 'read-write' : 'read-only', writeScope: current?.accessRole === role ? current.writeScope : role === 'trusted' && process.platform === 'darwin' ? 'home-only' : 'unrestricted', connection: flags.get('--connection') ?? current?.connection ?? 'local' });
-    requireApprovals(config, flags);
-    return validateConfig(config);
-}
-export async function maybeHandleInstances(argv) {
-    let command = argv[0] ?? 'help';
-    if (command === 'start-setup' && !process.env.MAC_MCP_INTERNAL_SETUP_OWNER_PID) {
-        command = 'run';
-        argv = ['run', '--profile', 'setup', ...argv.slice(1)];
-    }
-    if (command === 'doctor-setup') {
-        command = 'doctor';
-        argv = ['doctor', '--profile', 'setup', ...argv.slice(1)];
-    }
-    const supported = ['instance', 'config', 'run', 'status', 'stop', 'restart', 'logs', 'doctor', 'verify', 'access', 'permissions', 'privacy', 'setup'];
-    if (!supported.includes(command))
-        return false;
-    try {
-        const explicit = argv.includes('--instance');
-        const registry = await readRegistry();
-        const managed = registry.instances.length > 0;
-        const firstWizard = command === 'setup' && argv.length === 1 && process.stdin.isTTY;
-        if (!['instance', 'config'].includes(command) && !explicit && !managed && !firstWizard)
-            return false;
-        // A retained legacy profile remains available until the owner migrates it.
-        const profileIndex = argv.indexOf('--profile');
-        if (profileIndex >= 0 && !registry.instances.some(i => i.legacy === argv[profileIndex + 1]) && argv[profileIndex + 1] !== 'auto') {
-            if (registry.instances.some(i => i.legacy))
-                throw Error('LEGACY_PROFILE_NOT_MIGRATED_USE_INSTANCE: select --instance explicitly');
-            return false;
-        }
-        await handle(command, argv.slice(1));
-    }
-    catch (error) {
-        if (argv.includes('--json'))
-            output({ schemaVersion: 1, error: message(error) });
-        else
-            process.stderr.write(message(error) + '\n');
-        process.exitCode = 1;
-    }
-    return true;
-}
 export async function handle(command, args) {
     const { flags, positional } = options(args);
     const json = flags.has('--json');
-    const known = new Set([...booleans, '--instance', '--name', '--project', '--port', '--access-role', '--connection', '--profile', '--app-parent-pid', '--revision', '--patch', '--file', '--output', '--lines', '--expires', '--issuer', '--resource', '--resource-aliases', '--client-id', '--subjects', '--registration', '--token-auth', '--callback', '--target', '--mode']);
+    const known = new Set([...booleans, '--instance', '--name', '--project', '--port', '--access-role', '--connection', '--app-parent-pid', '--revision', '--patch', '--file', '--output', '--lines', '--expires', '--issuer', '--resource', '--resource-aliases', '--client-id', '--subjects', '--registration', '--token-auth', '--callback', '--target', '--mode']);
     for (const flag of flags.keys())
         if (!known.has(flag))
             throw Error('UNKNOWN_OPTION: ' + flag);
@@ -131,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));
@@ -152,12 +87,6 @@ export async function handle(command, args) {
             }
             return;
         }
-        if (op === 'create') {
-            const config = await wizard(flags);
-            const instance = await createInstance(positional[1] ?? flags.get('--name') ?? 'default', { config });
-            output({ instance, message: 'Saved. Start with: starmux up -i ' + JSON.stringify(instance.name) });
-            return;
-        }
         if (op === 'import') {
             const file = positional[1];
             if (!file)
@@ -168,11 +97,6 @@ export async function handle(command, args) {
                 message: flags.has('--link') ? 'Bound to original file. Changes require apply.' : 'Imported a private copy. The original file is no longer used.' });
             return;
         }
-        if (op === 'migrate') {
-            const { migrateLegacy } = await import('../instance-migration.js');
-            output(await migrateLegacy(positional[1], flags.has('--confirm'), flags.get('--name')));
-            return;
-        }
         const instance = await resolveInstance(positional[1] ?? flags.get('--instance'), homedir(), op === 'restore');
         if (op === 'copy') {
             const config = { ...(await loadInstanceConfig(instance)).config, port: await suggestPort() };
@@ -198,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;
@@ -222,47 +146,9 @@ export async function handle(command, args) {
             process.stdout.write(`Restored instance '${instance.name}'.\n`);
         return;
     }
-    if (command === 'status' && !flags.has('--instance') && (!json || flags.has('--all')))
-        return handle('instance', ['list', ...(json ? ['--json'] : [])]);
-    const profile = flags.get('--profile');
-    let selector = flags.get('--instance');
-    if (profile && profile !== 'auto') {
-        const legacy = (await readRegistry()).instances.find(i => i.legacy === profile);
-        if (!legacy)
-            throw Error('LEGACY_PROFILE_NOT_MIGRATED');
-        selector = legacy.id;
-    }
-    if (command === 'setup' && !(await readRegistry()).instances.length) {
-        await handle('instance', ['create', 'default', ...args]);
-        return;
-    }
+    const selector = flags.get('--instance');
     const instance = await resolveInstance(selector);
     const p = instancePaths(instance);
-    if (command === 'status') {
-        output(await instanceStatus(instance));
-        return;
-    }
-    if (command === 'run') {
-        if (flags.has('--port'))
-            throw Error('INSTANCE_PORT_OVERRIDE_DENIED: edit configuration and apply');
-        await runInstance(instance, { json, ...(flags.has('--app-parent-pid') ? { appParentPid: Number(flags.get('--app-parent-pid')) } : {}) });
-        return;
-    }
-    if (command === 'stop') {
-        output({ result: (await instanceRequest(instance, 'stop')) ? 'STOPPED' : 'ALREADY_STOPPED', instanceId: instance.id });
-        return;
-    }
-    if (command === 'restart') {
-        await handle('config', ['apply', '--instance', instance.id, ...(json ? ['--json'] : [])]);
-        return;
-    }
-    if (command === 'setup') {
-        const current = await loadInstanceConfig(instance);
-        const config = await wizard(flags, current.config);
-        await patchInstanceConfig(instance, config, current.revision);
-        output({ result: 'SAVED', instanceId: instance.id, message: 'Apply changes to restart the running instance.' });
-        return;
-    }
     if (command === 'config') {
         const op = positional[0] ?? 'show';
         if (op === 'path') {
@@ -278,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` +
@@ -320,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);
@@ -406,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
@@ -444,29 +338,6 @@ export async function handle(command, args) {
         }
         throw Error('CONFIG_ACTION_INVALID');
     }
-    if (command === 'logs') {
-        const file = path.join(p.logs, 'core.log');
-        const lines = Math.min(200, Math.max(1, Number(flags.get('--lines') ?? 60)));
-        if (!Number.isSafeInteger(Number(flags.get('--lines') ?? 60)) || Number(flags.get('--lines') ?? 60) < 1 || Number(flags.get('--lines') ?? 60) > 200)
-            throw Error('INVALID_LINES: expected 1..200');
-        const text = await exists(file) ? (await readTrusted(file, true, 32 * 1024 * 1024)).split('\n').slice(-lines).join('\n') : 'No logs yet.';
-        if (json)
-            output({ instanceId: instance.id, output: text });
-        else
-            process.stdout.write(text + '\n');
-        return;
-    }
-    if (command === 'access') {
-        process.env.MAC_MCP_ACCESS_FILE = p.access;
-        const clean = args.filter((_, i) => args[i] !== '--instance' && args[i - 1] !== '--instance' && args[i] !== '--profile' && args[i - 1] !== '--profile');
-        await (await import('./access.js')).accessCommand(clean);
-        if (positional[0] === 'mode') {
-            const mode = positional[1];
-            if (mode === 'ingress' || mode === 'api-key' || mode === 'oauth')
-                await changeRegistry(async (r) => { r.instances.find(i => i.id === instance.id).requiredAccess = mode; });
-        }
-        return;
-    }
     if (command === 'permissions') {
         const grants = await createWorkspaceGrants({ file: p.grants });
         const deny = await createDenyRules({ file: p.deny });
@@ -482,15 +353,6 @@ export async function handle(command, args) {
         }
         return;
     }
-    const loaded = await loadInstanceConfig(instance);
-    if (command === 'doctor') {
-        const { ensureAccessReady } = await import('../instance-store.js');
-        await ensureAccessReady(instance);
-        const status = await instanceStatus(instance);
-        output({ result: 'PASS', instanceId: instance.id, source: instance.source, config: loaded.config, configState: status.configState,
-            message: 'Configuration and access state validated. Run verify after starting to check real tools.' });
-        return;
-    }
     if (command === 'privacy') {
         const status = await instanceStatus(instance);
         if (!status.runtime?.port)
@@ -498,27 +360,5 @@ export async function handle(command, args) {
         output(await (await import('../privacy-diagnostics.js')).privacyReport({ port: status.runtime.port, home: homedir(), all: flags.has('--all'), target: flags.get('--target') ?? null }));
         return;
     }
-    if (command === 'verify') {
-        const state = await instanceRequest(instance, 'status');
-        if (state?.phase !== 'running' || !state.port)
-            throw Error('INSTANCE_NOT_RUNNING');
-        const endpoint = `http://127.0.0.1:${state.port}`;
-        const health = await fetch(endpoint + '/healthz', { signal: AbortSignal.timeout(3000) }).then(r => r.json());
-        if (health.instanceId !== instance.id)
-            throw Error('INSTANCE_HEALTH_IDENTITY_MISMATCH');
-        const request = async (method, params) => {
-            const reply = await fetch(endpoint + '/mcp', { method: 'POST', headers: { 'content-type': 'application/json', accept: 'application/json, text/event-stream', ...(process.env.MAC_MCP_API_KEY ? { authorization: 'Bearer ' + process.env.MAC_MCP_API_KEY } : {}) }, body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }), signal: AbortSignal.timeout(15000) });
-            if (!reply.ok)
-                throw Error(reply.status === 401 ? 'VERIFICATION_CREDENTIAL_REQUIRED: set MAC_MCP_API_KEY' : 'MCP_VERIFICATION_FAILED');
-            const data = await reply.json();
-            if (data.error || data.result?.isError)
-                throw Error('MCP_VERIFICATION_FAILED');
-            return data.result;
-        };
-        await request('tools/list', {});
-        await request('tools/call', { name: 'list_directory', arguments: { path: '.', depth: 0 } });
-        output({ result: 'PASS', instanceId: instance.id, port: state.port, remoteClientVerified: false });
-        return;
-    }
+    throw Error('INSTANCE_COMMAND_UNSUPPORTED');
 }
-//# sourceMappingURL=instances.js.map

package/dist/src/cli/oauth.js

@@ -71,4 +71,3 @@ export async function oauthCommand(args) {
         process.stdout.write('  Configuration saved. Enable explicitly: starmux auth mode oauth\n');
     process.stdout.write('  Remote ChatGPT authorization is not verified by this command.\n\n');
 }
-//# sourceMappingURL=oauth.js.map