starmux 0.13.1 → 0.15.0

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

@@ -1,5 +1,5 @@
 import { createAccessControl } from '../access-control.js';
-import { exists, instancePaths } from '../instance-store.js';
+import { exists, instancePaths, usesGlobalPermissions } from '../instance-store.js';
 import { shellQuote } from '../platform.js';
 async function authentication(instance, status) {
     const file = instancePaths(instance).access;
@@ -23,6 +23,8 @@ async function authentication(instance, status) {
     }
 }
 export async function formatStarmuxStatus(instance, status, config, options = {}) {
+    // 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';
@@ -37,29 +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 mode = !config
+    const globalMode = status.phase === 'running' ? status.runtime?.permissionMode === 'global' : !!config && usesGlobalPermissions(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)')
-            : 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  (run '${codingCmd}' to enable edits & shell)`;
-    const runtime = status.executionMode === 'background'
-        ? 'Background · continues after this terminal closes'
-        : status.executionMode === 'foreground-owned'
-            ? (status.runtime?.launcher === 'app' ? 'App-owned · stops when the app closes' : 'Foreground · Ctrl+C stops this instance')
-            : 'Stopped';
-    const title = omitSelector
-        ? `${indicator} Starmux is ${status.phase}`
-        : `${indicator} Starmux is ${status.phase}  (instance: ${instance.name})`;
-    const lines = ['', title];
+                : `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('Workspace', config?.projectRoot ?? 'Unavailable'), row('Mode', mode), row('Auth', auth.mode ? labels[auth.mode] + (ready ? '' : saved) : 'Unavailable'), row('Runtime', runtime));
+    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));
     }
@@ -119,4 +127,3 @@ export async function formatStarmuxStatus(instance, status, config, options = {}
         lines.push(row('Stop', command('down')));
     return lines.join('\n') + '\n';
 }
-//# sourceMappingURL=starmux-status.js.map

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

@@ -8,4 +8,3 @@ catch (error) {
     process.stderr.write(String(error) + '\n');
     process.exitCode = 1;
 }
-//# sourceMappingURL=starmux-supervisor.js.map

package/dist/src/cli/starmux.js

@@ -8,13 +8,13 @@ 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 { atomicPrivate, availablePort, changeRegistry, configJSONSchema, createInstance, ensureAccessReady, exists, instanceConfigSchema, instancePaths, loadInstanceConfig, parseConfig, patchInstanceConfig, readRegistry, readTrusted, resolveInstance, saveInstanceConfig, suggestPort, validateConfig } from '../instance-store.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 { desktopCommanderEntry } from '../runtime-paths.js';
+import { packageRoot, desktopCommanderEntry } from '../runtime-paths.js';
 import { shellQuote } from '../platform.js';
 import { formatStarmuxStatus } from './starmux-status.js';
-const version = '0.13.1';
+const { version } = JSON.parse(await readFile(path.join(packageRoot, 'package.json'), 'utf8'));
 const strings = ['instance', 'port', 'lines', 'expires', 'issuer', 'resource', 'resource-aliases', 'client-id', 'subject', 'subjects', 'registration', 'token-auth', 'callback', 'revision', 'patch', 'file', 'output', 'name', 'target', 'mode', 'app-parent-pid'];
 const booleans = ['help', 'version', 'json', 'write', 'code', 'read', 'yes', 'foreground', 'follow', 'archived', 'all', 'effective', 'link', 'allow-loopback-http', 'token-stdin', 'no-open', 'token'];
 const options = {};
@@ -52,12 +52,11 @@ function help() {
         verify: 'verify [--token-stdin]\n  Test MCP initialization, tool discovery and workspace read. Authenticated instances use STARMUX_TOKEN or stdin.',
         doctor: 'doctor\n  Check Node, bundled dependencies, workspace, configuration, port and authentication.',
         logs: 'logs [-f | --follow] [--lines 1..200]\n  Follow continues across restarts. Ctrl+C exits the follower only.',
-        migrate: 'migrate [registry|setup|live] [-y]\n  No source: preview. Select a source to migrate, retaining originals.',
         status: 'status [--all]\n  Show the selected instance, its actual endpoint and connection guide.',
         ls: 'ls [--archived]\n  List local workspace instances.',
         rm: 'rm [NAME] (alias for: config archive)\n  Stop and archive an instance.',
         down: 'down (alias: stop)\n  Stop the selected instance.',
-        permissions: 'permissions [status | token]\n  permissions disable-tool|enable-tool|deny-directory|allow-directory TARGET\n  Manage the selected instance’s tool and directory permissions.',
+        permissions: 'permissions [status]\n  Show the selected instance’s mode. Switch with up --read or up --code.',
         privacy: 'privacy [--all] [--target PATH]\n  Check privacy access through the running instance.'
     };
     if (topic && topic !== 'help' && !sections[topic])
@@ -81,8 +80,7 @@ function help() {
         '  starmux ls                   List workspace instances',
         '  starmux rm [name]            Stop and archive an instance',
         '  starmux init [path]          Save instance settings without starting',
-        '  starmux config               Inspect, edit or apply configuration',
-        '  starmux migrate              Import settings from a legacy installation'
+        '  starmux config               Inspect, edit or apply configuration'
     ].join('\n');
     process.stdout.write(`Starmux ${version}\n\n${sections[topic ?? ''] ?? overview}\n\nGlobal: -i, --instance NAME_OR_ID   --json   -h, --help\nUse starmux COMMAND --help for details.\n`);
 }
@@ -127,8 +125,11 @@ async function configure() {
         instance = await resolveInstance();
     if (instance?.archived)
         fail('Instance is archived. Use starmux config restore -i ' + instance.name);
-    if (!instance && await exists(path.join(homedir(), '.config', 'mac-mcp-gateway')) && !registry.instances.length)
-        fail('Existing installation found. Run starmux migrate first.');
+    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)
@@ -164,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;
@@ -364,7 +373,7 @@ async function auth(instance) {
         return;
     }
     if (op === 'oauth') {
-        process.env.MAC_MCP_ACCESS_FILE = instancePaths(instance).access;
+        process.env.STARMUX_ACCESS_FILE = instancePaths(instance).access;
         const action = positional[1] ?? 'status';
         const map = { 'init-keycloak': 'keycloak-realm', setup: 'configure', doctor: 'doctor', status: 'status' };
         if (!map[action])
@@ -593,7 +602,7 @@ async function main() {
     }
     const allowed = {
         up: ['port', 'read', 'write', 'code', 'yes', 'foreground', 'app-parent-pid'], init: ['port', 'read', 'write', 'code', 'yes'],
-        status: ['all'], ls: ['archived'], rm: [], down: [], stop: [], logs: ['lines', 'follow'], doctor: [], verify: ['token-stdin'], dashboard: ['token', 'no-open'], migrate: ['yes'],
+        status: ['all'], ls: ['archived'], rm: [], down: [], stop: [], logs: ['lines', 'follow'], doctor: [], verify: ['token-stdin'], dashboard: ['token', 'no-open'],
         auth: ['expires', 'issuer', 'resource', 'resource-aliases', 'client-id', 'subject', 'subjects', 'registration', 'token-auth', 'callback', 'allow-loopback-http'],
         config: ['yes', 'archived', 'effective', 'link', 'name', 'revision', 'patch', 'file', 'output'], permissions: ['target', 'mode'], privacy: ['all', 'target']
     };
@@ -609,15 +618,6 @@ async function main() {
         fail('Usage: starmux rm [NAME]');
     if (command === 'auth' && ['key', 'mode', 'revoke'].includes(positional[0] ?? '') && positional.length !== 2)
         fail('Usage: starmux auth ' + positional[0] + ' VALUE');
-    if (command === 'migrate' && positional.length > 1)
-        fail('Usage: starmux migrate [registry|setup|live] [-y]');
-    // Public commands never inherit old environment overlays. Core's private protocol is retained.
-    for (const key of Object.keys(process.env))
-        if (key.startsWith('MAC_MCP_'))
-            delete process.env[key];
-    for (const [key, value] of Object.entries(process.env))
-        if (key.startsWith('STARMUX_') && key !== 'STARMUX_TOKEN')
-            process.env['MAC_MCP_' + key.slice(8)] = value;
     if (command === 'up' || command === 'init') {
         const instance = await configure();
         if (command === 'up')
@@ -630,10 +630,6 @@ async function main() {
         }
         return;
     }
-    if (command === 'migrate') {
-        await (await import('../starmux-migration.js')).migrate(positional[0], yes(), json);
-        return;
-    }
     if (command === 'ls' || command === 'status' && flags.all) {
         await handle('instance', ['list', ...(flags.archived ? ['--archived'] : []), ...(json ? ['--json'] : [])]);
         return;
@@ -662,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);
@@ -679,29 +677,42 @@ 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`);
         }
     }
     else {
+        if (command === 'permissions' && usesGlobalPermissions((await loadInstanceConfig(instance)).config)) {
+            if (positional.length && positional[0] !== 'status')
+                fail('Directory grants and tool filters do not apply to global modes. Use starmux up --read or starmux up --code.');
+            await show(instance);
+            return;
+        }
         const args = [...positional, '--instance', instance.id];
         for (const [key, value] of Object.entries(flags))
             if (key !== 'instance' && value !== undefined)
@@ -720,4 +731,3 @@ catch (error) {
         process.stderr.write(message + '\n');
     process.exitCode = 1;
 }
-//# sourceMappingURL=starmux.js.map

package/dist/src/config-schemas.js

@@ -1,14 +1,5 @@
 import { z } from 'zod';
-const common = { projectRoot: z.string(), mode: z.enum(['read-only', 'read-write']), connection: z.enum(['tunnel', 'https']), port: z.number().int() };
-export const setupSchema = z.discriminatedUnion('version', [
-    z.object({ ...common, version: z.literal(1) }).strict(),
-    z.object({ ...common, version: z.literal(2), accessRole: z.enum(['restricted', 'trusted']) }).strict(),
-    z.object({ ...common, version: z.literal(3), accessRole: z.literal('trusted'), writeScope: z.literal('home-only') }).strict()
-]);
 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 revocationsSchema = z.object({ version: z.literal(1), revokedSubjects: z.array(z.string()), revokedJtis: 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 privateAgentSchema = z.object({ Label: z.string(), ProgramArguments: z.tuple([z.string(), z.string()]), EnvironmentVariables: z.record(z.string()), WorkingDirectory: z.string(), StandardOutPath: z.string().optional(), StandardErrorPath: z.string().optional(), RunAtLoad: z.boolean().optional() }).passthrough();
-//# sourceMappingURL=config-schemas.js.map
+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/configured-mcp-upstreams.js

@@ -191,4 +191,3 @@ export async function bootstrapConfiguredUpstreams(configFile, audit = () => { }
     }
     return { routes, upstreams, status: () => upstreams.map(x => x.status) };
 }
-//# sourceMappingURL=configured-mcp-upstreams.js.map

package/dist/src/contracts.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=contracts.js.map

package/dist/src/current-permission-probe.js

@@ -61,4 +61,3 @@ export async function probeCurrentDirectoryAccess({ home = os.homedir(), openDir
         checks
     };
 }
-//# sourceMappingURL=current-permission-probe.js.map

package/dist/src/dc-workspace-http.js

@@ -4,7 +4,7 @@ import { createAccessControl } from './access-control.js';
 import { accessPage, accessPost, accessHeaders } from './access-dashboard.js';
 import { isSafeInteger } from "./validation.js";
 // Explicit project-root Desktop Commander MCP endpoint. Never exposed to public Caddy.
-// Start only with owner-approved MAC_MCP_PROJECT_ROOT; no default HOME traversal.
+// Start only with owner-approved STARMUX_PROJECT_ROOT; no default HOME traversal.
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { createServer } from "node:http";
 import { createAuthorizedWorkspacePolicy } from "./authorized-workspace-roots.js";
@@ -22,6 +22,8 @@ import { createPrivateMCPActivity } from "./private-mcp-activity.js";
 import { createGitWorkflow } from "./project-git-workflow.js";
 import { createProjectPolicy } from "./project-workspace-policy.js";
 import { createWorkspaceGrants } from "./workspace-grants.js";
+import { createAccountAccessPolicy } from './account-access-policy.js';
+import { isAllowedGatewayHost } from './http-host-policy.js';
 /** Construction and imports are inert; only start acquires resources. */
 export function createGatewayRuntime(options = {}) {
     let running = null;
@@ -53,27 +55,31 @@ export function createGatewayRuntime(options = {}) {
     };
 }
 async function initializeGateway({ env = process.env, audit: externalAudit }) {
-    const access = await createAccessControl(env.MAC_MCP_ACCESS_FILE);
-    const page = (html) => instancePage(html, env.MAC_MCP_INSTANCE_NAME, env.MAC_MCP_INSTANCE_ID);
-    const root = env.MAC_MCP_PROJECT_ROOT;
+    const access = await createAccessControl(env.STARMUX_ACCESS_FILE);
+    const page = (html) => instancePage(html, env.STARMUX_INSTANCE_NAME, env.STARMUX_INSTANCE_ID);
+    const root = env.STARMUX_PROJECT_ROOT;
     if (!root)
         throw new Error("OWNER_APPROVED_PROJECT_ROOT_REQUIRED");
-    const mode = env.MAC_MCP_WORKSPACE_MODE || "read-only";
-    const developerCommands = env.MAC_MCP_DEV_COMMANDS || "presets";
-    const nativeAccessMode = env.MAC_MCP_DC_ACCESS_MODE || "workspace";
-    const writeScope = env.MAC_MCP_DC_WRITE_SCOPE || "unrestricted";
+    const mode = env.STARMUX_WORKSPACE_MODE || "read-only";
+    const developerCommands = env.STARMUX_DEV_COMMANDS || "presets";
+    const nativeAccessMode = env.STARMUX_DC_ACCESS_MODE || "workspace";
+    const writeScope = env.STARMUX_DC_WRITE_SCOPE || "unrestricted";
+    const globalPermissions = env.STARMUX_PERMISSION_MODE === 'global';
+    const globalReadOnly = globalPermissions && mode === 'read-only';
     if (!["unrestricted", "home-only"].includes(writeScope) ||
         (writeScope === "home-only" && nativeAccessMode !== "native"))
         throw Error("HOME_WRITE_SCOPE_REQUIRES_NATIVE_ROLE");
-    if (writeScope === "home-only" && env.MAC_MCP_UPSTREAMS_FILE)
+    if (writeScope === "home-only" && env.STARMUX_UPSTREAMS_FILE)
         throw Error("HOME_WRITE_SCOPE_UNSANDBOXED_EXTRA_UPSTREAMS");
     if (!["workspace", "native"].includes(nativeAccessMode) ||
         (nativeAccessMode === "native" &&
             (developerCommands !== "trusted-project" || mode !== "read-write")))
         throw new Error("NATIVE_ACCESS_REQUIRES_OWNER_TRUSTED_DEVELOPER_PROFILE");
-    const policy = await createProjectPolicy({ root, mode, developerCommands,
+    if (globalPermissions && (writeScope !== 'unrestricted' || (!globalReadOnly && nativeAccessMode !== 'native')))
+        throw Error('GLOBAL_ACCESS_MODE_INVALID');
+    const policy = globalPermissions ? await createAccountAccessPolicy(root, mode) : await createProjectPolicy({ root, mode, developerCommands,
         allowTrustedHomeRoot: nativeAccessMode === "native" && developerCommands === "trusted-project" });
-    const desiredPort = Number(env.MAC_MCP_PROJECT_PORT || 8793);
+    const desiredPort = Number(env.STARMUX_PROJECT_PORT || 18893);
     if (!isSafeInteger(desiredPort) || desiredPort < 0 || desiredPort > 65535)
         throw new Error("INVALID_PORT");
     let activity = null;
@@ -103,32 +109,31 @@ async function initializeGateway({ env = process.env, audit: externalAudit }) {
         await upstream.connect();
         // Default configuration remains the original Desktop Commander-only profile.
         // Additional trusted operator-owned routes require an explicit private config.
-        configured = await bootstrapConfiguredUpstreams(env.MAC_MCP_UPSTREAMS_FILE, audit);
+        configured = await bootstrapConfiguredUpstreams(env.STARMUX_UPSTREAMS_FILE, audit);
         const router = createMCPUpstreamRouter({ routes: [
                 { id: "desktop", upstream, exposeNativeNames: true }, ...configured.routes
             ] });
-        // Owner explicitly opts in on isolated development runs only.
-        // Not enabled in the currently deployed 8793 process.
-        if (env.MAC_MCP_PRIVATE_ACTIVITY_OBSERVER === "1")
+        // The instance supervisor enables this bounded, owner-local activity observer.
+        if (env.STARMUX_PRIVATE_ACTIVITY_OBSERVER === "1")
             activity = createPrivateMCPActivity({ routeFor: name => router.routeFor(name) });
-        const worktreeMode = env.MAC_MCP_WORKTREE_MODE || "off";
+        const worktreeMode = env.STARMUX_WORKTREE_MODE || "off";
         if (!["off", "linked"].includes(worktreeMode))
             throw Error("INVALID_WORKTREE_MODE");
         const worktreePolicy = createAuthorizedWorkspacePolicy({
-            basePolicy: policy, linkedGitWorktrees: worktreeMode
+            basePolicy: policy, linkedGitWorktrees: globalPermissions ? 'off' : worktreeMode
         });
         // Explicit opt-in: existing/private deployments remain unchanged without this file.
-        const grants = env.MAC_MCP_GRANTS_FILE ?
-            await createWorkspaceGrants({ file: env.MAC_MCP_GRANTS_FILE, audit }) : null;
+        const grants = !globalPermissions && env.STARMUX_GRANTS_FILE ?
+            await createWorkspaceGrants({ file: env.STARMUX_GRANTS_FILE, audit }) : null;
         const workspacePolicy = grants ?
             createManagedWorkspacePolicy({ basePolicy: worktreePolicy, grants }) : worktreePolicy;
         // Optional explicit deny preferences: default empty, independent from DC tools.
         // Owner-managed only via the same local token as Workspace Permissions.
-        if (env.MAC_MCP_DENY_FILE && !grants)
+        if (!globalPermissions && env.STARMUX_DENY_FILE && !grants)
             throw Error("DENY_CONSOLE_REQUIRES_OWNER_GRANTS");
-        const denyRules = env.MAC_MCP_DENY_FILE ?
-            await createDenyRules({ file: env.MAC_MCP_DENY_FILE, audit }) : null;
-        const gitMode = env.MAC_MCP_GIT_MODE || "off";
+        const denyRules = !globalPermissions && env.STARMUX_DENY_FILE ?
+            await createDenyRules({ file: env.STARMUX_DENY_FILE, audit }) : null;
+        const gitMode = globalPermissions ? 'off' : env.STARMUX_GIT_MODE || "off";
         if (!["off", "review", "write", "push"].includes(gitMode))
             throw new Error("INVALID_GIT_MODE");
         if (writeScope === "home-only" && gitMode !== "off")
@@ -138,15 +143,33 @@ async function initializeGateway({ env = process.env, audit: externalAudit }) {
             pushEnabled: gitMode === "push"
         });
         http = createServer(async (req, res) => {
-            const local = req.socket.remoteAddress === "127.0.0.1";
+            const denyRequest = (reason) => {
+                audit({ event: 'HTTP_REQUEST_DENIED', reason });
+                res.writeHead(403, { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' }).end(reason);
+            };
+            if (req.socket.remoteAddress !== "127.0.0.1") {
+                denyRequest('LOOPBACK_REQUIRED');
+                return;
+            }
+            let route;
+            try {
+                route = new URL(req.url || "/", "http://localhost").pathname;
+            }
+            catch {
+                res.writeHead(400).end('Invalid request target');
+                return;
+            }
             const address = http?.address();
             const port = address && typeof address !== "string" ? address.port : null;
-            const hostOk = [`127.0.0.1:${port}`, `localhost:${port}`].includes(req.headers.host ?? "");
-            if (!local || !hostOk) {
-                res.writeHead(403).end("Denied");
+            if (!isAllowedGatewayHost(req, port, route)) {
+                denyRequest('HOST_NOT_ALLOWED');
+                return;
+            }
+            if (globalPermissions && (route === '/permissions' || route === '/filters')) {
+                res.writeHead(410, { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' });
+                res.end('Starmux uses global Read-only or Coding mode. Directory grants and tool filters do not apply. Use starmux up --read or starmux up --code.');
                 return;
             }
-            const route = new URL(req.url || "/", "http://localhost").pathname;
             if (route.startsWith('/.well-known/oauth-protected-resource') && (req.method === 'GET' || req.method === 'OPTIONS')) {
                 try {
                     const config = await access.oauthSettings();
@@ -175,10 +198,10 @@ async function initializeGateway({ env = process.env, audit: externalAudit }) {
                     }
                     else if (req.method === "POST") {
                         const result = await accessPost(req, access);
-                        if (result.status === 200 && env.MAC_MCP_INSTANCE_ID) {
+                        if (result.status === 200 && env.STARMUX_INSTANCE_ID) {
                             const { changeRegistry, instancePaths } = await import('./instance-store.js');
                             await changeRegistry(async (registry) => {
-                                const instance = registry.instances.find(i => i.id === env.MAC_MCP_INSTANCE_ID);
+                                const instance = registry.instances.find(i => i.id === env.STARMUX_INSTANCE_ID);
                                 if (instance && instancePaths(instance).access === access.file)
                                     instance.requiredAccess = (await access.snapshot()).mode;
                             });
@@ -251,10 +274,11 @@ async function initializeGateway({ env = process.env, audit: externalAudit }) {
             if ((route === "/dashboard" || route === "/dashboard.json") && req.method === "GET") {
                 try {
                     const snapshot = { ...await collectOperationsSnapshot(), configuredUpstreams: configured.status(),
-                        ...(env.MAC_MCP_INSTANCE_ID ? { instance: { id: env.MAC_MCP_INSTANCE_ID, name: env.MAC_MCP_INSTANCE_NAME ?? env.MAC_MCP_INSTANCE_ID, port: desiredPort } } : {}),
+                        ...(env.STARMUX_INSTANCE_ID ? { instance: { id: env.STARMUX_INSTANCE_ID, name: env.STARMUX_INSTANCE_NAME ?? env.STARMUX_INSTANCE_ID, port: desiredPort } } : {}),
                         accessControl: await access.snapshot(),
                         permissionManagementEnabled: Boolean(grants),
                         nativeAccessEnabled: nativeAccessMode === "native",
+                        permissionMode: globalPermissions ? 'global' : 'workspace',
                         denyRuleManagementEnabled: Boolean(denyRules) };
                     const json = route.endsWith(".json");
                     res.writeHead(200, { ...dashboardHeaders,
@@ -291,7 +315,7 @@ async function initializeGateway({ env = process.env, audit: externalAudit }) {
                 res.writeHead(200, { "content-type": "application/json", "cache-control": "no-store" });
                 const accessMode = await access.snapshot().then(s => s.mode).catch(() => "unavailable");
                 res.end(JSON.stringify({ status: "ok", service: "dc-project-workspace", mode,
-                    writeScope, accessMode, ...(env.MAC_MCP_INSTANCE_ID ? { instanceId: env.MAC_MCP_INSTANCE_ID, instanceName: env.MAC_MCP_INSTANCE_NAME } : {}) }));
+                    writeScope, accessMode, ...(env.STARMUX_INSTANCE_ID ? { instanceId: env.STARMUX_INSTANCE_ID, instanceName: env.STARMUX_INSTANCE_NAME } : {}) }));
                 return;
             }
             if (route !== "/mcp") {
@@ -331,6 +355,7 @@ async function initializeGateway({ env = process.env, audit: externalAudit }) {
             const gateway = createDesktopCommanderBridge(router, audit, {
                 request, ...(oauth ? { oauthScope: oauth.scope } : {}), workspacePolicy, upstreamRouter: router,
                 nativePassthrough: nativeAccessMode === "native", denyRules,
+                globalReadOnly, permissionMode: globalPermissions ? 'global' : 'workspace',
                 ...(gitWorkflow ? { gitWorkflow } : {})
             });
             bridges.add(gateway);
@@ -385,4 +410,3 @@ export async function runGateway(options = {}) {
     process.on('SIGTERM', stop);
     return runtime;
 }
-//# sourceMappingURL=dc-workspace-http.js.map

package/dist/src/deny-dashboard.js

@@ -43,7 +43,7 @@ export function renderDenyDashboard({ rules, toolCatalog = [] }) {
         '<p>仅检查具有明确文件路径参数的直接工具调用。' +
         '<strong>不限制 Shell、Python、脚本或上游工具间接访问文件。</strong> ' +
         '也不是操作系统沙箱；对目录的递归枚举或搜索亦不能提供可靠隔离。' +
-        '需要真正隔离时，应由 Desktop Commander / macOS / 容器负责。</p>' +
+        '需要真正隔离时，应由 Desktop Commander / 操作系统 / 容器负责。</p>' +
         '<table><thead><tr><th>过滤目录</th><th>操作</th></tr></thead><tbody>' +
         (paths || '<tr><td colspan="2">没有目录过滤规则</td></tr>') +
         '</tbody></table><h3>添加禁止的目录</h3>' +
@@ -56,7 +56,7 @@ export function renderDenyDashboard({ rules, toolCatalog = [] }) {
         '</section><p><a href="/dashboard">运行 Dashboard</a> · ' +
         '<a href="/permissions">目录授权</a></p>' +
         '<small>黑名单是防误操作护栏，不是抵御恶意 Shell 或提示注入的安全边界。' +
-        '这里的管理密钥只由设备所有者在 Mac 本机使用，不得发送给远程 AI。</small>' +
+        '这里的管理密钥只由设备所有者在本机使用，不得发送给远程 AI。</small>' +
         '</body></html>';
 }
 export async function applyDenyPost(req, ruleStore, authorize, host) {
@@ -89,4 +89,3 @@ export async function applyDenyPost(req, ruleStore, authorize, host) {
         return { status: 400, message: "Rule rejected: check name or directory" };
     }
 }
-//# sourceMappingURL=deny-dashboard.js.map

package/dist/src/desktop-commander-facade.js

@@ -1,5 +1,6 @@
 import { createInvocationPipeline, safeAuditSink } from "./invocation.js";
 import { createToolDispatcher } from "./tool-dispatch.js";
+import { isReadOnlyTool } from './account-access-policy.js';
 // Desktop Commander tool-schema facade. Upstream catalog remains unmodified.
 // Preserve all native upstream tools; owner-approved native mode forwards unchanged.
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -10,7 +11,7 @@ export function createDesktopCommanderBridge(upstream, audit = () => { }, option
     const resourcesEnabled = typeof upstream.listResources === "function" &&
         typeof upstream.readResource === "function";
     const server = new Server({
-        name: "mac-mcp-gateway-desktop-commander-bridge", version: "0.1.0"
+        name: "starmux-desktop-commander-bridge", version: "0.1.0"
     }, { capabilities: { tools: {}, ...(resourcesEnabled ? { resources: {} } : {}) } });
     if (resourcesEnabled) {
         server.setRequestHandler(ListResourcesRequestSchema, async () => {
@@ -40,10 +41,10 @@ export function createDesktopCommanderBridge(upstream, audit = () => { }, option
                         annotations: { readOnlyHint: true, destructiveHint: false }
                     }] : []), {
                     name: "health_check",
-                    description: "Mac MCP Gateway bridge connection and genuine upstream availability check",
+                    description: "Starmux bridge connection, upstream availability and active mode check. Read-only blocks writes and arbitrary execution; Coding uses upstream tools with OS account permissions.",
                     inputSchema: { type: "object", properties: {}, additionalProperties: false },
                     annotations: { readOnlyHint: true, destructiveHint: false }
-                }].filter(tool => !state?.deniedTools.includes(tool.name)).map(tool => options.oauthScope ? { ...tool,
+                }].filter(tool => !state?.deniedTools.includes(tool.name) && (!options.globalReadOnly || isReadOnlyTool(tool.name))).map(tool => options.oauthScope ? { ...tool,
                 securitySchemes: [{ type: 'oauth2', scopes: [options.oauthScope] }],
                 _meta: { ...('_meta' in tool ? tool._meta : {}), securitySchemes: [{ type: 'oauth2', scopes: [options.oauthScope] }] } } : tool) };
     });
@@ -57,4 +58,3 @@ export function createDesktopCommanderBridge(upstream, audit = () => { }, option
     server.setRequestHandler(CallToolRequestSchema, request => invoke(request.params));
     return server;
 }
-//# sourceMappingURL=desktop-commander-facade.js.map

package/dist/src/explicit-deny-rules.js

@@ -3,7 +3,7 @@ import { ownedByUser, createPrivateDirectory, within } from "./platform.js";
 import { denySchema } from "./config-schemas.js";
 import { GatewayError, errorCode, parseJSON, record } from "./validation.js";
 // Optional explicit-deny preferences. Never a sandbox; native tools and command
-// semantics belong to upstream Desktop Commander and the macOS execution user.
+// semantics belong to upstream Desktop Commander and the OS execution user.
 // Reads the owner-only 0600 profile on EVERY discovery/call, so revocation applies
 // to stale-client tool calls without restarting the Gateway.
 import { randomBytes } from "node:crypto";
@@ -15,7 +15,7 @@ function issue(code) { const e = new GatewayError(code); throw e; }
 const toolName = /^[a-zA-Z_][a-zA-Z0-9_.:-]{0,127}$/;
 const pathKeys = new Set(["path", "file_path", "paths", "source", "destination", "outputPath"]);
 const defaults = () => ({ version: 1, deniedTools: [], deniedDirectories: [] });
-export const defaultDenyRulesPath = (home = homedir()) => path.join(home, ".config", "mac-mcp-gateway", "deny-rules-v1.json");
+export const defaultDenyRulesPath = (home = homedir()) => path.join(home, ".config", "starmux", "deny-rules-v1.json");
 function verify(value) {
     const obj = record(value, "DENY_RULES_INVALID");
     if (!obj || typeof obj !== "object" || Array.isArray(obj) ||
@@ -169,4 +169,3 @@ export async function createDenyRules({ file = defaultDenyRulesPath(), audit = (
     await snapshot();
     return Object.freeze({ file, snapshot, update, check });
 }
-//# sourceMappingURL=explicit-deny-rules.js.map