starmux 0.10.0 → 0.12.0

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

@@ -0,0 +1,122 @@
+import { createAccessControl } from '../access-control.js';
+import { exists, instancePaths } from '../instance-store.js';
+import { shellQuote } from '../platform.js';
+async function authentication(instance, status) {
+    const file = instancePaths(instance).access;
+    try {
+        const state = await (await createAccessControl(file, { initialize: false })).snapshot();
+        if (status.phase === 'running' && status.health === 'ok' && status.accessMode !== state.mode) {
+            return { mode: null, activeKeys: 0, oauth: null, problem: 'Authentication changed while checking. Run status again.' };
+        }
+        const incomplete = status.phase !== 'running' && instance.requiredAccess !== 'ingress' && state.mode !== instance.requiredAccess;
+        return { mode: state.mode, activeKeys: state.credentials.filter(c => c.status === 'active').length,
+            oauth: state.oauth ? { issuer: state.oauth.issuer, resource: state.oauth.resource, clientId: state.oauth.clientId, scope: state.oauth.scope, tokenAuth: state.oauth.tokenEndpointAuthMethod } : null,
+            problem: incomplete ? `This instance requires ${instance.requiredAccess} authentication before starting.` : null };
+    }
+    catch (error) {
+        // A new, never-started instance has an ingress default, but a lost store must
+        // never be presented as an intentional switch to unauthenticated access.
+        if (error.code === 'ENOENT' && status.phase === 'stopped' && instance.requiredAccess === 'ingress' && !await exists(file + '.initialized')) {
+            return { mode: 'ingress', activeKeys: 0, oauth: null, problem: null };
+        }
+        return { mode: null, activeKeys: 0, oauth: null, problem: 'Authentication settings are unavailable. Inspect them with the Auth command below.' };
+    }
+}
+export async function formatStarmuxStatus(instance, status, config, options = {}) {
+    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';
+    const selector = /^[A-Za-z0-9_.-]+$/.test(instance.name) && !instance.name.startsWith('-') ? instance.name : shellQuote(instance.name);
+    const flag = omitSelector ? '' : (instance.name.startsWith('-') ? ` --instance=${selector}` : ` -i ${selector}`);
+    const command = (action) => `starmux ${action}${flag}`;
+    const ready = status.phase === 'running' && status.health === 'ok';
+    const hasProblem = Boolean(status.configProblem || status.runtimeProblem || auth.problem);
+    const indicator = hasProblem ? '!' : ready ? '●' : status.phase === 'running' ? '◐' : '○';
+    const labels = {
+        ingress: 'None (no token required)',
+        '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 row = (label, value) => '  ' + label.padEnd(16) + value;
+    const codingCmd = command('up --code');
+    const mode = !config
+        ? 'Unavailable'
+        : config.accessRole === 'trusted'
+            ? (config.writeScope === 'home-only' ? 'Coding (Home sandbox · edits, shell & git)' : 'Coding (OS account · edits, shell & git)')
+            : config.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];
+    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));
+    if (ready && status.port && auth.mode === 'oauth' && auth.oauth) {
+        lines.push(row('Client URL', auth.oauth.resource), row('Issuer', auth.oauth.issuer));
+    }
+    if (status.configProblem || status.runtimeProblem)
+        lines.push(row('Problem', status.configProblem ?? status.runtimeProblem));
+    if (auth.problem)
+        lines.push(row('Auth issue', auth.problem));
+    const keyCommand = command('auth key "My AI Client"');
+    if (ready && !auth.problem) {
+        lines.push('', 'Connect an AI client (MCP settings)');
+        lines.push(row('Transport', 'Streamable HTTP'));
+        if (auth.mode === 'ingress') {
+            lines.push(row('URL (Local)', `http://127.0.0.1:${status.port}/mcp  (AI client on this computer)`), row('URL (Remote)', `https://<your-domain-or-tunnel>/mcp  (via protected HTTPS proxy or tunnel -> 127.0.0.1:${status.port})`), row('Authentication', `None  (optional Bearer API key: ${keyCommand})`));
+        }
+        else if (auth.mode === 'api-key') {
+            lines.push(row('URL (Local)', `http://127.0.0.1:${status.port}/mcp  (AI client on this computer)`), row('URL (Remote)', `https://<your-domain-or-tunnel>/mcp  (via protected HTTPS proxy or tunnel -> 127.0.0.1:${status.port})`), row('Authentication', `Bearer API key  (${auth.activeKeys} active ${auth.activeKeys === 1 ? 'key' : 'keys'})`), row('Header', 'Authorization: Bearer <YOUR_API_KEY>'));
+            if (!auth.activeKeys) {
+                lines.push(row('Create key', `${keyCommand}  (no active keys; required before connecting)`));
+            }
+        }
+        else if (auth.mode === 'oauth' && auth.oauth) {
+            lines.push(row('URL (Remote)', auth.oauth.resource), row('Authentication', 'OAuth (browser sign-in)'), row('Issuer', auth.oauth.issuer), row('Client ID', `${auth.oauth.clientId}  (Scope: ${auth.oauth.scope} · Token auth: ${auth.oauth.tokenAuth})`));
+        }
+    }
+    lines.push('', 'Commands');
+    if (auth.problem) {
+        lines.push(row('Check auth', command('auth')));
+    }
+    else if (!ready) {
+        if (status.phase === 'stopped' && !status.configProblem && !status.runtimeProblem) {
+            if (auth.mode === 'api-key' && !auth.activeKeys)
+                lines.push(row('Create key', keyCommand));
+            lines.push(row('Start', command('up')), row('Start coding', codingCmd));
+        }
+        else {
+            lines.push(row('Diagnose', command('doctor')));
+        }
+    }
+    else {
+        if (auth.mode === 'api-key' && auth.activeKeys) {
+            lines.push(row('Verify', `STARMUX_TOKEN=<key> ${command('verify')}`), row('New API key', keyCommand));
+        }
+        else if (auth.mode === 'oauth') {
+            lines.push(row('Check OAuth', command('auth oauth doctor')), row('Verify', command('verify')));
+        }
+        else {
+            lines.push(row('Verify', command('verify')));
+        }
+    }
+    if (status.configState === 'pending')
+        lines.push(row('Apply config', command('config apply')));
+    lines.push(row('Auth & keys', command('auth')));
+    if (ready)
+        lines.push(row('Dashboard', `${command('dashboard')}  (view & copy settings in browser)`));
+    lines.push(row('Logs', command('logs -f')));
+    if (status.phase === 'running')
+        lines.push(row('Stop', command('down')));
+    return lines.join('\n') + '\n';
+}
+//# sourceMappingURL=starmux-status.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"starmux-status.js","sourceRoot":"","sources":["../../../src/cli/starmux-status.ts"],"names":[],"mappings":"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","sourcesContent":["import {createAccessControl} from '../access-control.js';\nimport type {instanceStatus} from '../instance-runtime.js';\nimport {exists,instancePaths,type Instance,type InstanceConfig} from '../instance-store.js';\nimport {shellQuote} from '../platform.js';\n\ntype Status=Awaited<ReturnType<typeof instanceStatus>>;\ntype AuthMode='ingress'|'api-key'|'oauth';\ntype OAuthSummary={issuer:string;resource:string;clientId:string;scope:string;tokenAuth:string};\ntype AuthSummary={mode:AuthMode|null;activeKeys:number;oauth:OAuthSummary|null;problem:string|null};\n\nasync function authentication(instance:Instance,status:Status):Promise<AuthSummary>{\n  const file=instancePaths(instance).access;\n  try{\n    const state=await (await createAccessControl(file,{initialize:false})).snapshot();\n    if(status.phase==='running'&&status.health==='ok'&&status.accessMode!==state.mode){\n      return {mode:null,activeKeys:0,oauth:null,problem:'Authentication changed while checking. Run status again.'};\n    }\n    const incomplete=status.phase!=='running'&&instance.requiredAccess!=='ingress'&&state.mode!==instance.requiredAccess;\n    return {mode:state.mode,activeKeys:state.credentials.filter(c=>c.status==='active').length,\n      oauth:state.oauth?{issuer:state.oauth.issuer,resource:state.oauth.resource,clientId:state.oauth.clientId,scope:state.oauth.scope,tokenAuth:state.oauth.tokenEndpointAuthMethod}:null,\n      problem:incomplete?`This instance requires ${instance.requiredAccess} authentication before starting.`:null};\n  }catch(error){\n    // A new, never-started instance has an ingress default, but a lost store must\n    // never be presented as an intentional switch to unauthenticated access.\n    if((error as NodeJS.ErrnoException).code==='ENOENT'&&status.phase==='stopped'&&instance.requiredAccess==='ingress'&&!await exists(file+'.initialized')){\n      return {mode:'ingress',activeKeys:0,oauth:null,problem:null};\n    }\n    return {mode:null,activeKeys:0,oauth:null,problem:'Authentication settings are unavailable. Inspect them with the Auth command below.'};\n  }\n}\n\nexport async function formatStarmuxStatus(instance:Instance,status:Status,config:InstanceConfig|undefined,options:{isDefault?:boolean}={}){\n  const auth=await authentication(instance,status);\n  // Omit `-i default` for the default instance to keep everyday single-instance output clean.\n  const omitSelector=options.isDefault===true&&instance.name==='default';\n  const selector=/^[A-Za-z0-9_.-]+$/.test(instance.name)&&!instance.name.startsWith('-')?instance.name:shellQuote(instance.name);\n  const flag=omitSelector?'':(instance.name.startsWith('-')?` --instance=${selector}`:` -i ${selector}`);\n  const command=(action:string)=>`starmux ${action}${flag}`;\n  const ready=status.phase==='running'&&status.health==='ok';\n  const hasProblem=Boolean(status.configProblem||status.runtimeProblem||auth.problem);\n  const indicator=hasProblem?'!':ready?'●':status.phase==='running'?'◐':'○';\n  const labels={\n    ingress:'None (no token required)',\n    'api-key':`API key (Bearer token; ${auth.activeKeys} active ${auth.activeKeys===1?'key':'keys'})`,\n    oauth:'OAuth (browser sign-in)'\n  };\n  const saved=status.phase==='running'?' (saved; live state unavailable)':' (saved for next start)';\n  const row=(label:string,value:string)=>'  '+label.padEnd(16)+value;\n  const codingCmd=command('up --code');\n  const mode=!config\n    ?'Unavailable'\n    :config.accessRole==='trusted'\n    ?(config.writeScope==='home-only'?'Coding (Home sandbox · edits, shell & git)':'Coding (OS account · edits, shell & git)')\n    :config.mode==='read-write'\n    ?'File writes (restricted)'\n    :`Read-only  (run '${codingCmd}' to enable edits & shell)`;\n  const runtime=status.executionMode==='background'\n    ?'Background · continues after this terminal closes'\n    :status.executionMode==='foreground-owned'\n    ?(status.runtime?.launcher==='app'?'App-owned · stops when the app closes':'Foreground · Ctrl+C stops this instance')\n    :'Stopped';\n  const title=omitSelector\n    ?`${indicator} Starmux is ${status.phase}`\n    :`${indicator} Starmux is ${status.phase}  (instance: ${instance.name})`;\n  const lines=['',title];\n  if(ready&&status.port){\n    lines.push(row('Listen',`http://127.0.0.1:${status.port}/mcp  (this computer only)`));\n  }\n  lines.push(\n    row('Workspace',config?.projectRoot??'Unavailable'),\n    row('Mode',mode),\n    row('Auth',auth.mode?labels[auth.mode]+(ready?'':saved):'Unavailable'),\n    row('Runtime',runtime)\n  );\n  if(ready&&status.port&&auth.mode==='oauth'&&auth.oauth){\n    lines.push(row('Client URL',auth.oauth.resource),row('Issuer',auth.oauth.issuer));\n  }\n  if(status.configProblem||status.runtimeProblem)lines.push(row('Problem',status.configProblem??status.runtimeProblem!));\n  if(auth.problem)lines.push(row('Auth issue',auth.problem));\n\n  const keyCommand=command('auth key \"My AI Client\"');\n  if(ready&&!auth.problem){\n    lines.push('','Connect an AI client (MCP settings)');\n    lines.push(row('Transport','Streamable HTTP'));\n    if(auth.mode==='ingress'){\n      lines.push(\n        row('URL (Local)',`http://127.0.0.1:${status.port}/mcp  (AI client on this computer)`),\n        row('URL (Remote)',`https://<your-domain-or-tunnel>/mcp  (via protected HTTPS proxy or tunnel -> 127.0.0.1:${status.port})`),\n        row('Authentication',`None  (optional Bearer API key: ${keyCommand})`)\n      );\n    }else if(auth.mode==='api-key'){\n      lines.push(\n        row('URL (Local)',`http://127.0.0.1:${status.port}/mcp  (AI client on this computer)`),\n        row('URL (Remote)',`https://<your-domain-or-tunnel>/mcp  (via protected HTTPS proxy or tunnel -> 127.0.0.1:${status.port})`),\n        row('Authentication',`Bearer API key  (${auth.activeKeys} active ${auth.activeKeys===1?'key':'keys'})`),\n        row('Header','Authorization: Bearer <YOUR_API_KEY>')\n      );\n      if(!auth.activeKeys){\n        lines.push(row('Create key',`${keyCommand}  (no active keys; required before connecting)`));\n      }\n    }else if(auth.mode==='oauth'&&auth.oauth){\n      lines.push(\n        row('URL (Remote)',auth.oauth.resource),\n        row('Authentication','OAuth (browser sign-in)'),\n        row('Issuer',auth.oauth.issuer),\n        row('Client ID',`${auth.oauth.clientId}  (Scope: ${auth.oauth.scope} · Token auth: ${auth.oauth.tokenAuth})`)\n      );\n    }\n  }\n\n  lines.push('','Commands');\n  if(auth.problem){\n    lines.push(row('Check auth',command('auth')));\n  }else if(!ready){\n    if(status.phase==='stopped'&&!status.configProblem&&!status.runtimeProblem){\n      if(auth.mode==='api-key'&&!auth.activeKeys)lines.push(row('Create key',keyCommand));\n      lines.push(row('Start',command('up')),row('Start coding',codingCmd));\n    }else{\n      lines.push(row('Diagnose',command('doctor')));\n    }\n  }else{\n    if(auth.mode==='api-key'&&auth.activeKeys){\n      lines.push(\n        row('Verify',`STARMUX_TOKEN=<key> ${command('verify')}`),\n        row('New API key',keyCommand)\n      );\n    }else if(auth.mode==='oauth'){\n      lines.push(\n        row('Check OAuth',command('auth oauth doctor')),\n        row('Verify',command('verify'))\n      );\n    }else{\n      lines.push(row('Verify',command('verify')));\n    }\n  }\n  if(status.configState==='pending')lines.push(row('Apply config',command('config apply')));\n  lines.push(row('Auth & keys',command('auth')));\n  if(ready)lines.push(row('Dashboard',`${command('dashboard')}  (view & copy settings in browser)`));\n  lines.push(row('Logs',command('logs -f')));\n  if(status.phase==='running')lines.push(row('Stop',command('down')));\n  return lines.join('\\n')+'\\n';\n}\n"]}

package/dist/src/cli/starmux.js

@@ -9,10 +9,12 @@ 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, createInstance, ensureAccessReady, exists, instanceConfigSchema, instancePaths, loadInstanceConfig, parseConfig, patchInstanceConfig, readRegistry, readTrusted, resolveInstance, saveInstanceConfig, suggestPort, validateConfig } from '../instance-store.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 { handle } from './instances.js';
-import { desktopCommanderEntry, packageRoot } from '../runtime-paths.js';
-const version = '0.10.0';
+import { desktopCommanderEntry } from '../runtime-paths.js';
+import { shellQuote } from '../platform.js';
+import { formatStarmuxStatus } from './starmux-status.js';
+const version = '0.12.0';
 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 = {};
@@ -39,22 +41,50 @@ function fail(message) { throw Error(message); }
 const absolute = (value) => path.resolve(value === '~' ? homedir() : value.startsWith('~/') ? path.join(homedir(), value.slice(2)) : value);
 const pause = (ms) => new Promise(resolve => setTimeout(resolve, ms));
 function help() {
-    const topic = command === 'help' ? positional[0] : command;
+    const requested = command === 'help' ? positional[0] : command;
+    const topic = requested === 'stop' ? 'down' : requested;
     const sections = {
         up: 'up [path] [--read | --write | --code] [-y] [--port N] [--foreground]\n  Initialize and start. First use defaults to CWD; later starts reuse saved settings.',
         init: 'init [path] [--read | --write | --code] [-y] [--port N]\n  Save settings without starting. --write and --code enable full account coding permissions.',
-        auth: 'auth\n  auth key "Client name" [--expires 30d]\n  auth mode ingress|api-key|oauth\n  auth revoke ID\n  auth oauth init-keycloak --resource URL --callback URL\n  auth oauth setup --issuer URL --resource URL --client-id ID --subject USER_ID\n  auth oauth doctor',
-        config: 'config show|path|edit|validate|diff|apply|schema|recover\n  config import FILE [-i NAME] [--link] [-y]\n  config copy NEW_NAME -i SOURCE\n  config rename NEW_NAME -i SOURCE\n  config default NAME\n  config archive|restore -i NAME\n  config export --output FILE\n  config relink --file FILE | manage\n  config save --file FILE --revision REV\n  config patch --patch JSON --revision REV [-y]\n  config secret set|remove NAME',
+        auth: 'auth\n  auth key "Client name" [--expires 30d]\n  auth mode none|ingress|api-key|oauth\n  auth revoke ID\n  auth oauth init-keycloak --resource URL --callback URL\n  auth oauth setup --issuer URL --resource URL --client-id ID --subject USER_ID\n  auth oauth doctor',
+        config: 'config [show] [--effective]\n  config edit | diff | apply | validate | path | schema | recover\n  config default NAME | rename NEW_NAME -i SOURCE | copy NEW_NAME -i SOURCE\n  config archive -i NAME | restore -i NAME | import FILE [-i NAME] [--link]\n  config export [--output FILE] | secret set|remove NAME',
         dashboard: 'dashboard [--no-open | --token]\n  Open the local Access console. --no-open prints a private login link.',
-        verify: 'verify [--token-stdin]\n  Test MCP initialization and a directory read. Authenticated instances use STARMUX_TOKEN or stdin.',
+        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 Dashboard.',
-        ls: 'ls [--archived]\n  List local instances.',
-        down: 'down (alias: stop)\n  Stop the selected instance.'
+        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.',
+        privacy: 'privacy [--all] [--target PATH]\n  Check privacy access through the running instance.'
     };
-    process.stdout.write(`Starmux ${version}\n\n${sections[topic ?? ''] ?? 'Connect AI clients to your computer’s files and development tools.\n\n  starmux up [path] [--code]   Start in the background\n  starmux init [path]         Save settings\n  starmux status              Show local endpoints\n  starmux verify | doctor     Check tools or environment\n  starmux logs [-f]           Read logs\n  starmux down                Stop\n  starmux auth                Manage client access\n  starmux dashboard           Open local Access console\n  starmux ls                  List instances\n  starmux config              Advanced configuration\n  starmux migrate             Import an old installation'}\n\nGlobal: -i, --instance NAME_OR_ID   --json   -h, --help\nUse starmux COMMAND --help for details.\nDocumentation: ${path.join(packageRoot, 'docs', 'README.md')}\n`);
+    if (topic && topic !== 'help' && !sections[topic])
+        fail('Unknown command: ' + topic + '. Run starmux --help.');
+    const overview = [
+        'Connect AI clients to your computer’s files, shell and development tools.',
+        '',
+        'Workspace Lifecycle:',
+        '  starmux up [path] [--code]   Start in the background (default: Read-only)',
+        '  starmux down                 Stop the running instance (alias: stop)',
+        '  starmux status               Show health, endpoint and connection guide',
+        '  starmux logs [-f]            View or stream gateway logs',
+        '',
+        'Access & Verification:',
+        '  starmux auth                 Manage auth mode, API keys and OAuth',
+        '  starmux dashboard            Open the local Web Access Console',
+        '  starmux verify               Test local MCP handshake and workspace read',
+        '  starmux doctor               Check runtime, config, port and auth state',
+        '',
+        'Multi-Instance & Config:',
+        '  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'
+    ].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`);
 }
 async function confirm(message) {
     if (yes())
@@ -118,6 +148,16 @@ async function configure() {
     await rememberConsent(instance, config);
     return instance;
 }
+async function isDefaultInstance(instance) {
+    const registry = await readRegistry().catch(() => ({ defaultInstanceId: null, instances: [] }));
+    return instance.name === 'default' && (registry.defaultInstanceId === instance.id || registry.instances.filter(i => !i.archived).length <= 1);
+}
+async function instanceFlag(instance) {
+    if (await isDefaultInstance(instance))
+        return '';
+    const selector = /^[A-Za-z0-9_.-]+$/.test(instance.name) && !instance.name.startsWith('-') ? instance.name : shellQuote(instance.name);
+    return instance.name.startsWith('-') ? `--instance=${selector}` : `-i ${selector}`;
+}
 async function show(instance) {
     const status = await instanceStatus(instance);
     if (json) {
@@ -125,12 +165,7 @@ async function show(instance) {
         return;
     }
     const config = status.phase === 'running' ? status.active?.config : (await loadInstanceConfig(instance).catch(() => null))?.config;
-    process.stdout.write(`\nStarmux · ${instance.name} · ${status.phase}\nWorkspace  ${config?.projectRoot ?? 'Unavailable'}\nMode       ${config?.accessRole === 'trusted' ? (config.writeScope === 'home-only' ? 'Coding (Home sandbox)' : 'Coding (OS account)') : config?.mode === 'read-write' ? 'File writes (restricted)' : 'Read-only'}\nRuntime    ${status.executionMode}\n`);
-    if (status.port && status.phase === 'running')
-        process.stdout.write(`MCP        http://127.0.0.1:${status.port}/mcp\nDashboard  http://127.0.0.1:${status.port}/access\n`);
-    if (status.configProblem || status.runtimeProblem)
-        process.stdout.write(`Problem    ${status.configProblem ?? status.runtimeProblem}\n`);
-    process.stdout.write(`Logs       starmux logs -f -i ${JSON.stringify(instance.name)}\n`);
+    process.stdout.write(await formatStarmuxStatus(instance, status, config, { isDefault: await isDefaultInstance(instance) }));
 }
 async function start(instance) {
     const state = await instanceStatus(instance);
@@ -145,7 +180,7 @@ async function start(instance) {
     if (!await availablePort(config.port))
         fail(`Port ${config.port} is in use. Choose another with starmux up --port PORT.`);
     if (flags.foreground || string('app-parent-pid')) {
-        await runInstance(instance, { json, ...(string('app-parent-pid') ? { appParentPid: Number(string('app-parent-pid')) } : {}) });
+        await runInstance(instance, { json, ...(!json ? { onReady: () => show(instance) } : {}), ...(string('app-parent-pid') ? { appParentPid: Number(string('app-parent-pid')) } : {}) });
         return;
     }
     const log = path.join(instancePaths(instance).logs, 'supervisor.log');
@@ -189,10 +224,13 @@ async function verify(instance) {
         fail('Start this instance with starmux up first.');
     const token = await bearer();
     const client = new Client({ name: 'starmux-verify', version });
-    const transport = new StreamableHTTPClientTransport(new URL(`http://127.0.0.1:${status.port}/mcp`), { requestInit: { headers: token ? { Authorization: 'Bearer ' + token } : {} } });
+    const endpoint = `http://127.0.0.1:${status.port}/mcp`;
+    const transport = new StreamableHTTPClientTransport(new URL(endpoint), { requestInit: { headers: token ? { Authorization: 'Bearer ' + token } : {} } });
+    let toolCount = 0;
     try {
         await client.connect(transport);
-        await client.listTools();
+        const listed = await client.listTools();
+        toolCount = listed.tools.length;
         const result = await client.callTool({ name: 'list_directory', arguments: { path: '.', depth: 0 } });
         if (result.isError)
             fail('Directory read failed.');
@@ -205,8 +243,15 @@ async function verify(instance) {
     }
     if (json)
         print({ result: 'PASS', instanceId: instance.id, port: status.port, remoteClientVerified: false });
-    else
-        process.stdout.write('PASS · MCP handshake, tool discovery and workspace read.\n');
+    else {
+        const cfg = status.active?.config;
+        const mode = cfg?.accessRole === 'trusted' ? 'Coding mode' : 'Read-only mode';
+        const root = cfg?.projectRoot ?? '.';
+        process.stdout.write(`✓ MCP handshake      ${endpoint}\n` +
+            `✓ Tool discovery     ${toolCount} tools available (${mode})\n` +
+            `✓ Workspace read     ${root}\n` +
+            `PASS · MCP handshake, tool discovery and workspace read.\n`);
+    }
 }
 function expires(value) {
     if (!value)
@@ -222,36 +267,85 @@ async function auth(instance) {
     const op = positional[0];
     if (!op) {
         const state = await access.snapshot();
-        if (json)
+        if (json) {
             print(state);
-        else {
-            process.stdout.write(`Authentication: ${state.mode}\n`);
-            for (const c of state.credentials)
-                process.stdout.write(`${c.id}  ${c.name}  ${c.status}\n`);
-            for (const c of state.oauthConnections)
-                process.stdout.write(`${c.id}  OAuth ${c.clientId}  ${c.revokedAt ? 'revoked' : 'active'}\n`);
+            return;
         }
+        const flag = await instanceFlag(instance);
+        const cmd = (action) => `starmux ${action}${flag ? ' ' + flag : ''}`;
+        const activeKeys = state.credentials.filter(c => c.status === 'active').length;
+        const modeDesc = state.mode === 'ingress'
+            ? 'None (no Starmux token · local or ingress proxy)'
+            : state.mode === 'api-key'
+                ? `API key (Bearer token · ${activeKeys} active)`
+                : 'OAuth (browser sign-in)';
+        const lines = [
+            ...(flag ? [`Instance       ${instance.name}`] : []),
+            `Auth mode      ${modeDesc}`,
+            `API keys       ${activeKeys} active (${state.credentials.length} total)`,
+            `OAuth          ${state.oauth ? `${state.oauth.issuer} (${state.oauthConnections.filter(c => !c.revokedAt).length} active sessions)` : 'Not configured'}`
+        ];
+        if (state.credentials.length) {
+            lines.push('', 'API Keys');
+            for (const c of state.credentials) {
+                const exp = c.expiresAt ? `  expires ${c.expiresAt.slice(0, 10)}` : '';
+                lines.push(`  ${c.id.padEnd(26)}  ${c.name.padEnd(20)}  ${c.status}${exp}`);
+            }
+        }
+        if (state.oauthConnections.length) {
+            lines.push('', 'OAuth Sessions');
+            for (const c of state.oauthConnections) {
+                lines.push(`  ${c.id.padEnd(26)}  OAuth ${c.clientId.padEnd(14)}  ${c.revokedAt ? 'revoked' : 'active'}`);
+            }
+        }
+        lines.push('', 'Commands', `  Create API key   ${cmd('auth key "My AI Client"')}`, `  Switch mode      ${cmd('auth mode <none|api-key|oauth>')}`, ...(activeKeys > 0 || state.oauthConnections.some(c => !c.revokedAt) ? [`  Revoke access    ${cmd('auth revoke <ID>')}`] : []));
+        process.stdout.write(lines.join('\n') + '\n');
         return;
     }
     if (op === 'key') {
         const result = await access.create(positional[1] ?? '', expires(string('expires')), true);
         await changeRegistry(async (r) => { r.instances.find(i => i.id === instance.id).requiredAccess = 'api-key'; });
-        if (json)
+        if (json) {
             print({ ...result, mode: 'api-key' });
-        else
-            process.stdout.write(`API key enabled for ${result.name}\nID: ${result.id}\n\n${result.key}\n\nCopy this key now; it is shown once.\n`);
+            return;
+        }
+        const cfg = (await loadInstanceConfig(instance).catch(() => null))?.config;
+        const port = cfg?.port ?? 18893;
+        process.stdout.write(`API key enabled for ${result.name} (ID: ${result.id})\n` +
+            `Copy this key now; it is shown only once:\n\n` +
+            `  ${result.key}\n\n` +
+            `Option A — Fill in AI client form UI:\n` +
+            `  Transport       Streamable HTTP\n` +
+            `  URL (Local)     http://127.0.0.1:${port}/mcp\n` +
+            `  URL (Remote)    https://<your-domain-or-tunnel>/mcp\n` +
+            `  Authentication  Bearer API key\n` +
+            `  Header          Authorization: Bearer ${result.key}\n\n` +
+            `Option B — Or paste JSON config (mcpServers):\n` +
+            `  {\n` +
+            `    "mcpServers": {\n` +
+            `      "starmux": {\n` +
+            `        "type": "streamable-http",\n` +
+            `        "url": "https://<your-domain-or-tunnel>/mcp",\n` +
+            `        "headers": {\n` +
+            `          "Authorization": "Bearer ${result.key}"\n` +
+            `        }\n` +
+            `      }\n` +
+            `    }\n` +
+            `  }\n`);
         return;
     }
     if (op === 'mode') {
-        const mode = positional[1];
+        const raw = positional[1];
+        const mode = raw === 'none' ? 'ingress' : raw;
         if (mode !== 'ingress' && mode !== 'api-key' && mode !== 'oauth')
-            fail('Choose ingress, api-key or oauth.');
+            fail('Choose none (or ingress), api-key or oauth.');
         await access.setMode(mode);
         await changeRegistry(async (r) => { r.instances.find(i => i.id === instance.id).requiredAccess = mode; });
+        const label = mode === 'ingress' ? 'none (ingress)' : mode;
         if (json)
             print(await access.snapshot());
         else
-            process.stdout.write('Authentication: ' + mode + '\n');
+            process.stdout.write('Authentication: ' + label + '\n');
         return;
     }
     if (op === 'revoke') {
@@ -321,15 +415,16 @@ async function logs(instance) {
         fail('--lines must be 1..200.');
     const file = path.join(instancePaths(instance).logs, 'core.log');
     let offset = 0;
-    if (await exists(file)) {
-        const text = await readTrusted(file, true, 32 * 1024 * 1024);
-        offset = Buffer.byteLength(text);
-        const output = text.split('\n').slice(-count).join('\n');
-        if (json)
-            print({ instanceId: instance.id, output });
-        else
-            process.stdout.write(output);
-    }
+    const text = await exists(file) ? await readTrusted(file, true, 32 * 1024 * 1024) : '';
+    offset = Buffer.byteLength(text);
+    const lines = text.split('\n');
+    if (text.endsWith('\n'))
+        lines.pop();
+    const output = lines.slice(-count).join('\n') + (text.endsWith('\n') ? '\n' : '');
+    if (json)
+        print({ instanceId: instance.id, output });
+    else
+        process.stdout.write(output || 'No logs yet.\n');
     if (!flags.follow)
         return;
     let done = false;
@@ -370,6 +465,10 @@ async function logs(instance) {
 async function configCommand() {
     const op = positional[0] ?? 'show';
     const selector = string('instance');
+    if (op === 'schema') {
+        print(configJSONSchema());
+        return;
+    }
     if (op === 'import') {
         const file = positional[1];
         if (!file)
@@ -432,6 +531,57 @@ async function configCommand() {
         args.push('--approve-trusted-developer', '--approve-unrestricted');
     await handle('config', args);
 }
+function validateSubcommand() {
+    if (command !== 'config' && command !== 'auth')
+        return;
+    const op = positional[0] ?? (command === 'config' ? 'show' : '');
+    let name = command + (op ? ' ' + op : '');
+    let count = positional.length - (positional.length ? 1 : 0);
+    let minimum = 0;
+    let maximum = 0;
+    let supported;
+    if (command === 'config') {
+        const commands = { show: ['effective'], path: [], edit: [], validate: [], diff: [], apply: ['revision', 'yes'], schema: [], recover: [],
+            import: ['name', 'link', 'yes'], copy: [], rename: [], default: [], archive: [], restore: [], export: ['output'], relink: ['file'], manage: [],
+            save: ['file', 'revision', 'yes'], patch: ['patch', 'revision', 'yes'], secret: [] };
+        supported = commands[op];
+        if (['import', 'copy', 'rename', 'default'].includes(op))
+            minimum = maximum = 1;
+        if (op === 'relink') {
+            minimum = string('file') ? 0 : 1;
+            maximum = minimum;
+        }
+        if (op === 'secret') {
+            minimum = maximum = 2;
+            if (!['set', 'remove'].includes(positional[1] ?? ''))
+                fail('Usage: starmux config secret set|remove NAME');
+        }
+    }
+    else if (op === 'oauth') {
+        const action = positional[1] ?? 'status';
+        name += ' ' + action;
+        count = Math.max(0, positional.length - 2);
+        const actions = { status: [], doctor: [],
+            'init-keycloak': ['resource', 'callback', 'allow-loopback-http'],
+            setup: ['issuer', 'resource', 'resource-aliases', 'client-id', 'subject', 'subjects', 'registration', 'token-auth', 'allow-loopback-http'] };
+        supported = actions[action];
+        if (flags.subject !== undefined && flags.subjects !== undefined)
+            fail('Use either --subject or --subjects.');
+    }
+    else {
+        const commands = { '': [], key: ['expires'], mode: [], revoke: [] };
+        supported = commands[op];
+        if (['key', 'mode', 'revoke'].includes(op))
+            minimum = maximum = 1;
+    }
+    if (!supported)
+        fail('Unknown command: ' + name + '. See starmux ' + command + ' --help.');
+    if (count < minimum || count > maximum || positional.slice(1).some(value => !value.trim()))
+        fail('Invalid arguments for starmux ' + name + '. See starmux ' + command + ' --help.');
+    for (const key of Object.keys(flags))
+        if (!['instance', 'json', 'help', 'version'].includes(key) && !supported.includes(key))
+            fail('Option --' + key + ' is not supported by ' + name + '.');
+}
 async function main() {
     if (flags.version) {
         process.stdout.write(version + '\n');
@@ -443,15 +593,20 @@ 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'], 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'], migrate: ['yes'],
         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']
     };
     for (const key of Object.keys(flags))
         if (!['instance', 'json', 'help', 'version'].includes(key) && !allowed[command]?.includes(key))
             fail('Option --' + key + ' is not supported by ' + command + '.');
+    if (string('instance') !== undefined && !string('instance').trim())
+        fail('--instance requires a non-empty name or ID.');
+    validateSubcommand();
     if (['status', 'ls', 'down', 'stop', 'logs', 'doctor', 'verify', 'dashboard'].includes(command) && positional.length)
         fail('Unexpected argument: ' + positional[0]);
+    if (command === 'rm' && positional.length > 1)
+        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)
@@ -469,8 +624,10 @@ async function main() {
             await start(instance);
         else if (json)
             print({ result: 'SAVED', instance });
-        else
-            process.stdout.write(`Saved ${instance.name}. Start with starmux up -i ${JSON.stringify(instance.name)}\n`);
+        else {
+            const flag = await instanceFlag(instance);
+            process.stdout.write(`Saved ${instance.name}. Start with starmux up${flag ? ' ' + flag : ''}\n`);
+        }
         return;
     }
     if (command === 'migrate') {
@@ -481,6 +638,11 @@ async function main() {
         await handle('instance', ['list', ...(flags.archived ? ['--archived'] : []), ...(json ? ['--json'] : [])]);
         return;
     }
+    if (command === 'rm') {
+        const target = positional[0] ?? string('instance') ?? (await selected()).id;
+        await handle('instance', ['archive', target, ...(json ? ['--json'] : [])]);
+        return;
+    }
     if (command === 'config') {
         await configCommand();
         return;
@@ -525,8 +687,19 @@ async function main() {
             fail('Configured port is in use: ' + loaded.config.port);
         if (json)
             print({ result: 'PASS', node: process.version, instanceId: instance.id, configState: state.configState });
-        else
-            process.stdout.write('PASS · Node, dependencies, workspace, configuration, port and authentication.\n');
+        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 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` +
+                `✓ Configuration      ${instance.source.path} (${state.configState})\n` +
+                `✓ Authentication     ${authLabel}\n` +
+                `PASS · Node, dependencies, workspace, configuration, port and authentication.\n`);
+        }
     }
     else {
         const args = [...positional, '--instance', instance.id];