@shardflux/cli 0.14.0 → 0.14.1

package/dist/acp-models.js

@@ -0,0 +1,161 @@
+import { createHash } from 'node:crypto';
+import { projectIdentity } from "./project-identity.js";
+import { savedMachine } from "./filesystem-state.js";
+import { syncAgentConfig } from "./agent-config-sync.js";
+import { seedAgentRepository } from "./agent-repository.js";
+import { createConversationRecord, conversationWorkspace } from "./conversations.js";
+import { AgentStateStore } from "./agent-state.js";
+import { objectValue } from "./acp-rpc.js";
+import { nativeCurrentModel, nativeModelOptions } from "./acp-catalog.js";
+/** No prompts, login, logout or credential writes. Every child process group is
+ * terminated, including initialization failures and interrupted clients. */
+export const ACP_MODELS_SCRIPT = String.raw `
+const {spawn}=require('node:child_process');
+const {createInterface}=require('node:readline');
+async function catalog(app){
+ const child=spawn(app==='codex'?'codex-acp':'claude-agent-acp',[],{
+  cwd:process.cwd(),env:{...process.env,SF_ACP_MODEL_DISCOVERY:'1'},detached:true,stdio:['pipe','pipe','pipe']});
+ const pending=new Map();let seq=0;
+ const kill=signal=>{try{process.kill(-child.pid,signal);}catch{}};
+ const interrupt=()=>kill('SIGKILL');
+ const terminate=()=>{kill('SIGKILL');process.exit(143);};
+ process.on('exit',interrupt);process.on('SIGTERM',terminate);process.on('SIGINT',terminate);
+ const closed=new Promise(resolve=>child.once('close',resolve));
+ const fail=error=>{for(const p of pending.values())p.reject(error);pending.clear();};
+ child.on('error',fail);child.on('exit',()=>fail(Error(app+' adapter exited')));
+ child.stdin.on('error',fail);
+ child.stderr.resume();
+ const lines=createInterface({input:child.stdout});
+ lines.on('line',line=>{
+  let m;try{m=JSON.parse(line);}catch{return;}
+  if(m.method&&m.id!==undefined){child.stdin.write(JSON.stringify({jsonrpc:'2.0',id:m.id,error:{code:-32601,message:'Catalog discovery has no client tools'}})+'\n');return;}
+  const p=pending.get(m.id);if(!p)return;pending.delete(m.id);
+  if(m.error)p.reject(Error(m.error.message));else p.resolve(m.result);
+ });
+ function rpc(method,params){return new Promise((resolve,reject)=>{
+  const id=++seq;pending.set(id,{resolve,reject});
+  child.stdin.write(JSON.stringify({jsonrpc:'2.0',id,method,params})+'\n');
+ });}
+ const timer=setTimeout(()=>{fail(Error(app+' model discovery timed out'));kill('SIGKILL');},45000);
+ try{
+  const init=await rpc('initialize',{protocolVersion:1,clientInfo:{name:'shardflux-models',version:'1'},clientCapabilities:{fs:{readTextFile:false,writeTextFile:false},terminal:false}});
+  const session=await rpc('session/new',{cwd:process.cwd(),mcpServers:[]});
+  return {agentInfo:init.agentInfo,configOptions:session.configOptions,models:session.models};
+ }finally{
+  clearTimeout(timer);lines.close();kill('SIGTERM');
+  const force=setTimeout(()=>kill('SIGKILL'),1000);
+  await closed;clearTimeout(force);kill('SIGKILL');
+  process.removeListener('exit',interrupt);process.removeListener('SIGTERM',terminate);process.removeListener('SIGINT',terminate);
+ }
+}
+(async()=>{
+ const results=Object.fromEntries(await Promise.all(['claude','codex'].map(async app=>{
+  try{return [app,await catalog(app)];}catch(e){return [app,{error:String(e.message)}];}
+ })));
+ process.stdout.write(JSON.stringify(results)+'\n');
+})().catch(e=>{process.stderr.write(e.message+'\n');process.exitCode=1;});
+`;
+const modelKey = (scope, app) => JSON.stringify([scope.apiUrl, scope.organizationId, app, scope.template]);
+export function acpScope(apiUrl, ws) {
+    if (!ws.organization_id || !ws.template.slug || !Number.isInteger(ws.template.version))
+        throw new Error('Conversation allocation omitted its account or template identity.');
+    return { apiUrl, organizationId: ws.organization_id, template: `${ws.template.slug}@${ws.template.immutable_version ?? ws.template.version}` };
+}
+/** Model payloads are account/harness/template scoped. The credential fingerprint
+ * only locates the last verified binding; it is never stored or logged in clear. */
+export class AcpModelCache {
+    #store;
+    constructor(dir) { this.#store = new AgentStateStore(dir); }
+    #bindingKey(ctx, folder) {
+        const p = ctx.store.profile(ctx.apiUrl);
+        const credential = ctx.io.env.SHARDFLUX_API_KEY?.trim() || p.api_key?.token || ctx.io.env.SHARDFLUX_SESSION_TOKEN?.trim() || p.session?.token;
+        const authority = createHash('sha256').update(credential ?? 'no-credential').digest('hex');
+        const project = projectIdentity(folder);
+        return JSON.stringify([ctx.apiUrl, authority, project.remote ?? `file://${project.folder}`]);
+    }
+    lookup(ctx, folder) {
+        const doc = this.#store.read(), binding = objectValue(doc.acp_model_bindings)[this.#bindingKey(ctx, folder)];
+        if (!binding?.scope || binding.scope.apiUrl !== ctx.apiUrl)
+            return;
+        const catalog = this.read(binding.scope);
+        return Object.keys(catalog).length ? { scope: binding.scope, catalog } : undefined;
+    }
+    remember(ctx, folder, scope) {
+        const key = this.#bindingKey(ctx, folder);
+        this.#store.update(doc => { doc.acp_model_bindings = { ...objectValue(doc.acp_model_bindings), [key]: { scope } }; });
+    }
+    read(scope) {
+        const entries = objectValue(this.#store.read().acp_model_cache), catalog = {};
+        for (const app of ['claude', 'codex']) {
+            const session = objectValue(entries[modelKey(scope, app)]);
+            if (nativeModelOptions(session).length) {
+                nativeCurrentModel(session);
+                catalog[app] = session;
+            }
+        }
+        return catalog;
+    }
+    write(scope, catalog) {
+        this.#store.update(doc => {
+            const entries = { ...objectValue(doc.acp_model_cache) };
+            for (const app of ['claude', 'codex']) {
+                const session = catalog[app];
+                if (!session || !nativeModelOptions(session).length) {
+                    delete entries[modelKey(scope, app)];
+                    continue;
+                }
+                nativeCurrentModel(session);
+                // Never persist initialize auth status, MCP credentials or a native
+                // session identity. Only the model configuration belongs in this cache.
+                entries[modelKey(scope, app)] = { configOptions: [{ id: 'model', category: 'model', type: 'select',
+                            currentValue: nativeCurrentModel(session), options: nativeModelOptions(session) }] };
+            }
+            doc.acp_model_cache = entries;
+        });
+    }
+}
+export async function discoverAcpCatalog(ctx, ws, root) {
+    const result = await ws.cell().exec.run(['node', '-e', ACP_MODELS_SCRIPT], { cwd: root, timeoutMs: 55_000,
+        signal: ctx.signal, maxOutputBytes: 1 << 20, env: { SF_ACP_MODEL_DISCOVERY: '1' } });
+    if (result.exitCode !== 0)
+        throw new Error(`Guest model discovery failed: ${result.stderr.trim()}`);
+    const discovered = JSON.parse(result.stdout), catalog = {};
+    for (const app of ['claude', 'codex'])
+        if (discovered[app] && nativeModelOptions(discovered[app]).length) {
+            nativeCurrentModel(discovered[app]);
+            catalog[app] = discovered[app];
+        }
+    if (!Object.keys(catalog).length)
+        throw new Error('The guest adapters returned no available models. Check your cloud agent sign-ins.');
+    return catalog;
+}
+export const ACP_LIFECYCLE = { async prepare(ctx, folder, name, callbacks) {
+        let allocation;
+        const c = await createConversationRecord(ctx, folder, 'claude', 'acp', name, view => { allocation = view; }, `acp-session-${name}`);
+        callbacks.allocated(c, allocation);
+        const ws = await conversationWorkspace(ctx, c);
+        callbacks.ready(ws);
+        if (!(await savedMachine(ctx))?.template)
+            await syncAgentConfig(ctx, ws);
+        await ws.cell().files.mkdir(c.worktree_path, { parents: true });
+        let initialReady, initialFailed;
+        const initialFiles = new Promise((resolve, reject) => { initialReady = resolve; initialFailed = reject; });
+        const seeded = (async () => {
+            await seedAgentRepository(ctx, ws, folder, { root: c.worktree_path, populate: true,
+                initialFiles: ['.claude/settings.json', '.claude/settings.local.json', '.codex/config.toml', '.mcp.json'], onInitialFiles: initialReady });
+            const result = await ws.cell().exec.run(['git', '-C', c.worktree_path, 'checkout', '-B', c.branch, c.base_commit], { timeoutMs: 30_000, signal: ctx.signal });
+            if (result.exitCode !== 0)
+                throw new Error(`Conversation branch could not be prepared: ${result.stderr.trim()}`);
+            callbacks.prepared();
+        })();
+        void seeded.catch(initialFailed);
+        const models = (async () => { await initialFiles; return discoverAcpCatalog(ctx, ws, c.worktree_path); })();
+        // Observe both failures immediately. Never start a second VM, and never delete
+        // the user's conversation VM as catalog cleanup.
+        const results = await Promise.allSettled([seeded, models]);
+        if (results[0].status === 'rejected')
+            throw results[0].reason;
+        if (results[1].status === 'rejected')
+            throw results[1].reason;
+        return results[1].value;
+    } };

package/dist/acp.d.ts

@@ -1,6 +1,8 @@
 import type { Ctx } from './commands.js';
 import { AcpRpc, RpcError } from './acp-rpc.js';
 import type { ObjectValue } from './acp-rpc.js';
+import type { AcpCatalog } from './acp-catalog.js';
+import type { AcpLifecycle } from './acp-models.js';
 type App = 'claude' | 'codex';
 type ErrorMapper = (error: unknown) => RpcError;
 export declare function acpModel(app: App, id: string): string;
@@ -8,7 +10,7 @@ export declare function parseAcpModel(value: unknown): {
     app: App;
     id: string;
 };
-export declare function acpModelOptions(catalog: Record<App, ObjectValue>): ObjectValue[];
+export declare function acpModelOptions(catalog: AcpCatalog): ObjectValue[];
 export declare function acpError(error: unknown): RpcError;
 /** Rewrite structural session/file references, never the agent's prose or command output. */
 export declare function acpReferences(value: unknown, record: {
@@ -16,10 +18,10 @@ export declare function acpReferences(value: unknown, record: {
     nativeId?: string;
     folder: string;
 }, root: string, inbound?: boolean): unknown;
-/** One provider, two harness catalogs. The model selection determines the VM's native harness. */
+/** One provider; model catalogs belong to their guest/account/session. */
 export declare class ShardfluxAcp {
     #private;
-    constructor(ctx: Ctx, client: AcpRpc, errors?: ErrorMapper);
+    constructor(ctx: Ctx, client: AcpRpc, errors?: ErrorMapper, lifecycle?: AcpLifecycle);
     handle(method: string, params: ObjectValue, request: boolean): Promise<unknown>;
     close(): Promise<void>;
 }

package/dist/acp.js

@@ -3,16 +3,15 @@ import { isAbsolute } from 'node:path';
 import { CLI_VERSION } from "./args.js";
 import { AgentStateStore } from "./agent-state.js";
 import { AcpRpc, RpcError, objectValue } from "./acp-rpc.js";
-import { ACP_CATALOG } from "./acp-catalog.js";
+import { ACP_PROBE_CATALOG, nativeCurrentModel, nativeModelOptions, withoutNativeModel } from "./acp-catalog.js";
+import { ACP_LIFECYCLE, AcpModelCache, acpScope } from "./acp-models.js";
 import { AcpJournal } from "./acp-journal.js";
-import { createConversation, getConversation, conversationWorkspace, rememberConversation, resumeConversation, restoreConversationBinding } from "./conversations.js";
+import { getConversation, conversationWorkspace, rememberConversation, resumeConversation, restoreConversationBinding } from "./conversations.js";
 import { projectIdentity } from "./project-identity.js";
 import { describeError, ownHint } from "./errors.js";
 import { serveAcpDeviceApprovals } from "./device-bridge.js";
 import { syncAgentCredentials } from "./agent-credentials.js";
 import { cloudClaudeLogin } from "./claude-cloud-login.js";
-import { syncAgentConfig } from "./agent-config-sync.js";
-import { savedMachine } from "./filesystem-state.js";
 import { ensureMenubar, MenubarManager } from "./menubar.js";
 const PREFIX = 'shardflux:';
 export function acpModel(app, id) { return `${PREFIX}${app}:${id}`; }
@@ -26,10 +25,7 @@ export function parseAcpModel(value) {
 }
 export function acpModelOptions(catalog) {
     return ['claude', 'codex'].flatMap(app => {
-        const source = catalog[app].configOptions.find(c => c.category === 'model');
-        return (source?.options ?? []).flatMap(option => Array.isArray(option.options) ? option.options : [option]).map((option) => {
-            if (typeof option.value !== 'string' || !option.value || typeof option.name !== 'string' || !option.name)
-                throw new Error('Agent model metadata omitted its ID or name');
+        return nativeModelOptions(catalog[app] ?? {}).map((option) => {
             return { ...option, value: acpModel(app, option.value), name: `${app === 'claude' ? 'Claude Code' : 'Codex'} · ${option.name}` };
         });
     });
@@ -63,23 +59,25 @@ export function acpReferences(value, record, root, inbound = false) {
         return [key, acpReferences(leaf, record, root, inbound)];
     }));
 }
-/** One provider, two harness catalogs. The model selection determines the VM's native harness. */
+/** One provider; model catalogs belong to their guest/account/session. */
 export class ShardfluxAcp {
     #ctx;
     #client;
     #store;
     #errors;
     #sessions = new Map();
-    #catalog = { claude: structuredClone(ACP_CATALOG.claude.session), codex: structuredClone(ACP_CATALOG.codex.session) };
+    #lifecycle;
+    #cache;
     #initialized = false;
     #probe = false;
-    constructor(ctx, client, errors = acpError) { this.#ctx = ctx; this.#client = client; this.#store = new AgentStateStore(ctx.store.dir); this.#errors = errors; }
+    constructor(ctx, client, errors = acpError, lifecycle = ACP_LIFECYCLE) { this.#ctx = ctx; this.#client = client; this.#store = new AgentStateStore(ctx.store.dir); this.#cache = new AcpModelCache(ctx.store.dir); this.#errors = errors; this.#lifecycle = lifecycle; }
     #records() { return this.#store.read().acp_sessions ?? {}; }
     #save(record) { this.#store.update(doc => { doc.acp_sessions = { ...objectValue(doc.acp_sessions), [record.id]: record }; }); }
-    #configuration(model, native = {}) {
-        const options = acpModelOptions(this.#catalog);
-        return { ...native, models: { currentModelId: model, availableModels: options.map(o => ({ modelId: o.value, name: o.name, ...(o.description ? { description: o.description } : {}) })) },
-            configOptions: [{ id: 'model', name: 'Model', category: 'model', type: 'select', currentValue: model, options }, ...(native.configOptions ?? []).filter(c => c.category !== 'model')] };
+    #configuration(model, native = {}, catalog = {}) {
+        const options = acpModelOptions(catalog);
+        const current = options.some(o => o.value === model) ? model : undefined;
+        return { ...native, models: { ...(current ? { currentModelId: current } : {}), availableModels: options.map(o => ({ modelId: o.value, name: o.name, ...(o.description ? { description: o.description } : {}) })) },
+            configOptions: [{ id: 'model', name: 'Model', category: 'model', type: 'select', ...(current ? { currentValue: current } : {}), options }, ...(native.configOptions ?? []).filter(c => c.category !== 'model' && c.id !== 'model')] };
     }
     async handle(method, params, request) {
         try {
@@ -108,18 +106,34 @@ export class ShardfluxAcp {
         }
         if (method === 'session/new') {
             if (this.#probe)
-                return this.#configuration(acpModel('claude', 'default'), { sessionId: 'shardflux-probe' });
+                return this.#configuration(acpModel('claude', 'default'), { sessionId: 'shardflux-probe' }, ACP_PROBE_CATALOG);
             if (typeof params.cwd !== 'string' || !isAbsolute(params.cwd))
                 throw new RpcError(-32602, 'Open a project folder first.');
             const folder = projectIdentity(params.cwd).folder;
-            const record = { id: `sf-${randomUUID()}`, apiUrl: this.#ctx.apiUrl, folder, model: acpModel('claude', 'default'), from_seq: 0, updatedAt: new Date().toISOString() };
-            // T3 selects its model after session/new. Reserve identity now; allocate on the selection/first prompt.
+            const cached = this.#cache.lookup(this.#ctx, folder), catalog = cached?.catalog ?? {};
+            const app = catalog.claude ? 'claude' : 'codex';
+            const record = { id: `sf-${randomUUID()}`, apiUrl: this.#ctx.apiUrl, folder, catalog, scope: cached?.scope,
+                model: catalog[app] ? acpModel(app, nativeCurrentModel(catalog[app])) : '', from_seq: 0, updatedAt: new Date().toISOString() };
+            // A real session owns one VM from birth. Cached metadata returns without
+            // blocking on its boot, seed or adapter discovery; the first use waits.
+            const session = { record, stop: new AbortController() };
             this.#save(record);
-            this.#sessions.set(record.id, { record, stop: new AbortController() });
-            return this.#configuration(record.model, { sessionId: record.id });
+            this.#sessions.set(record.id, session);
+            this.#prepare(session);
+            if (!cached) {
+                await session.preparing;
+                if (session.preparationError)
+                    throw session.preparationError;
+                if (session.discoveryError)
+                    throw session.discoveryError;
+            }
+            session.announced = true;
+            return this.#configuration(record.model, { sessionId: record.id }, record.catalog);
         }
         if (this.#probe && method === 'session/close')
             return {};
+        if (this.#probe)
+            throw new RpcError(-32601, 'The provider probe has no conversation.');
         if (typeof params.sessionId !== 'string')
             throw new RpcError(-32602, 'A conversation is required');
         const session = this.#session(params.sessionId, params.cwd);
@@ -130,17 +144,42 @@ export class ShardfluxAcp {
         }
         if (method === 'session/set_model' || (method === 'session/set_config_option' && params.configId === 'model')) {
             const model = String(method === 'session/set_model' ? params.modelId : params.value), selected = parseAcpModel(model);
-            if (session.conversation && session.conversation.harness !== selected.app)
+            if (!record.catalog && record.conversationId)
+                await this.#connect(session);
+            if (record.app && record.app !== selected.app)
                 throw new RpcError(-32602, 'Choose a new conversation to switch between Claude Code and Codex.');
+            if (!acpModelOptions(record.catalog ?? {}).some(o => o.value === model))
+                throw new RpcError(-32602, 'Choose a model available in this conversation.');
+            // The selection chooses the harness, but is not persisted as accepted
+            // until the actual guest session has confirmed it.
+            await session.prepared;
+            if (session.preparationError)
+                throw session.preparationError;
+            if (!acpModelOptions(record.catalog ?? {}).some(o => o.value === model))
+                throw new RpcError(-32602, 'This model is no longer available. Choose a model from this conversation.');
             record.model = model;
-            this.#save(record);
+            record.app = selected.app;
             await this.#connect(session);
-            const result = await session.transport.rpc.request('session/set_config_option', { sessionId: record.nativeId, configId: 'model', value: selected.id });
-            return method === 'session/set_model' ? {} : this.#configuration(model, objectValue(result));
+            if (!acpModelOptions(record.catalog ?? {}).some(o => o.value === model))
+                throw new RpcError(-32602, 'This model is no longer available. Choose a model from this conversation.');
+            let result;
+            try {
+                result = objectValue(await session.transport.rpc.request('session/set_config_option', { sessionId: record.nativeId, configId: 'model', value: selected.id }));
+            }
+            catch (e) {
+                await this.#rejectModel(session, selected.id, e);
+                throw e;
+            }
+            record.model = model;
+            this.#save(record);
+            await this.#modelUpdate(session);
+            return method === 'session/set_model' ? {} : this.#configuration(model, result, record.catalog);
         }
+        if (!record.model)
+            throw new RpcError(-32602, 'Choose an available model before sending a message.');
         await this.#connect(session);
         if (method === 'session/load' || method === 'session/resume')
-            return this.#configuration(record.model, { ...record.setup, sessionId: record.id });
+            return this.#configuration(record.model, { ...record.setup, sessionId: record.id }, record.catalog);
         const mapped = acpReferences(params, record, session.conversation.worktree_path, true);
         if (method === 'session/prompt') {
             record.prompted = true;
@@ -149,8 +188,116 @@ export class ShardfluxAcp {
         }
         if (!request)
             return session.transport.rpc.notify(method, mapped);
-        const result = objectValue(await session.transport.rpc.request(method, mapped, method === 'session/prompt' ? 0 : 120_000));
-        return this.#configuration(record.model, acpReferences(result, record, session.conversation.worktree_path));
+        let result;
+        try {
+            result = objectValue(await session.transport.rpc.request(method, mapped, method === 'session/prompt' ? 0 : 120_000));
+        }
+        catch (e) {
+            if (method === 'session/prompt')
+                await this.#rejectModel(session, parseAcpModel(record.model).id, e);
+            throw e;
+        }
+        return this.#configuration(record.model, acpReferences(result, record, session.conversation.worktree_path), record.catalog);
+    }
+    #prepare(session) {
+        if (session.preparing)
+            return;
+        const { record } = session, ctx = { ...this.#ctx, signal: AbortSignal.any([this.#ctx.signal, session.stop.signal]) };
+        let prepared;
+        // The native selected adapter must not wait for the other harness's model
+        // probe. Both are guest processes; only boot/repository preparation gates it.
+        session.prepared = new Promise(resolve => { prepared = resolve; });
+        session.preparing = (async () => {
+            await syncAgentCredentials(ctx.cloud(), { home: ctx.io.env.HOME, redact: value => ctx.addSecret(value) });
+            const catalog = await this.#lifecycle.prepare(ctx, record.folder, `acp-${record.id.slice(3).replaceAll('-', '')}`, {
+                allocated: (c, view) => {
+                    session.conversation = c;
+                    record.conversationId = c.id;
+                    record.workspaceId = c.workspace_id;
+                    const previous = record.scope;
+                    record.scope = acpScope(ctx.apiUrl, view);
+                    this.#cache.remember(ctx, record.folder, record.scope);
+                    if (previous && JSON.stringify(previous) !== JSON.stringify(record.scope)) {
+                        record.catalog = this.#cache.read(record.scope);
+                        const app = record.catalog.claude ? 'claude' : 'codex';
+                        record.model = record.catalog[app] ? acpModel(app, nativeCurrentModel(record.catalog[app])) : '';
+                        if (session.announced)
+                            void this.#modelUpdate(session).catch(() => { });
+                    }
+                    this.#save(record);
+                },
+                ready: ws => { session.ws = ws; record.scope = acpScope(ctx.apiUrl, ws.data); this.#cache.remember(ctx, record.folder, record.scope); },
+                prepared: () => { session.seedReady = true; prepared(); },
+            });
+            ctx.signal.throwIfAborted();
+            if (!record.scope)
+                throw new Error('Conversation preparation omitted its allocation identity.');
+            // Lifecycle implementations that finish atomically also satisfy readiness.
+            session.seedReady = true;
+            prepared();
+            this.#cache.write(record.scope, catalog);
+            // Once the selected native session is live, its config is authoritative.
+            // A background catalog session must never reset its selected/current model.
+            if (record.nativeId && session.transport)
+                this.#cacheSession(session);
+            else {
+                record.catalog = record.app ? { [record.app]: catalog[record.app] } : catalog;
+                const app = record.app ?? (catalog.claude ? 'claude' : 'codex');
+                record.model = acpModel(app, nativeCurrentModel(catalog[app]));
+                this.#save(record);
+                if (session.announced)
+                    await this.#modelUpdate(session);
+            }
+        })().catch(async (error) => {
+            const failure = error instanceof Error ? error : new Error(String(error));
+            if (!session.seedReady)
+                session.preparationError = failure;
+            else
+                session.discoveryError = failure;
+            prepared();
+            if (session.stop.signal.aborted || ctx.signal.aborted)
+                return;
+            if (record.nativeId && session.transport)
+                return;
+            // Cached choices cannot survive a failed live refresh as if verified.
+            record.catalog = {};
+            record.model = '';
+            this.#save(record);
+            if (session.announced)
+                await this.#modelUpdate(session);
+        });
+    }
+    #cacheSession(session) {
+        const { record } = session;
+        if (!record.scope || !record.app || !record.catalog?.[record.app])
+            return;
+        const catalog = { ...this.#cache.read(record.scope), [record.app]: record.catalog[record.app] };
+        this.#cache.write(record.scope, catalog);
+    }
+    async #modelUpdate(session) {
+        const { record } = session;
+        await this.#client.notify('session/update', { sessionId: record.id, update: { sessionUpdate: 'config_option_update', ...this.#configuration(record.model, record.setup, record.catalog) } });
+    }
+    async #rejectModel(session, id, error) {
+        if (!(error instanceof RpcError) || !/model.*(?:not supported|unsupported|not found|not available|invalid)|(?:unsupported|invalid).*model/i.test(error.message))
+            return;
+        const { record } = session, { app } = parseAcpModel(record.model);
+        const native = withoutNativeModel(record.catalog?.[app] ?? {}, id);
+        record.catalog = { [app]: native };
+        // Keep an already accepted selection if a different requested model failed.
+        // A rejected current model needs a new choice; never pretend it switched.
+        if (!nativeModelOptions(native).some(o => o.value === parseAcpModel(record.model).id))
+            record.model = '';
+        if (record.scope) {
+            const cached = this.#cache.read(record.scope);
+            if (record.model)
+                cached[app] = native;
+            else
+                delete cached[app];
+            this.#cache.write(record.scope, cached);
+        }
+        this.#save(record);
+        await this.#modelUpdate(session);
     }
     #session(id, cwd) {
         const record = this.#records()[id];
@@ -164,6 +311,9 @@ export class ShardfluxAcp {
         return session;
     }
     async #connect(session) {
+        await session.prepared;
+        if (session.preparationError)
+            throw session.preparationError;
         if (session.connecting)
             return session.connecting;
         if (session.transport && !session.transport.rpc.closed)
@@ -172,27 +322,28 @@ export class ShardfluxAcp {
         return session.connecting;
     }
     async #start(session) {
-        const ctx = this.#ctx, { record } = session, { app } = parseAcpModel(record.model);
+        const ctx = this.#ctx, { record } = session, app = record.app ?? parseAcpModel(record.model).app;
+        record.app = app;
         await session.transport?.close();
         await syncAgentCredentials(ctx.cloud(), { home: ctx.io.env.HOME, redact: value => ctx.addSecret(value) });
         if (app === 'claude' && !(await cloudClaudeLogin(ctx)))
             throw new RpcError(-32000, 'Sign in to Claude Code with shard agents credentials login claude.', { code: 'unauthenticated', fix: 'Run shard agents credentials login claude.' });
         if (!record.conversationId) {
-            const created = await createConversation(ctx, record.folder, app, 'acp');
-            session.conversation = created.conversation;
-            session.ws = created.workspace;
-            record.conversationId = created.conversation.id;
-            this.#save(record);
-            if (!(await savedMachine(ctx))?.template)
-                await syncAgentConfig(ctx, created.workspace);
+            this.#prepare(session);
+            await session.prepared;
+            if (session.preparationError)
+                throw session.preparationError;
         }
-        else {
+        {
+            if (!record.conversationId)
+                throw new Error('Conversation preparation returned no binding.');
             const current = await getConversation(ctx, record.conversationId);
             session.conversation = await resumeConversation(ctx, current);
             session.ws = await conversationWorkspace(ctx, session.conversation);
             rememberConversation(ctx, session.conversation, record.folder);
         }
-        const c = session.conversation, cell = session.ws.cell();
+        let c = session.conversation;
+        const cell = session.ws.cell();
         await ensureMenubar(ctx.store.dir, ctx.apiUrl, new MenubarManager({ home: ctx.io.env.HOME, signal: ctx.signal }));
         await restoreConversationBinding(ctx, c, session.ws);
         session.approvals ??= await serveAcpDeviceApprovals(ctx.store.dir, c.id, async (approval) => {
@@ -205,6 +356,11 @@ export class ShardfluxAcp {
         const launched = await cell.exec.run(['sf-agent', 'acp', app, '--conversation', c.id, '--detach'], { cwd: c.worktree_path, timeoutMs: 30_000, signal: ctx.signal, maxOutputBytes: 1 << 20 });
         if (launched.exitCode !== 0)
             throw new Error(`ACP supervisor could not attach: ${launched.stderr.trim()}`);
+        c = await getConversation(ctx, c.id);
+        if (c.harness !== app)
+            throw new Error('The guest did not claim this conversation harness.');
+        session.conversation = c;
+        rememberConversation(ctx, c, record.folder);
         const status = JSON.parse(await cell.files.readText(`/home/user/.local/share/shardflux/acp/${c.id}/status.json`, { length: 8192 }));
         if (status.conversation_id !== c.id || status.harness !== app || !Number.isSafeInteger(status.pid) || status.pid <= 0 || !status.start || status.ended)
             throw new Error('ACP supervisor identity does not match this conversation.');
@@ -221,8 +377,12 @@ export class ShardfluxAcp {
             if (method === 'session/update') {
                 const update = objectValue(params.update);
                 if (update.sessionUpdate === 'config_option_update' && Array.isArray(update.configOptions)) {
-                    this.#catalog[app].configOptions = update.configOptions;
-                    mapped.update = { ...update, ...this.#configuration(record.model, { configOptions: update.configOptions }) };
+                    const native = { ...record.catalog?.[app], configOptions: update.configOptions };
+                    record.catalog = { [app]: native };
+                    record.model = acpModel(app, nativeCurrentModel(native));
+                    this.#save(record);
+                    this.#cacheSession(session);
+                    mapped.update = { ...update, ...this.#configuration(record.model, native, record.catalog) };
                 }
             }
             if (request) {
@@ -245,21 +405,35 @@ export class ShardfluxAcp {
             if (initialized.protocolVersion !== 1)
                 throw new Error('Agent protocol version changed');
             const nativeId = c.harness_session_id ?? record.nativeId;
-            const result = objectValue(await transport.rpc.request(nativeId ? 'session/load' : 'session/new', { cwd: c.worktree_path, mcpServers: [], ...(nativeId ? { sessionId: nativeId } : {}) }));
+            const result = objectValue(await transport.rpc.request(nativeId ? 'session/load' : 'session/new', { cwd: c.worktree_path, mcpServers: [{ name: 'shardflux', command: '/usr/local/bin/sf-agent', args: ['conversation', 'mcp'], env: [{ name: 'SF_CONVERSATION_ID', value: c.id }] }], ...(nativeId ? { sessionId: nativeId } : {}) }));
             const id = result.sessionId ?? nativeId;
             if (typeof id !== 'string' || !id)
                 throw new Error('Agent returned no native session id');
             record.nativeId = id;
             record.setup = result;
             record.owner = owner;
-            if (Array.isArray(result.configOptions))
-                this.#catalog[app].configOptions = result.configOptions;
+            record.catalog = { [app]: result };
+            record.model = acpModel(app, nativeCurrentModel(result));
+            this.#save(record);
+            this.#cacheSession(session);
+            await this.#modelUpdate(session);
+        }
+        else {
+            // Even a reattachment refreshes the live session, rather than using model
+            // options persisted under an earlier guest/account identity.
+            const result = objectValue(await transport.rpc.request('session/load', { cwd: c.worktree_path, sessionId: record.nativeId, mcpServers: [] }));
+            record.setup = result;
+            record.catalog = { [app]: result };
+            record.model = acpModel(app, nativeCurrentModel(result));
             this.#save(record);
+            this.#cacheSession(session);
+            await this.#modelUpdate(session);
         }
     }
     async #close(session) {
         this.#sessions.delete(session.record.id);
         session.stop.abort();
+        await session.preparing;
         await session.transport?.close();
         session.ws?.cell().close();
         await session.approvals?.stop();

package/dist/agent-repository.d.ts

@@ -12,6 +12,8 @@ export declare function needsGitSeed(ctx: Ctx, ws: Workspace): boolean;
 export declare function seedAgentRepository(ctx: Ctx, ws: Workspace, folder: string, options?: {
     root?: string;
     populate?: boolean;
+    initialFiles?: readonly string[];
+    onInitialFiles?: () => void;
 }): Promise<void>;
 /** History above this goes through the project's origin instead of the bounded files path. */
 export declare const HISTORY_BUNDLE_LIMIT: number;