@milpa/comal 0.1.3 → 0.1.5

package/README.md

@@ -28,7 +28,7 @@ comal --help
 
 Keep the PATH line in your shell startup file if you use that prefix. If your Node manager already provides a user prefix, you can omit `--prefix "$HOME/.local"`. The package registers the `comal` executable; you do not need to create a shell alias.
 
-You can pin a version with `npx @milpa/comal@0.1.3` or `npm install --global @milpa/comal@0.1.3`. The local release manifest preserves SHA-256 and SHA-512 integrity is checked against npm at publish time. No independent publisher signature is claimed.
+You can pin a version with `npx @milpa/comal@0.1.5` or `npm install --global @milpa/comal@0.1.5`. The local release manifest preserves SHA-256 and SHA-512 integrity is checked against npm at publish time. No independent publisher signature is claimed.
 
 ## Test without account or model
 
@@ -56,6 +56,8 @@ comal --auth-provider codex --name resident
 
 For APIs, set the key via the environment or your secrets manager. Do not paste it in the composer or as an argument. See https://comal.milpahq.com/academy/docs/modelos/ and https://comal.milpahq.com/academy/docs/login/ for profiles and providers.
 
+In the TUI, `/provider` opens a searchable list of workspace profiles and login providers. `/models` lists models from the active provider; `/effort` offers the active model’s supported levels. Use ↑/↓ and Enter to select, or Esc to keep your draft. A pending selection stays distinct from the active connection. Comal checks model/provider candidates before replacing a working connection; failed checks offer explicit recovery without retrying automatically. A catalog check does not prove inference entitlement.
+
 ## Connect your Artifacts account
 
 ```sh
@@ -77,7 +79,7 @@ This removes the client; it keeps project sessions and user credentials. To disc
 
 ## Scope of this first distribution
 
-Installation is verified on Linux, from an empty prefix and HOME. macOS and Windows via WSL2 are paths pending verification in those environments; native Windows support is not claimed. Chrome Lab requires configuring your own SSH/CDP host. The package does not grant access to the author's lab.
+Release acceptance runs the exact archive in empty user state on Linux, macOS arm64 and native Windows. Reports identify the archive hash, OS, Node runtime and checks; successful installation alone does not establish feature parity. On native Windows, cross-session messaging is explicitly unavailable, provider/cloud credential stores still need a Windows ACL implementation, and Bash/Grep require Unix tools. Use WSL for the complete Unix-oriented workflow; WSL and Intel macOS require separate runtime verification. Chrome Lab requires configuring your own SSH/CDP host. The package does not grant access to the author's lab.
 
 The package belongs to the npm organization `@milpa`. `npx comal` corresponds to another project; use the full name `npx @milpa/comal`. A public license, native installers, and publisher signature will be resolved separately with the maintainer. Full documentation: https://comal.milpahq.com/academy/ .
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milpa/comal",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Comal: governed operations, execution receipts, and programming assistance in any language",
   "type": "module",
   "private": false,

package/src/cli.mjs

@@ -33,6 +33,8 @@ import { trustedContext } from './trusted-context.mjs';
 import { contextSettings, resolveContextBudget, estimateRequest } from './compaction.mjs';
 import { modelTimingSettings } from './model-deadline.mjs';
 import { House, houseSnapshot } from './house.mjs';
+import { Operation } from './operations.mjs';
+import { validateConnectionCandidate } from './connection-validation.mjs';
 import { PluginRuntime, parsePluginCommand } from './plugins.mjs';
 import { registerWorkOperations, workProjection } from './work-plan.mjs';
 import { evidenceOperations } from './work-state.mjs';
@@ -352,7 +354,7 @@ async function boot(args, createScreen, setInterrupt, startupSignal) {
   peerBus=new SessionBus({store,getSessionId:()=>session.id,inbound:v.inbound,getMetadata:()=>({name:session.name,model:provider.model,effort:provider.effort || 'auto',authProvider:provider.authProvider,provider:v.demo?'demo':settings.provider,profile:provider.profileName || null,capabilities:sessionCapabilities()}),getAuthority:()=>({cwd,mode:policy.mode,allowed:[...policy.allowed],denied:[...policy.denied],ceilings:peerGuard.ceilings()}),getChain:()=>peerGuard.chain,onEvent});
   const beforeModel=async({signal,source,turn,prompt}={})=>{
     const context={provider,tools:tools.executor,record:event=>store.append(session.id,event),signal};
-    if(turn===1 && ['user','goal'].includes(source))await preparePeerRouting(prompt,{...context,bus:peerBus});
+    if(peerBus.availability?.available!==false && turn===1 && ['user','goal'].includes(source))await preparePeerRouting(prompt,{...context,bus:peerBus});
     const delivered=await peerBus.drain();peerGuard.receive(delivered);
     await preparePeerCapabilities(delivered,context);
     for(const message of delivered)onEvent({type:'peer_message',from:message.from,message:message.content,request_id:message.request_id});return delivered.length+await subagents.incorporate({sessionId:session.id,signal});
@@ -361,11 +363,11 @@ async function boot(args, createScreen, setInterrupt, startupSignal) {
     if (chromeWorkflow) await chromeWorkflow.finishResult(final, context);
     await completePeerReplies(final,{...context,requests:peerGuard.messages,store,sessionId:session.id,tools:tools.executor,record:event=>store.append(session.id,event),onEvent});
   };
-  for(const definition of peerToolDefinitions)registry.add({...definition,native:true,effects:{workspace:'none',external:definition.name==='SendMessage'?'write':'none',process:'none',authority:'none'},run:async(input,options)=>JSON.stringify(definition.name==='ListAgents'?await peerBus.list(input):await peerBus.send(input,options))});
+  for(const definition of (peerBus.availability?.available===false?[]:peerToolDefinitions))registry.add({...definition,native:true,effects:{workspace:'none',external:definition.name==='SendMessage'?'write':'none',process:'none',authority:'none'},run:async(input,options)=>JSON.stringify(definition.name==='ListAgents'?await peerBus.list(input):await peerBus.send(input,options))});
   let providerOperations=[];
-  const publishProviderFeatures=()=>{
-    const definitions=providerFeatureDefinitions(provider).map(definition=>({...definition,effects:{workspace:definition.name==='AnalyzeMedia'?'read':'none',external:definition.name==='ProviderCapabilities'?'none':'read',process:'none',authority:'none'},run:(input,options)=>executeProviderFeature(definition.name,input,{provider,workspace:tools,record:event=>store.append(session.id,event),signal:options.signal,observe:options.observe,invoke:(request,execute)=>activeGoalBudget?activeGoalBudget.complete(request,execute):execute(request)})}));
-    house.registry.replace(providerOperations,definitions);providerOperations=definitions.map(definition=>definition.name);
+  const providerFeaturesFor=next=>providerFeatureDefinitions(next).map(definition=>new Operation({...definition,effects:{workspace:definition.name==='AnalyzeMedia'?'read':'none',external:definition.name==='ProviderCapabilities'?'none':'read',process:'none',authority:'none'},run:(input,options)=>executeProviderFeature(definition.name,input,{provider:next,workspace:tools,record:event=>store.append(session.id,event),signal:options.signal,observe:options.observe,invoke:(request,execute)=>activeGoalBudget?activeGoalBudget.complete(request,execute):execute(request)})}));
+  const publishProviderFeatures=(definitions=providerFeaturesFor(provider))=>{
+    house.registry.replace(providerOperations,definitions);providerOperations=definitions.map(definition=>definition.contract.name);
   };
   publishProviderFeatures();
   const combinedTools = tools.executor;
@@ -641,8 +643,8 @@ async function boot(args, createScreen, setInterrupt, startupSignal) {
     { name: 'SessionMode', description: 'Human changes the permission mode.', input_schema: { type: 'object', properties: { mode: { type: 'string', enum: PERMISSION_MODES } }, required: ['mode'], additionalProperties: false }, run: async ({ mode }) => { policy.mode = mode; await store.append(session.id, { type: 'mode', mode }); return t("Permissions: {v0}", {v0: mode}); } },
     { name:'SessionModel',description:'Human selects a model without replacing session history.',input_schema:{type:'object',properties:{model:{type:'string',minLength:1,maxLength:256}},required:['model'],additionalProperties:false},run:async({model})=>{
       if(!model.trim() || /\s/.test(model))throw new Error(t("Use /model ID, without spaces."));
-      await replaceProvider({...settings,model,effort:'auto'},{refresh:true});
-      return t("Model: {v0} · effort {v1} · same session", {v0: provider.model, v1: provider.effort || 'auto'});
+      const verification=await replaceProvider({...settings,model,effort:'auto'},{refresh:true,validate:true});
+      return t("Model: {v0} · effort {v1} · same session", {v0: provider.model, v1: provider.effort || 'auto'}) + (verification?.compatibilityFallback? ' · '+t('Model catalog unavailable; the active connection is unverified. No inference was sent.'):'');
     }},
     {name:'SessionEffort',description:'Human selects a supported reasoning effort for the next request.',input_schema:{type:'object',properties:{effort:{type:'string',minLength:1,maxLength:16}},required:['effort'],additionalProperties:false},run:async({effort})=>{
       await replaceProvider({...settings,model:provider.model,effort:normalizeEffort(effort)});
@@ -653,8 +655,8 @@ async function boot(args, createScreen, setInterrupt, startupSignal) {
       if(v.demo)throw new Error(t("The demo does not allow changing provider."));
       const selected=profiles.profiles.find(item=>item.name===profile);
       const config=selected ? {provider:selected.provider,profile:selected,namedProfile:true,authProvider:selected.authProvider,model:selected.model,baseURL:selected.baseURL,effort:selected.effort || 'auto',maxTokens:contextConfig.maxTokens} : {...authProviderDefaults(profile),effort:'auto',maxTokens:contextConfig.maxTokens};
-      await replaceProvider(config);
-      return t("Provider: {v0} · {v1} · {v2}", {v0: selected?.name || provider.authProvider, v1: settings.provider, v2: provider.model});
+      const verification=await replaceProvider(config,{validate:true});
+      return t("Provider: {v0} · {v1} · {v2}", {v0: selected?.name || provider.authProvider, v1: settings.provider, v2: provider.model}) + (verification?.compatibilityFallback?' · '+t('Model catalog unavailable; the active connection is unverified. No inference was sent.'):'');
     }},
     {name:'SessionLogin',description:'Human authorizes a provider login. Only the environment variable name is recorded.',input_schema:{type:'object',properties:{provider:{type:'string',enum:AUTH_PROVIDERS.map(item=>item.id)},apiKeyEnv:{type:'string',pattern:'^[A-Za-z_][A-Za-z0-9_]*$'}},required:['provider'],additionalProperties:false},effects:{workspace:'none',external:'unknown',process:'none',authority:'credential_control'},run:async({provider:target,apiKeyEnv})=>loginControl(target+(apiKeyEnv?' --api-key-env '+apiKeyEnv:''))},
     {name:'SessionLogout',description:'Human removes Comal credentials; does not revoke the remote account.',input_schema:{type:'object',properties:{provider:{type:'string',enum:AUTH_PROVIDERS.map(item=>item.id)}},required:['provider'],additionalProperties:false},effects:{workspace:'none',external:'none',process:'none',authority:'credential_control'},run:async({provider:target})=>loginControl(target,true)},
@@ -672,10 +674,12 @@ async function boot(args, createScreen, setInterrupt, startupSignal) {
   } });
   const changeMode = mode => humanTools.execute('SessionMode', { mode });
   let discoveredModels = [], discoveredModelKey = '', discoveredSessions = [], discoveredPeers = [];
+  let authStatus={};
+  const refreshConnections=async()=>{const statuses=await Promise.allSettled(AUTH_PROVIDERS.map(item=>authManager.status(item.id)));authStatus=Object.fromEntries(AUTH_PROVIDERS.map((item,index)=>[item.id,statuses[index].status==='fulfilled'?statuses[index].value.status:'unknown']));};
   const modelDiscoveryKey = () => `${settings.provider}:${provider.baseURL || provider.url || ''}:${provider.model}`;
   const discovery = () => ({
     mode: policy.mode, effortLevels: modelCapabilities?.effort?.levels || ['auto'],
-    capabilities: modelCapabilities, profiles: profiles.profiles.map(({name}) => ({name})),
+    capabilities: modelCapabilities, profiles: profiles.profiles.map(({name,provider,model,authProvider}) => ({name,provider,model,authProvider})),authStatus,
     authProviders: AUTH_PROVIDERS.map(({id,label,method,apiKeyEnv,experimental}) => ({id,label,description: method==='device_code' ? t('Browser sign-in') + (experimental ? ' · '+t('Experimental') : '') : t('Uses environment variable {name}',{name:apiKeyEnv})})),
     mcpServers: mcpRuntime.status().servers.map(({name,status}) => ({name,status})),
     plugins: plugins.status().plugins.map(({id,state,operations,builtin}) => ({id,state,operations,builtin})),
@@ -683,21 +687,29 @@ async function boot(args, createScreen, setInterrupt, startupSignal) {
     models: discoveredModelKey === modelDiscoveryKey() ? discoveredModels : [{id:provider.model}],
     sessions: discoveredSessions, peers: discoveredPeers,agents:[...(ui?.subagentBlocks.values() || [])].map(child=>({id:child.run_id || child.id,description:`${child.runner_state || child.state} / ${child.turn_state || '?'} / ${child.work_state || 'unjudged'} · ${child.description || ''}`})),
   });
-  const metadata = () => ({cwd,sessionId:session.id,name:session.name,model:provider.model,mode:policy.mode,provider:v.demo?'demo':settings.provider,profile:provider.profileName,effort:provider.effort || 'auto',contextBudget:contextBudget(modelCapabilities),modelCapabilities,authProvider:provider.authProvider,workflow:chromeWorkflow?`chrome:${chromeWorkflow.task.project}`:null});
-  const replaceProvider = async (config,{refresh=false}={}) => {
+  const metadata = () => ({cwd,sessionId:session.id,name:session.name,model:provider.model,mode:policy.mode,provider:v.demo?'demo':settings.provider,profile:provider.profileName,effort:provider.effort || 'auto',contextBudget:contextBudget(modelCapabilities),modelCapabilities,authProvider:provider.authProvider,peerAvailability:peerBus.availability,workflow:chromeWorkflow?`chrome:${chromeWorkflow.task.project}`:null});
+  const replaceProvider = async (config,{refresh=false,validate=false}={}) => {
     if(v.demo)throw new Error(t("Change model/effort in a session with a real provider."));
     modelController=new AbortController();const wasBusy=ui?.busy;ui?.setBusy(true);
     const signal=controller?.signal?AbortSignal.any([controller.signal,modelController.signal]):modelController.signal;
     try {
     const next=await instantiate({...config,signal,maxTokens:contextConfig.maxTokens,...(config.provider==='openai'?timing:{})});
     if(typeof next.discoverModel==='function')await next.discoverModel({signal});
+    const verification=validate?await validateConnectionCandidate(next,{signal,explicitModel:typeof config.model==='string' && Boolean(config.model.trim())}):null;
     await setProviderEffort(next,config.effort || 'auto',{signal});
     const report=await inspectModel(next,{signal,force:refresh});report.effort.selected=next.effort;
     effectiveContextWindow(report);
+    if(verification)report.connectionValidation=verification;
+    const features=providerFeaturesFor(next);
+    for(const feature of features)if(house.registry.get(feature.contract.name) && !providerOperations.includes(feature.contract.name))throw Object.assign(new Error('Provider operation conflicts with an existing contract.'),{code:'PROVIDER_OPERATION_CONFLICT'});
     const identityChanged=provider.model!==next.model || settings.provider!==config.provider || (provider.baseURL || String(provider.url))!==(next.baseURL || String(next.url));
     signal?.throwIfAborted();await persistProvider(next,config,report);
-    provider=next;settings={...config,model:next.model};modelCapabilities=report;publishProviderFeatures();agent.providerName=settings.provider;agent.compactor.contextWindow=effectiveContextWindow(report);if(identityChanged)agent.compactor.factor=1;
-    ui?.updateMetadata(metadata());await peerBus.setState(controller?'busy':'idle');
+    provider=next;settings={...config,model:next.model};modelCapabilities=report;publishProviderFeatures(features);agent.providerName=settings.provider;agent.compactor.contextWindow=effectiveContextWindow(report);if(identityChanged)agent.compactor.factor=1;
+    // The durable provider row is the commit boundary. Cancellation after it
+    // cannot truthfully report that the previous connection was retained.
+    ui?.updateMetadata(metadata());
+    try{await peerBus.setState(controller?'busy':'idle');}catch{ui?.notice(t('Connection applied; live-session presence could not be refreshed.'),true);}
+    return verification;
     }finally{modelController=null;if(ui)ui.setBusy(wasBusy);}
   };
   const loginControl=async(name,logout=false)=>{
@@ -711,6 +723,7 @@ async function boot(args, createScreen, setInterrupt, startupSignal) {
     finally{authController=null;if(ui)ui.setBusy(wasBusy);}
   };
   const backend = {
+    refreshConnections,
     async listModels({signal}={}) {
       const key=modelDiscoveryKey();
       const models=await listProviderModels(provider,{signal});
@@ -831,6 +844,8 @@ async function boot(args, createScreen, setInterrupt, startupSignal) {
   };
   try {
     await peerBus.start();
+    if(peerBus.availability?.available===false){const note=t('Cross-session messaging is unavailable on this platform. Local work remains available.');if(ui)ui.notice(note,true);else stderr.write(note+'\n');}
+    await refreshConnections();
     await saveProvider();
     await lifecycle.execute('PluginInitialize', { trust: Boolean(v['trust-plugins']) }, { signal: startupSignal });
     await lifecycle.execute('McpInitialize', { trust: Boolean(v['trust-mcp']) }, { signal: startupSignal });

package/src/connection-validation.mjs

@@ -0,0 +1,49 @@
+import {listProviderModels} from './model-controls.mjs';
+
+const NETWORK_CODES = new Set(['ECONNREFUSED', 'ENOTFOUND', 'EHOSTUNREACH', 'EAI_AGAIN', 'ECONNRESET', 'ETIMEDOUT', 'UND_ERR_CONNECT_TIMEOUT']);
+function rejected(code, message, status) {
+  return Object.assign(new Error(message), {code, ...(status ? {status} : {})});
+}
+
+// A catalog response proves only the read-only connection check. It cannot prove
+// that inference, a particular model or paid/account entitlements will succeed.
+// The candidate remains detached; this helper neither persists nor selects it.
+export async function validateConnectionCandidate(provider, {signal, explicitModel = false, timeoutMs = 10000} = {}) {
+  if (!provider || typeof provider.model !== 'string' || !provider.model.trim()) throw rejected('CONNECTION_MODEL_REQUIRED', 'Choose a model before applying this connection.');
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000) throw new TypeError('Connection validation timeout must be between 1 and 30000 milliseconds.');
+  if (typeof provider.listModels !== 'function' && !(typeof provider.fetch === 'function' && (provider.baseURL || provider.url))) {
+    throw rejected('CONNECTION_CATALOG_UNSUPPORTED', 'This provider cannot check its model catalog.');
+  }
+  const timeout = AbortSignal.timeout(timeoutMs), bounded = signal ? AbortSignal.any([signal, timeout]) : timeout;
+  let onAbort;
+  try {
+    bounded.throwIfAborted();
+    const interrupted = new Promise((resolve, reject) => {
+      onAbort = () => reject(rejected(timeout.aborted && !signal?.aborted ? 'CONNECTION_TIMEOUT' : 'ABORT_ERR', timeout.aborted && !signal?.aborted ? 'Connection validation timed out.' : 'Connection validation cancelled.'));
+      bounded.addEventListener('abort', onAbort, {once: true});
+    });
+    const models = await Promise.race([listProviderModels(provider, {signal: bounded}), interrupted]);
+    bounded.throwIfAborted();
+    return {verified: true, catalogVerified: true, modelAdvertised: models.some(item => item.id === provider.model.replace(/^models\//, '')),
+      compatibilityFallback: false, source: 'model_catalog', inferenceVerified: false};
+  } catch (error) {
+    if (signal?.aborted) throw Object.assign(rejected('ABORT_ERR', 'Connection validation cancelled.'), {name: 'AbortError'});
+    if (timeout.aborted || error?.name === 'TimeoutError' || ['ETIMEDOUT', 'UND_ERR_CONNECT_TIMEOUT'].includes(error?.code)) {
+      throw Object.assign(rejected('CONNECTION_TIMEOUT', 'Connection validation timed out.'), {name: 'TimeoutError'});
+    }
+    // Native adapters may keep the HTTP code in a structured diagnostic rather
+    // than error.status. Read the integer only, never their upstream payload.
+    const status = [error?.status, error?.details?.http_status].find(value => Number.isInteger(value) && value >= 100 && value <= 599);
+    if (explicitModel === true && [404, 405].includes(status)) {
+      return {verified: false, catalogVerified: false, modelAdvertised: null, compatibilityFallback: true,
+        source: 'catalog_unavailable', inferenceVerified: false, metadataStatus: status};
+    }
+    const networkCode = [error?.code, error?.cause?.code].find(code => NETWORK_CODES.has(code));
+    if (networkCode) throw rejected(networkCode, 'The model server could not be reached.');
+    if ([401, 403].includes(status) || ['PROVIDER_AUTH_REQUIRED', 'AUTH_REQUIRED', 'UNAUTHENTICATED'].includes(error?.code)) throw rejected('CONNECTION_AUTH_REQUIRED', 'The model server refused authentication. Sign in or choose another connection.', status);
+    if (status) throw rejected('CONNECTION_CATALOG_HTTP', 'The model catalog is unavailable. The active connection was not changed.', status);
+    throw rejected('CONNECTION_VALIDATION_FAILED', 'The model catalog could not be checked. The active connection was not changed.');
+  } finally {
+    if (onAbort) bounded.removeEventListener('abort', onAbort);
+  }
+}

package/src/i18n/es.mjs

@@ -245,5 +245,69 @@ export default Object.freeze({
   "Provider: {provider}. The selected model applies to the next call; active work keeps its model.": "Proveedor: {provider}. El modelo elegido se aplica a la siguiente llamada; el trabajo activo conserva su modelo.",
   "No options found. Check the provider or use /model ID.": "No hay opciones. Revisa el proveedor o usa /model ID.",
   "The provider changed. Open the model list again.": "El proveedor cambió. Abre de nuevo la lista de modelos.",
-  "Selection queued. It will apply after the current turn.": "Selección en cola. Se aplicará al terminar el turno actual."
+  "Selection queued. It will apply after the current turn.": "Selección en cola. Se aplicará al terminar el turno actual.",
+  "Signed in": "Sesión iniciada",
+  "Credentials configured": "Credenciales configuradas",
+  "Not signed in": "Sin sesión iniciada",
+  "Sign-in expired": "Inicio de sesión vencido",
+  "Authentication status unknown": "Estado de autenticación desconocido",
+  "Workspace profile": "Perfil del espacio de trabajo",
+  "Choose a provider": "Elige un proveedor",
+  "Choose a workspace profile or login provider. The connection is checked before replacing the active provider.": "Elige un perfil del espacio de trabajo o un proveedor de inicio de sesión. Se comprueba la conexión antes de reemplazar el proveedor activo.",
+  "{count} input tokens": "{count} tokens de entrada",
+  "Choose effort": "Elige el esfuerzo",
+  "This model does not announce configurable effort. Auto uses the provider default.": "Este modelo no anuncia esfuerzo configurable. Auto usa el valor predeterminado del proveedor.",
+  "Only levels announced by the active model are offered. Auto uses the provider default.": "Solo se ofrecen los niveles anunciados por el modelo activo. Auto usa el valor predeterminado del proveedor.",
+  "Effort support is unknown. Only auto is available; use /capabilities refresh to check.": "El soporte de esfuerzo es desconocido. Solo está disponible auto; usa /capabilities refresh para comprobarlo.",
+  "Current effort {effort} is not in the announced levels.": "El esfuerzo actual {effort} no está entre los niveles anunciados.",
+  "Current effort is unknown. Auto is the safe default.": "El esfuerzo actual es desconocido. Auto es el valor predeterminado seguro.",
+  "Provider default; no explicit effort is sent.": "Valor predeterminado del proveedor; no se envía un esfuerzo explícito.",
+  "Announced by the active model": "Anunciado por el modelo activo",
+  "Connection change queued. The active connection stays in use.": "Cambio de conexión en cola. Se sigue usando la conexión activa.",
+  "Checking the selected connection before applying it.": "Comprobando la conexión elegida antes de aplicarla.",
+  "Connection change applied.": "Cambio de conexión aplicado.",
+  "Connection change cancelled.": "Cambio de conexión cancelado.",
+  "Connection change failed. The previous connection is still active.": "Falló el cambio de conexión. La conexión anterior sigue activa.",
+  "Connection change could not be confirmed. Check the active connection before trying again.": "No se pudo confirmar el cambio de conexión. Revisa la conexión activa antes de volver a intentarlo.",
+  "Connection change not applied": "Cambio de conexión no aplicado",
+  "Connection status needs review": "El estado de conexión requiere revisión",
+  "Keep the active connection": "Conservar la conexión activa",
+  "Return to your draft without changing the connection.": "Vuelve a tu borrador sin cambiar la conexión.",
+  "Retry this selection": "Reintentar esta selección",
+  "Sign in to the selected provider": "Iniciar sesión con el proveedor elegido",
+  "Choose another connection": "Elegir otra conexión",
+  "Open the provider and workspace profile selector.": "Abre el selector de proveedores y perfiles del espacio de trabajo.",
+  "Sign in or check the configured credential environment variable.": "Inicia sesión o revisa la variable de entorno configurada para las credenciales.",
+  "The model server timed out.": "Se agotó el tiempo de espera del servidor del modelo.",
+  "The model server could not be reached.": "No se pudo contactar al servidor del modelo.",
+  "The active model does not support this setting.": "El modelo activo no admite esta configuración.",
+  "The change could not be verified.": "No se pudo verificar el cambio.",
+  "Checking /{command} {target} · active: {model}": "Comprobando /{command} {target} · activo: {model}",
+  "Queued /{command} {target} · active: {model}": "En cola /{command} {target} · activo: {model}",
+  "Connection applied; live-session presence could not be refreshed.": "Conexión aplicada; no se pudo actualizar la presencia de la sesión en vivo.",
+  "Model catalog unavailable; the active connection is unverified. No inference was sent.": "Catálogo de modelos no disponible; la conexión activa no está verificada. No se envió ninguna inferencia.",
+  "Cross-session messaging is unavailable on this platform. Local work remains available.": "Los mensajes entre sesiones no están disponibles en esta plataforma. El trabajo local sigue disponible.",
+  "Attach up to two images per message.": "Adjunta hasta dos imágenes por mensaje.",
+  "The session changed; the image was not attached.": "La sesión cambió; no se adjuntó la imagen.",
+  "Checking vision support…": "Comprobando soporte de visión…",
+  "{count} image(s) attached · Backspace removes a label": "{count} imagen(es) adjunta(s) · Retroceso elimina una etiqueta",
+  "This model cannot receive images or vision is unverified. Switch model or remove the image before sending.": "Este modelo no puede recibir imágenes o la visión no está verificada. Cambia de modelo o elimina la imagen antes de enviar.",
+  "Attaching image…": "Adjuntando imagen…",
+  "The session changed; the message was not sent.": "La sesión cambió; no se envió el mensaje.",
+  "Image not sent: the current model does not support verified vision.": "Imagen no enviada: el modelo actual no tiene soporte de visión verificado.",
+  "Use a plain message with images; commands do not accept image attachments.": "Usa un mensaje normal con imágenes; los comandos no aceptan imágenes adjuntas.",
+  "Choose a connection": "Elige una conexión",
+  "Setup values support up to 4096 bytes.": "Los valores de configuración admiten hasta 4096 bytes.",
+  "Connection settings": "Configuración de conexión",
+  "Connecting": "Conectando",
+  "Use at most 4096 bytes.": "Usa un máximo de 4096 bytes.",
+  "Check the value and try again.": "Revisa el valor e inténtalo de nuevo.",
+  "Ctrl+C cancels": "Ctrl+C cancela",
+  "Ctrl+C exits": "Ctrl+C sale",
+  "↑/↓ choose · Enter continues · Esc back": "↑/↓ elige · Enter continúa · Esc vuelve",
+  "Enter continues · Esc back": "Enter continúa · Esc vuelve",
+  "Esc back": "Esc vuelve",
+  "Working…": "Trabajando…",
+  "Checking…": "Comprobando…",
+  "The draft changed while preparing the image. Press Enter again to send the current draft.": "El borrador cambió mientras se preparaba la imagen. Pulsa Enter de nuevo para enviar el borrador actual."
 });

package/src/model-controls.mjs

@@ -16,10 +16,17 @@ function headers(provider) {
     ? { 'x-api-key': provider.apiKey, 'anthropic-version': '2023-06-01' }
     : { 'x-goog-api-key': provider.apiKey };
 }
-async function json(provider, url, { signal, ...options } = {}) {
+async function json(provider, url, { signal, throwHttp = false, ...options } = {}) {
   const timeout = AbortSignal.timeout(3000);
   const response = await provider.fetch(url, { ...options, headers: { 'content-type': 'application/json', ...headers(provider) }, signal: signal ? AbortSignal.any([signal, timeout]) : timeout, redirect: 'error' });
-  if (!response.ok) { await response.body?.cancel(); return null; }
+  if (!response.ok) {
+    try { await response.body?.cancel(); } catch {}
+    // Optional capability probes can still be absent. A user-requested catalog
+    // check must distinguish unsupported routes from refused authentication or
+    // an unavailable server, without retaining an error body or request URL.
+    if (throwHttp) throw Object.assign(new Error('The model catalog request was refused.'), {code: 'MODEL_DISCOVERY_HTTP', status: response.status});
+    return null;
+  }
   const reader = response.body?.getReader();
   if (!reader) return null;
   let text = '', size = 0; const decoder = new TextDecoder();
@@ -43,8 +50,8 @@ export async function listProviderModels(provider, { signal } = {}) {
   do {
     const url = new URL(base(provider));
     if (next) url.searchParams.set(protocol(provider) === 'gemini' ? 'pageToken' : 'after_id', next);
-    const data = await json(provider, url.href, { signal });
-    if (!data) throw Object.assign(new Error('The server did not allow listing models.'), { code: 'MODEL_DISCOVERY_UNAVAILABLE' });
+    const data = await json(provider, url.href, { signal, throwHttp: true });
+    if (!data || (!Array.isArray(data.data) && !Array.isArray(data.models))) throw Object.assign(new Error('The server did not return a model catalog.'), { code: 'MODEL_DISCOVERY_UNAVAILABLE' });
     for (const item of Array.isArray(data.data) ? data.data : Array.isArray(data.models) ? data.models : []) { const safe = safeModel(item); if (safe && !models.some(model => model.id === safe.id)) models.push(safe); }
     next = protocol(provider) === 'gemini' ? data.nextPageToken : data.has_more ? data.last_id : '';
   } while (next && ++pages < 8 && models.length < 1024);

package/src/session-bus.mjs

@@ -60,13 +60,18 @@ function mailbox(rows) {
 /** Local, same-user IPC. The private registry authenticates live instances; it is
  * not a sandbox against other programs already running as this OS user. */
 export class SessionBus {
-  constructor({ store, getSessionId, getMetadata = () => ({}), getAuthority = () => ({}), getChain = () => ({}), directory = process.env.COMAL_PEER_DIR || path.join(os.homedir(), '.local/state/comal/peers'), inbound, onPending, onEvent, timeoutMs = 5000, ttlMs = TTL } = {}) {
+  constructor({ store, getSessionId, getMetadata = () => ({}), getAuthority = () => ({}), getChain = () => ({}), directory = process.env.COMAL_PEER_DIR || path.join(os.homedir(), '.local/state/comal/peers'), inbound, onPending, onEvent, timeoutMs = 5000, ttlMs = TTL, platform = process.platform } = {}) {
     if (!store || typeof getSessionId !== 'function') throw new TypeError('SessionBus requiere store y getSessionId.');
     if (inbound !== undefined && !['accept', 'hold', 'refuse'].includes(inbound)) throw fail('PEER_INBOUND_INVALID', 'Usa accept, hold o refuse.');
     Object.assign(this, { store, getSessionId, getMetadata, getAuthority, getChain, directory: path.resolve(directory), onPending, onEvent, timeoutMs, ttlMs: Math.min(TTL, Math.max(10, ttlMs)) });
+    this.availability = Object.freeze(platform === 'win32' ? { available: false, transport: 'none', code: 'PEER_PLATFORM_UNSUPPORTED', reason: 'Cross-session messaging is unavailable on native Windows; the current IPC requires POSIX private directories and Unix sockets.' } : { available: true, transport: 'unix' });
     this.state = 'idle'; this.inbound = inbound || 'accept'; this.inboundOverride = inbound; this.inboundConfigured = new Set(); this.sockets = new Set(); this._starting = undefined;
   }
+  _requireSupported() {
+    if (!this.availability.available) throw Object.assign(fail(this.availability.code, this.availability.reason), { availability: this.availability });
+  }
   async _directory() {
+    this._requireSupported();
     await mkdir(this.directory, { recursive: true, mode: 0o700 });
     const stat = await lstat(this.directory);
     if (!stat.isDirectory() || stat.isSymbolicLink() || (uid() !== undefined && stat.uid !== uid()) || (stat.mode & 0o077)) throw fail('PEER_DIRECTORY_UNSAFE', 'El directorio de peers debe pertenecer al usuario y tener permisos 0700, sin symlinks.');
@@ -128,6 +133,10 @@ export class SessionBus {
     throw fail('PEER_SESSION_IN_USE', 'La sesión está iniciando en otra instancia.');
   }
   async start() {
+    if (!this.availability.available) {
+      if (!this._unavailableReported) { this._unavailableReported = true; this._event({ type: 'peer_unavailable', ...this.availability }); }
+      return this;
+    }
     if (this._starting) return this._starting;
     this._starting = this._start();
     try { return await this._starting; } finally { this._starting = undefined; }
@@ -205,6 +214,7 @@ export class SessionBus {
   }
   async send(input = {}, { signal } = {}) { return this._send(input, { signal }); }
   async _send(input = {}, { signal, kind = 'message', chain, inheritedAuthority } = {}) {
+    this._requireSupported();
     await this.start(); if (signal?.aborted) throw fail('ABORT_ERR', 'Envío cancelado.');
     const { to, message, request_id = randomUUID(), reply_to, notify_when_idle = false, required_capabilities = [] } = input;
     if ((typeof message !== 'string' || !message.trim()) && !notify_when_idle) throw fail('PEER_MESSAGE_REQUIRED', 'Se requiere un mensaje o notify_when_idle.');
@@ -301,11 +311,13 @@ export class SessionBus {
     return result;
   }
   async pending() {
+    if (!this.availability.available) return { count: 0, held: 0, total: 0, ...this.availability };
     const id = this.getSessionId(); this._paths(id); const state = mailbox((await this.store.load(id)).rows);
     const held = state.live.filter(item => item.held && !state.released.has(item.message_id)).length;
     return { count: this.inbound==='accept' ? state.live.length - held : 0, held, total: state.live.length };
   }
   async drain() {
+    if (!this.availability.available) return [];
     const id = this.getSessionId(); this._paths(id);
     if (this.inbound !== 'accept') return [];
     return this.store.workTransaction(id, async () => {
@@ -322,6 +334,7 @@ export class SessionBus {
     });
   }
   async releaseHeld(id = 'all') {
+    this._requireSupported();
     const sessionId = this.getSessionId(); this._paths(sessionId);
     const count = await this.store.workTransaction(sessionId, async () => {
       const state = mailbox((await this.store.load(sessionId)).rows); let released = 0;
@@ -331,6 +344,7 @@ export class SessionBus {
     if (count && this.inbound === 'accept') this._signal(); return { released: count };
   }
   async setInbound(value) {
+    this._requireSupported();
     if (!['accept', 'hold', 'refuse'].includes(value)) throw fail('PEER_INBOUND_INVALID', 'Usa accept, hold o refuse.');
     const id = this.getSessionId(); this._paths(id);
     const previous = this._inboundSetting || Promise.resolve();
@@ -350,7 +364,7 @@ export class SessionBus {
     if (!['busy', 'idle'].includes(value)) throw fail('PEER_STATE_INVALID', 'Usa busy o idle.');
     this.state = value; if (this.server) await this._publish();
     if (value === 'idle' && this.server && this.inbound === 'accept') await this._notifyIdle();
-    return { state: this.state };
+    return { state: this.state, ...(!this.availability.available ? this.availability : {}) };
   }
   async _notifyIdle() {
     if (this.notifying || !this.server) return; this.notifying = true;

package/src/tui/connection-options.mjs

@@ -0,0 +1,111 @@
+import { t } from '../i18n/index.mjs';
+import { EFFORT_LEVELS } from '../model-controls.mjs';
+import { safeText } from './text.mjs';
+
+// These snapshots are presentation data, not credentials or executable command
+// fragments. Never change an identifier while sanitizing its display label.
+const controls = /[\s\x00-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/u;
+const id = value => typeof value === 'string' && value.length > 0 && value.length <= 256 && !controls.test(value) ? value : null;
+const text = (value, length = 240) => typeof value === 'string'
+  ? safeText(value).replace(/[\u202a-\u202e\u2066-\u2069]/gu, '').replace(/\s+/gu, ' ').trim().slice(0, length) : '';
+const list = values => Array.isArray(values) ? values.slice(0, 1024) : [];
+const join = values => values.filter(Boolean).join(' · ');
+const unique = values => [...new Map(values.map(value => [value.id, value])).values()];
+
+function authState(provider, discovery) {
+  const snapshots = discovery.authStatus;
+  const snapshot = Array.isArray(snapshots) ? snapshots.find(item => item?.provider === provider.id)
+    : snapshots && typeof snapshots === 'object' ? snapshots[provider.id] : null;
+  const value = provider.status ?? (typeof snapshot === 'string' ? snapshot : snapshot?.status);
+  const states = { authenticated: t('Signed in'), configured: t('Credentials configured'), logged_out: t('Not signed in'), expired: t('Sign-in expired') };
+  return typeof value === 'string' && Object.hasOwn(states, value) ? states[value] : t('Authentication status unknown');
+}
+
+function authItems(discovery) {
+  const seen = new Set();
+  return list(discovery.authProviders).flatMap(value => {
+    const provider = typeof value === 'string' ? { id: value } : value;
+    const key = id(provider?.id);
+    if (!key || seen.has(key)) return [];
+    seen.add(key);
+    return [{ id: key, label: text(provider.label, 100) || key, description: join([key, authState(provider, discovery), text(provider.description)]), kind: 'auth' }];
+  });
+}
+
+function providerItems(discovery) {
+  const seen = new Set();
+  const profiles = list(discovery.profiles).flatMap(value => {
+    const profile = typeof value === 'string' ? { name: value } : value;
+    const key = id(profile?.name);
+    if (!key || seen.has(key)) return [];
+    seen.add(key);
+    const authProvider = id(profile.authProvider);
+    const auth = authProvider && list(discovery.authProviders).find(value => value?.id === authProvider);
+    return [{ id: key, label: key, description: join([t('Workspace profile'), text(profile.provider || profile.protocol, 40), text(profile.model, 100), authProvider ? authState(auth || { id: authProvider }, discovery) : t('Authentication status unknown'), text(profile.description)]), kind: 'profile' }];
+  });
+  // /provider resolves configured names first; the picker must show exactly the
+  // same choice instead of a second, misleading builtin with the same argument.
+  return [...profiles, ...authItems(discovery).filter(value => !seen.has(value.id))];
+}
+
+/** Build an inert, searchable connection menu from an already-read snapshot.
+ * Opening this helper performs no auth, filesystem, model or network requests.
+ * Current is actual metadata only: an unavailable current effort is described,
+ * never silently replaced by an invented selectable capability.
+ */
+export function connectionOptions(kind, { discovery = {}, metadata = {}, filter = '' } = {}) {
+  if (kind === 'models') kind = 'model';
+  let title, description, items, current;
+  if (kind === 'login') {
+    title = t('Sign in to a model provider');
+    description = t('Choose how to authenticate. Your Comal account for Artifacts is separate.');
+    items = authItems(discovery);
+    // Being active is independent of being authenticated; do not mark a login
+    // as a no-op merely because that provider is already selected.
+    current = id(metadata.authProvider);
+  } else if (kind === 'provider') {
+    title = t('Choose a provider');
+    description = t('Choose a workspace profile or login provider. The connection is checked before replacing the active provider.');
+    items = providerItems(discovery);
+    current = id(metadata.profile);
+    if (!current) {
+      const auth = id(metadata.authProvider);
+      if (items.some(item => item.id === auth && item.kind === 'auth')) current = auth;
+    }
+  } else if (kind === 'model') {
+    title = t('Choose a model');
+    description = t('Provider: {provider}. The selected model applies to the next call; active work keeps its model.', { provider: text(metadata.profile || metadata.authProvider || metadata.provider, 100) || 'openai' });
+    current = id(metadata.model);
+    const seen = new Set();
+    items = list(discovery.models).flatMap(value => {
+      const model = typeof value === 'string' ? { id: value } : value;
+      const key = id(model?.id);
+      if (!key || seen.has(key)) return [];
+      seen.add(key);
+      const limit = Number.isSafeInteger(model.inputTokenLimit) && model.inputTokenLimit > 0 ? t('{count} input tokens', { count: model.inputTokenLimit }) : '';
+      return [{ id: key, label: key, description: join([text(model.display_name || model.displayName), limit]), kind: 'model' }];
+    });
+  } else if (kind === 'effort') {
+    title = t('Choose effort');
+    const report = discovery.capabilities || metadata.modelCapabilities;
+    const capability = report?.effort;
+    const stale = report?.model && metadata.model && report.model !== metadata.model;
+    const supported = stale ? null : capability?.supported;
+    // Explicit unsupported/stale metadata outranks an older autocomplete list.
+    const announced = stale || supported === false ? [] : capability?.levels ?? discovery.effortLevels;
+    const levels = new Set(list(announced));
+    const selectable = EFFORT_LEVELS.filter(level => level === 'auto' || levels.has(level));
+    current = EFFORT_LEVELS.includes(metadata.effort) ? metadata.effort : null;
+    description = supported === false ? t('This model does not announce configurable effort. Auto uses the provider default.')
+      : !stale && (supported === true || selectable.length > 1) ? t('Only levels announced by the active model are offered. Auto uses the provider default.')
+      : t('Effort support is unknown. Only auto is available; use /capabilities refresh to check.');
+    if (current && !selectable.includes(current)) description += ' ' + t('Current effort {effort} is not in the announced levels.', { effort: current });
+    if (!current) description += ' ' + t('Current effort is unknown. Auto is the safe default.');
+    items = selectable.map(level => ({ id: level, label: level, description: level === 'auto' ? t('Provider default; no explicit effort is sent.') : t('Announced by the active model'), kind: 'effort' }));
+  } else throw new TypeError('Unknown connection selector.');
+
+  const term = text(filter, 256).toLocaleLowerCase();
+  items = unique(items).map(item => ({ ...item, current: item.id === current, noOp: kind !== 'login' && item.id === current, ...(item.id === current ? { badge: t('Current') } : {}) }))
+    .filter(item => !term || `${item.id} ${item.label} ${item.description}`.toLocaleLowerCase().includes(term));
+  return { title, description, items, selected: items.some(item => item.id === current) ? current : undefined, command: kind, current };
+}

package/src/tui/connection-transition.mjs

@@ -0,0 +1,134 @@
+// UI projection only. Admission, persistence, authentication and actual provider
+// replacement remain the responsibility of the queue and local control boundary.
+const COMMANDS = new Set(['model', 'provider', 'effort', 'login', 'logout']);
+const CHANGES = new Set(['model', 'provider', 'effort']);
+const TERMINAL = new Set(['applied', 'failed', 'cancelled']);
+const REASONS = new Set(['cancelled', 'timeout', 'authentication', 'unavailable', 'unsupported', 'unknown', 'superseded']);
+const KEYS = ['provider', 'authProvider', 'profile', 'model', 'effort'];
+const MESSAGES = Object.freeze({
+  pending: 'Connection change queued. The active connection stays in use.',
+  applying: 'Checking the selected connection before applying it.',
+  applied: 'Connection change applied.',
+  cancelled: 'Connection change cancelled.',
+  failed: 'Connection change failed. The previous connection is still active.',
+  uncertain: 'Connection change could not be confirmed. Check the active connection before trying again.',
+});
+
+function label(value) {
+  if (typeof value !== 'string') return '';
+  // Never render terminal escapes or URL credentials/query strings in a status.
+  let text = value.replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '').replace(/[\x00-\x1f\x7f-\x9f]/g, '');
+  text = text.replace(/https?:\/\/[^\s]+/gi, '[endpoint]');
+  return [...text].slice(0, 120).join('');
+}
+function selection(value = {}) {
+  return Object.fromEntries(KEYS.filter(key => typeof value[key] === 'string').map(key => [key, label(value[key])]));
+}
+function action(value) {
+  if (!value || !COMMANDS.has(value.command) || typeof value.argument !== 'string') throw new TypeError('Invalid connection action.');
+  const argument = value.argument.trim();
+  if (!argument || argument.length > 512 || /[\x00-\x1f\x7f-\x9f]/.test(argument)) throw new TypeError('Invalid connection argument.');
+  if (['model', 'effort'].includes(value.command) && /\s/.test(argument)) throw new TypeError('Connection selection must be one identifier.');
+  if (['login', 'logout'].includes(value.command) && !/^[a-z][a-z0-9_-]*(?: --api-key-env [A-Za-z_][A-Za-z0-9_]*)?$/.test(argument)) throw new TypeError('Invalid credential control action.');
+  return {command: value.command, argument};
+}
+
+export function connectionAction(text) {
+  if (typeof text !== 'string') return null;
+  const match = /^\/(model|provider|effort|login|logout)\s+([^\r\n]+)$/.exec(text.trim());
+  if (!match || match[1]==='login' && match[2] === 'status') return null;
+  try { return action({command: match[1], argument: match[2]}); } catch { return null; }
+}
+
+// Intentionally ignores error.message, stack, HTTP response bodies and URLs.
+export function connectionFailureReason(error) {
+  if (error?.name === 'AbortError' || error?.code === 'ABORT_ERR') return 'cancelled';
+  if (error?.name === 'TimeoutError' || ['ETIMEDOUT', 'UND_ERR_CONNECT_TIMEOUT', 'MODEL_TIMEOUT'].includes(error?.code)) return 'timeout';
+  if ([401, 403].includes(error?.status) || ['AUTH_REQUIRED', 'UNAUTHENTICATED','PROVIDER_AUTH_REQUIRED','CONNECTION_AUTH_REQUIRED'].includes(error?.code)) return 'authentication';
+  if(Number.isInteger(error?.status) && error.status>=500)return 'unavailable';
+  if (['ECONNREFUSED', 'ENOTFOUND', 'EHOSTUNREACH', 'EAI_AGAIN'].includes(error?.code)) return 'unavailable';
+  if (['MODEL_CONTROL_UNSUPPORTED', 'MODEL_EFFORT_UNAVAILABLE', 'UNSUPPORTED_EFFORT'].includes(error?.code)) return 'unsupported';
+  return 'unknown';
+}
+
+export class ConnectionTransitions {
+  constructor(active = {}, {limit = 64} = {}) {
+    if (!Number.isInteger(limit) || limit < 1 || limit > 256) throw new TypeError('Invalid connection history limit.');
+    this.active = selection(active); this.limit = limit; this.records = new Map();
+    this.sequence = 0; this.latestApplied = 0;
+  }
+  admit(id, requested, {queued = true} = {}) {
+    if (typeof id !== 'string' || !/^[A-Za-z0-9_.:-]{1,128}$/.test(id) || this.records.has(id)) throw new TypeError('Connection action ID must be new.');
+    const intent = action(requested);
+    // Keep unfinished actions: history pressure must never hide queued controls.
+    if (this.records.size >= this.limit) {
+      const oldest = [...this.records.values()].find(record => TERMINAL.has(record.state));
+      if (!oldest) throw new Error('Connection action history is full.');
+      this.records.delete(oldest.id);
+    }
+    this.records.set(id, {id, intent, queued: Boolean(queued), state: 'pending', attempt: null, sequence: 0, revision: 0, unchanged: false, reason: null});
+    return this.get(id);
+  }
+  revisePending(id, requested) {
+    const record = this.records.get(id);
+    if (!record || record.state !== 'pending') return false;
+    const intent = action(requested);
+    if (record.intent.command === intent.command && record.intent.argument === intent.argument) return false;
+    record.intent = intent; record.revision++;
+    return true;
+  }
+  start(id) {
+    const record = this.records.get(id);
+    if (!record || record.state !== 'pending') return null;
+    record.state = 'applying'; record.attempt = ++this.sequence; record.sequence = record.attempt;
+    return record.attempt;
+  }
+  complete(id, attempt, {outcome, active, unchanged = false, reason, error} = {}) {
+    const record = this.records.get(id);
+    if (!record || record.state !== 'applying' || record.attempt !== attempt) return false;
+    if (!['applied', 'failed', 'cancelled'].includes(outcome)) throw new TypeError('Explicit connection outcome required.');
+    // A late result may close its card but cannot roll back a newer application.
+    if (attempt < this.latestApplied) {
+      record.state = 'cancelled'; record.reason = 'superseded'; record.unchanged = false;
+      return false;
+    }
+    if (outcome === 'applied') {
+      if (!active || typeof active !== 'object') throw new TypeError('Applied connection requires authoritative metadata.');
+      this.active = selection(active); this.latestApplied = attempt;
+    }
+    record.state = outcome; record.unchanged = outcome !== 'applied' && unchanged === true;
+    record.reason = outcome === 'applied' ? null : REASONS.has(reason) ? reason : connectionFailureReason(error);
+    return true;
+  }
+  cancel(id) {
+    const record = this.records.get(id);
+    // Removing a queued item is certain. An in-flight login/provider operation
+    // must settle at its actual control boundary, never by optimistic UI cancel.
+    if (!record || record.state !== 'pending') return false;
+    record.state = 'cancelled'; record.reason = 'cancelled'; record.unchanged = true;
+    return true;
+  }
+  canRetry(id) {
+    const record = this.records.get(id);
+    return Boolean(record?.state === 'failed' && record.queued && record.unchanged && CHANGES.has(record.intent.command));
+  }
+  retry(id, newId, {confirmed = false} = {}) {
+    if (confirmed !== true || !this.canRetry(id)) return null;
+    const previous = this.records.get(id), intent = {...previous.intent};
+    this.admit(newId, intent); this.records.get(newId).retryOf = id;
+    // This is a new admission proposal, not execution or a queue mutation.
+    return {...intent, text: `/${intent.command} ${intent.argument}`, retryOf: id, id: newId};
+  }
+  get(id) {
+    const record = this.records.get(id); if (!record) return null;
+    const uncertain = ['failed', 'cancelled'].includes(record.state) && !record.unchanged && record.reason !== 'superseded';
+    return {id: record.id, revision: record.revision, command: record.intent.command, target: label(record.intent.argument), state: record.state,
+      message: MESSAGES[uncertain ? 'uncertain' : record.state], reason: record.reason,
+      confirmedUnchanged: record.unchanged, retryable: this.canRetry(id),
+      ...(record.retryOf ? {retryOf: record.retryOf} : {})};
+  }
+  snapshot() {
+    const changes = [...this.records.keys()].map(id => this.get(id));
+    return {active: {...this.active}, pending: changes.filter(item => ['pending', 'applying'].includes(item.state)), changes, latest: changes.at(-1) || null};
+  }
+}

package/src/tui/controller.mjs

@@ -9,6 +9,9 @@ import { shellCommands } from '../auto-guard.mjs';
 import { findImageCandidates } from '../image-attachments.mjs';
 import { Composer } from './composer.mjs';
 import { isRemoteCommand } from '../remote-commands.mjs';
+import { randomUUID } from 'node:crypto';
+import { connectionOptions } from './connection-options.mjs';
+import { ConnectionTransitions, connectionAction, connectionFailureReason } from './connection-transition.mjs';
 
 const IMMEDIATE = new Set(['cloud', 'remote-control', 'rc', 'help', 'copy', 'select', 'status', 'context', 'tools', 'house', 'state', 'audit', 'board', 'tasks', 'work', 'operations', 'plugins', 'sessions', 'resume', 'clear', 'model', 'models', 'effort', 'capabilities', 'login', 'logout', 'permissions', 'rename', 'table', 'queue', 'agents', 'mcp','list-agents','inbox','providers','provider', 'exit', 'quit']);
 
@@ -28,12 +31,25 @@ export class InteractiveController {
   attachSession(session) {
     this.session = session; this.ui.loadSession(session); this.ui.updateMetadata(this.backend.metadata());
     const id = session.id;
+    this.connections=new ConnectionTransitions(this.backend.metadata());this.connectionItems=new Map();
     this.queue = new MessageQueue(session.queue, snapshot => this.backend.saveQueue(id, snapshot));
     this.runner = new QueueRunner(this.queue, async item => {
       if(item.remote){await this.backend.validateRemote(item);if(item.text.trimStart().startsWith('/')&&!isRemoteCommand(item.text))throw new Error('This command is only available in the local terminal.');}
       this.ui.setBusy(true);
-      try { return await this.backend.execute(item.text, { userIntent: item.text, attachments: item.attachments || [], shouldYield: () => this.queue.items.length > 0 }); }
-      finally { this.ui.setBusy(false); }
+      const change=this.connectionItems.get(item.id),attempt=change?this.connections.start(change.id):null,before=this.connectionIdentity();
+      this.syncConnectionStatus();
+      try {
+        const result=await this.backend.execute(item.text,{userIntent:item.text,attachments:item.attachments || [],shouldYield:()=>this.queue.items.length>0});
+        if(change && attempt!==null){
+          const failed=Boolean(result),unchanged=before===this.connectionIdentity() && ['model','provider','effort'].includes(change.action.command);
+          this.connections.complete(change.id,attempt,{outcome:failed?'failed':'applied',active:this.backend.metadata(),unchanged});
+          if(failed)this.scheduleConnectionRecovery(change.id,change.action);
+        }
+        return result;
+      }catch(error){
+        if(change && attempt!==null){this.connections.complete(change.id,attempt,{outcome:connectionFailureReason(error)==='cancelled'?'cancelled':'failed',active:this.backend.metadata(),unchanged:before===this.connectionIdentity() && ['model','provider','effort'].includes(change.action.command),error});this.scheduleConnectionRecovery(change.id,change.action);}
+        throw error;
+      }finally {this.ui.setBusy(false);this.ui.updateMetadata(this.backend.metadata());this.syncConnectionStatus();}
     }, { blocked: () => Boolean(this.peerProcessing || this.ui.selecting || this.modalOverlay() || this.ui.editingQueue || this.switching || this.closed), onChange: () => { this.syncQueue(); this.refreshDiscovery(); }, onError: error => this.ui.notice(error.message, true) });
     this.syncQueue(); this.refreshDiscovery();
     if (this.queue.items.length || this.queue.interrupted.length) this.ui.notice(t("The recovered queue is paused. Check F4 before resuming; interrupted messages were not resent."));
@@ -47,7 +63,7 @@ export class InteractiveController {
       finally{this.ui.setBusy(false);}
     })().catch(error=>this.ui.notice(error.message,true)).finally(()=>{this.peerProcessing=null;this.runner.kick();});
   }
-  syncQueue() { this.ui.setQueue(this.queue.snapshot()); if (this.ui.overlay?.kind === 'queue') this.ui.overlay.index = Math.min(this.ui.overlay.index, Math.max(0, this.queue.items.length - 1)); }
+  syncQueue() { this.syncConnectionQueue();this.ui.setQueue(this.queue.snapshot()); if (this.ui.overlay?.kind === 'queue') this.ui.overlay.index = Math.min(this.ui.overlay.index, Math.max(0, this.queue.items.length - 1)); }
   scheduleDraft(text, attachments = this.ui.composer.attachments || []) {
     clearTimeout(this.draftTimer); this.pendingDraft = { id: this.session.id, text, attachments };
     this.draftTimer = setTimeout(() => { this.flushDraft().catch(e => this.ui.notice(e.message, true)); }, 500);
@@ -155,7 +171,7 @@ export class InteractiveController {
     }
     if (['rc','remote-control'].includes(command) && ['', 'start'].includes(arg.trim()))await this.requireIdle();
     if (command === 'help') { this.ui.showHelp(); return; }
-    if (command==='models' || command==='model' && !arg.trim() || command==='login' && !arg.trim()) return this.chooseConnection(command,arg);
+    if (command==='models' || ['model','login','provider','effort'].includes(command) && !arg.trim()) return this.chooseConnection(command,arg);
     if (command === 'sessions' || (command === 'resume' && !arg)) { this.ui.showSessions(await this.backend.listSessions()); return; }
     if (command === 'resume' || command === 'clear') {
       await this.requireIdle(); this.switching = true;
@@ -174,6 +190,7 @@ export class InteractiveController {
     }
     if(command==='work'&&(arg.trim()==='recover'||arg.trim().startsWith('review '))){await this.requireIdle();const output=await this.backend.control(command,arg);if(output)this.ui.notice(output);return;}
     if (['board', 'tasks', 'work'].includes(command)) { this.ui.showBoard(JSON.parse(await this.backend.control('board', ''))); return; }
+    if(connectionAction(`/${command} ${arg}`)){await this.requireIdle();return this.connectionControl(command,arg);}
     if (['cloud', 'model', 'effort', 'provider', 'login', 'logout'].includes(command) && (arg.trim() || ['login', 'logout'].includes(command))) await this.requireIdle();
     if (command === 'table') { if (!arg) throw new Error(t("Use /table file.csv|tsv|json|md.")); const table = await this.backend.readTable(arg); this.ui.addTable(table.text, table.format, arg); return; }
     const changing=(['cloud','model','effort','provider','login','logout'].includes(command) && (arg.trim() || ['login','logout'].includes(command))) || (['rc','remote-control'].includes(command) && ['', 'start'].includes(arg.trim()));
@@ -184,42 +201,88 @@ export class InteractiveController {
     } finally {if(changing){this.switching=false;this.runner.kick();}}
 
   }
+  connectionIdentity() {
+    const meta=this.backend.metadata();return JSON.stringify(['provider','authProvider','profile','model','effort'].map(key=>meta[key] || null));
+  }
+  syncConnectionStatus() {if(this.connections)this.ui.setConnectionStatus?.(this.connections.snapshot());}
+  syncConnectionQueue() {
+    if(!this.connections || !this.queue)return;
+    const live=new Set([...this.queue.items,this.queue.running].filter(Boolean).map(item=>item.id));
+    for(const item of this.queue.items){
+      const action=connectionAction(item.text),old=this.connectionItems.get(item.id);
+      if(old?.text===item.text)continue;
+      if(action){
+        if(old && this.connections.get(old.id)?.state==='pending'){this.connections.revisePending(old.id,action);this.connectionItems.set(item.id,{...old,text:item.text,action});}
+        else {const id=old?randomUUID():item.id;this.connections.admit(id,action);this.connectionItems.set(item.id,{id,text:item.text,action});}
+      }else if(old){this.connections.cancel(old.id);this.connectionItems.set(item.id,{...old,text:item.text});}
+    }
+    for(const [queueId,change]of this.connectionItems)if(!live.has(queueId)){this.connections.cancel(change.id);this.connectionItems.delete(queueId);}
+    this.syncConnectionStatus();
+  }
+  async connectionControl(command,argument){
+    const requested=connectionAction(`/${command} ${argument}`),id=randomUUID(),before=this.connectionIdentity();
+    this.connections.admit(id,requested);const attempt=this.connections.start(id);this.switching=true;this.syncConnectionStatus();
+    let failure;
+    try{
+      const output=await this.backend.control(command,argument);if(output)this.ui.notice(output);
+      this.connections.complete(id,attempt,{outcome:'applied',active:this.backend.metadata()});
+      try{await this.backend.refreshConnections?.();}catch{}
+    }catch(error){
+      const reason=connectionFailureReason(error);this.connections.complete(id,attempt,{outcome:reason==='cancelled'?'cancelled':'failed',active:this.backend.metadata(),unchanged:before===this.connectionIdentity() && ['model','provider','effort'].includes(command),error});failure=error;
+    }finally{this.switching=false;this.ui.updateMetadata(this.backend.metadata());this.refreshDiscovery();this.syncConnectionStatus();this.runner.kick();}
+    if(failure){const state=this.connections.get(id);this.ui.notice(t(state.message),true);await this.recoverConnection(id,requested);}
+  }
+  scheduleConnectionRecovery(id,action){
+    const runner=this.runner;
+    // Finishing a queued control persists its outcome asynchronously. Wait for
+    // that boundary; one event-loop tick can still find the runner occupied.
+    Promise.resolve(runner.processing).catch(()=>{}).then(()=>{
+      if(this.runner===runner)setImmediate(()=>this.recoverConnection(id,action).catch(()=>{}));
+    });
+  }
+  async recoverConnection(id,action){
+    if(this.closed || this.ui.busy || this.runner.processing || this.modalOverlay() || this.ui.permission)return;
+    const state=this.connections.get(id);if(state?.state!=='failed')return;
+    const items=[{id:'keep',label:t('Keep the active connection'),description:t('Return to your draft without changing the connection.')}];
+    if(state.retryable)items.push({id:'retry',label:t('Retry this selection'),description:`/${action.command} ${state.target}`});
+    const discovery=this.backend.discovery?.() || {},profile=discovery.profiles?.find(p=>p.name===action.argument);
+    const loginProvider=profile?.authProvider || (discovery.authProviders?.some(p=>p.id===action.argument)?action.argument:null);
+    if(state.reason==='authentication' && action.command==='provider' && loginProvider)items.push({id:'login',label:t('Sign in to the selected provider'),description:loginProvider});
+    items.push({id:'choose',label:t('Choose another connection'),description:t('Open the provider and workspace profile selector.')});
+    const reason={authentication:'Sign in or check the configured credential environment variable.',timeout:'The model server timed out.',unavailable:'The model server could not be reached.',unsupported:'The active model does not support this setting.',unknown:'The change could not be verified.'}[state.reason];
+    const choice=await this.ui.setupChoice({title:t(state.confirmedUnchanged?'Connection change not applied':'Connection status needs review'),description:t(state.message)+(reason?'\n\n'+t(reason):''),items});
+    if(this.closed)return;
+    if(choice==='retry' && this.connections.canRetry(id))await this.submit(`/${action.command} ${action.argument}`);
+    else if(choice==='login')await this.submit(`/login ${loginProvider}`);
+    else if(choice==='choose')await this.chooseConnection('provider');
+    this.runner.kick();
+  }
   async chooseConnection(command, filter='') {
     if(this.modalOverlay() || this.ui.permission)return;
-    const identity=()=>JSON.stringify([this.session.id,...['provider','authProvider','profile','model'].map(key=>this.backend.metadata()[key])]);
-    const original=identity(), abort=new AbortController();let selected;
-    try {
-      let items, current, title, description;
-      if(command==='login'){
-        const providers=this.backend.discovery?.().authProviders || [];
-        items=providers.map(p=>({id:p.id,label:p.label || p.id,description:`${p.id} · ${p.description || ''}`}));
-        title=t('Sign in to a model provider');description=t('Choose how to authenticate. Your Comal account for Artifacts is separate.');
-      }else{
+    const identity=()=>JSON.stringify([this.session.id,this.connectionIdentity()]),original=identity(),abort=new AbortController();
+    try{
+      await this.backend.refreshConnections?.();
+      let discovery=this.backend.discovery?.() || {};
+      if(['model','models'].includes(command)){
         this.ui.setupStatus({title:t('Finding models'),description:t('Reading the current provider catalog. No task is sent. Esc cancels.')});
-        const previous=this.ui.callbacks.onSetupCancel;
-        this.ui.callbacks.onSetupCancel=()=>abort.abort();
+        const state=this.ui.setup,previous=this.ui.callbacks.onSetupCancel;this.ui.callbacks.onSetupCancel=()=>abort.abort();
         let models;
-        try {models=await this.backend.listModels({signal:abort.signal});}
-        finally {this.ui.callbacks.onSetupCancel=previous;this.ui.clearSetup();}
+        try{models=await this.backend.listModels({signal:abort.signal});}
+        finally{this.ui.callbacks.onSetupCancel=previous;if(this.ui.setup===state)this.ui.clearSetup();}
         if(abort.signal.aborted || this.closed || identity()!==original)return;
-        this.refreshDiscovery();
-        const meta=this.backend.metadata();current=meta.model;
-        items=models.filter(item=>!filter || item.id.toLowerCase().includes(filter.trim().toLowerCase())).map(m=>({id:m.id,label:m.id,badge:m.id===current?t('Current'):'',description:[m.display_name || m.displayName,m.inputTokenLimit?`${m.inputTokenLimit} input tokens`:null].filter(Boolean).join(' · ')}));
-        title=t('Choose a model');description=t('Provider: {provider}. The selected model applies to the next call; active work keeps its model.',{provider:meta.authProvider || meta.profile || meta.provider || 'openai'});
+        this.refreshDiscovery();discovery={...(this.backend.discovery?.() || {}),models};
       }
-      if(!items.length){this.ui.notice(t('No options found. Check the provider or use /model ID.'),true);return;}
-      items=[...new Map(items.map(item=>[item.id,item])).values()];
-      selected=await this.ui.setupChoice({title,description,items,selected:current,searchable:true,signal:abort.signal});
+      const menu=connectionOptions(command,{discovery,metadata:this.backend.metadata(),filter});
+      if(!menu.items.length){this.ui.notice(t('No options found. Check the provider or use /model ID.'),true);return;}
+      const selected=await this.ui.setupChoice({...menu,searchable:true,signal:abort.signal});
       if(!selected || this.closed)return;
       if(identity()!==original)throw new Error(t('The provider changed. Open the model list again.'));
-      if(command!=='login' && selected===current)return;
-      // Re-enter normal admission: a busy model/login change is queued, never
-      // applied by a picker or while an inference call is in progress.
-      await this.submit(`/${command==='login'?'login':'model'} ${selected}`);
-      if(this.ui.busy)this.ui.notice(t('Selection queued. It will apply after the current turn.'));
-    } catch(error) {if(!abort.signal.aborted)throw error;}
-    finally {this.runner.kick();}
+      if(menu.items.find(item=>item.id===selected)?.noOp)return;
+      await this.submit(`/${menu.command} ${selected}`);
+    }catch(error){if(!abort.signal.aborted)throw error;}
+    finally{this.runner.kick();}
   }
+
   async action(name, arg) {
     if (name === 'exit') return this.exit();
     if (name === 'interrupt') { this.backend.interrupt(); await this.queue.setPaused(true); this.syncQueue(); return; }

package/src/tui/screen.mjs

@@ -179,6 +179,15 @@ export class TerminalScreen {
   motionEnabled() { return brandMotionEnabled({ env: this.env, stream: this.output }); }
   brandFrame() { return Math.floor((Date.now() - this.brandStarted) / BRAND_FRAME_INTERVAL_MS); }
   spinner() { return SPINNER[(this.motionEnabled() ? this.frame : 0) % SPINNER.length]; }
+  setConnectionStatus(snapshot) { this.connectionStatus=structuredClone(snapshot);this.schedule(); }
+  connectionHint() {
+    const snapshot=this.connectionStatus;if(!snapshot)return '';
+    const pending=snapshot.pending?.find(item=>item.state==='applying') || snapshot.pending?.[0];
+    if(pending)return t(pending.state==='applying'?'Checking /{command} {target} · active: {model}':'Queued /{command} {target} · active: {model}',{command:pending.command,target:pending.target,model:safeText(this.metadata.model || '?')}) + (snapshot.pending.length>1?` · +${snapshot.pending.length-1}`:'');
+    const latest=snapshot.latest;
+    if(latest?.state==='failed')return t(latest.message);
+    return '';
+  }
   setDiscovery(context = {}) { this.discovery = structuredClone(context); this.schedule(); }
   discoveryContext() { return { ...this.discovery, effortLevels: this.metadata.modelCapabilities?.effort?.levels || this.discovery.effortLevels, busy: this.busy, queue: this.queue, mode: this.mode, selecting: this.selecting, editingQueue: this.editingQueue }; }
   refreshDiscovery() { this.callbacks.onDiscover?.(); }
@@ -661,7 +670,7 @@ export class TerminalScreen {
     const footer = [clip(bar, columns), tone.muted('─'.repeat(columns)), composerHeading];
     const offset = Math.max(0, composer.cursorRow - composerHeight + 1);
     const inputLines = Array.from({ length: composerHeight }, (_, i) => tone.muted(i === 0 ? ' ❯ ' : ' │ ') + (composer.lines[offset + i] || ''));
-    const hints = this.selecting ? tone.warning(t(" SELECTION · Drag and copy from your terminal · F5/Esc returns")) : this.attachmentStatus ? (['unsupported','invalid'].includes(this.attachmentStatus.state) ? tone.warning : tone.muted)(' ' + safeText(this.attachmentStatus.message)) : tone.muted(' ' + (completions.items.length ? t("Tab or Enter completes · ↑/↓ chooses · Esc closes · does not send") : (this.overlay?.kind === 'help' ? t("Help open · composer active · PgUp/PgDn scrolls · Esc/F1 closes") : this.preparedDraft ? t("Action prepared · Esc recovers your draft · Enter sends and restores it") : contextualTip(this.composer.text, this.discoveryContext()))));
+    const hints = this.selecting ? tone.warning(t(" SELECTION · Drag and copy from your terminal · F5/Esc returns")) : this.attachmentStatus ? (['unsupported','invalid'].includes(this.attachmentStatus.state) ? tone.warning : tone.muted)(' ' + safeText(this.attachmentStatus.message)) : tone.muted(' ' + (completions.items.length ? t("Tab or Enter completes · ↑/↓ chooses · Esc closes · does not send") : (this.overlay?.kind === 'help' ? t("Help open · composer active · PgUp/PgDn scrolls · Esc/F1 closes") : this.preparedDraft ? t("Action prepared · Esc recovers your draft · Enter sends and restores it") : (this.connectionHint() || contextualTip(this.composer.text, this.discoveryContext())))));
     const suggestionLines = [];
     if (completionHeight) {
       suggestionLines.push(tone.muted(t("  Suggestions · {v0} · Tab completes", {v0: completions.items.length})));