@shardflux/cli 0.13.6 → 0.14.1

package/dist/acp-rpc.d.ts

@@ -0,0 +1,41 @@
+export type RpcId = string | number;
+export type ObjectValue = Record<string, unknown>;
+export interface RpcMessage extends ObjectValue {
+    jsonrpc: '2.0';
+    id?: RpcId | null;
+    method?: string;
+    params?: ObjectValue;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+export declare class RpcError extends Error {
+    readonly code: number;
+    readonly data?: unknown;
+    constructor(code: number, message: string, data?: unknown);
+}
+export declare const objectValue: (value: unknown) => ObjectValue;
+/** Each peer owns its request namespace; adapter IDs never escape to another conversation. */
+export declare class AcpRpc {
+    #private;
+    readonly pending: Map<RpcId, {
+        resolve(value: unknown): void;
+        reject(error: unknown): void;
+        timer?: ReturnType<typeof setTimeout>;
+        cleanup?(): void;
+    }>;
+    handler: (method: string, params: ObjectValue, request: boolean) => Promise<unknown>;
+    onIdle: () => void;
+    onResponse: (message: RpcMessage) => void;
+    constructor(write: (message: RpcMessage) => Promise<void>);
+    get busy(): boolean;
+    get closed(): boolean;
+    feed(bytes: Uint8Array): void;
+    request(method: string, params: ObjectValue, timeoutMs?: number, signal?: AbortSignal): Promise<unknown>;
+    notify(method: string, params: ObjectValue): Promise<void>;
+    close(error?: Error): void;
+    drain(): Promise<void>;
+}

package/dist/acp-rpc.js

@@ -0,0 +1,115 @@
+import { StringDecoder } from 'node:string_decoder';
+import { randomUUID } from 'node:crypto';
+export class RpcError extends Error {
+    code;
+    data;
+    constructor(code, message, data) { super(message); this.code = code; this.data = data; }
+}
+export const objectValue = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+/** Each peer owns its request namespace; adapter IDs never escape to another conversation. */
+export class AcpRpc {
+    pending = new Map();
+    handler = () => Promise.reject(new RpcError(-32601, 'Method not found'));
+    onIdle = () => { };
+    onResponse = () => { };
+    #write;
+    #decoder = new StringDecoder('utf8');
+    #buffer = '';
+    #next = 0;
+    #namespace = randomUUID();
+    #closed;
+    #inbound = 0;
+    #receiving = new Set();
+    constructor(write) { this.#write = write; }
+    get busy() { return this.pending.size > 0 || this.#inbound > 0; }
+    get closed() { return this.#closed !== undefined; }
+    feed(bytes) {
+        this.#buffer += this.#decoder.write(Buffer.from(bytes));
+        let newline;
+        while ((newline = this.#buffer.indexOf('\n')) >= 0) {
+            const line = this.#buffer.slice(0, newline);
+            this.#buffer = this.#buffer.slice(newline + 1);
+            if (Buffer.byteLength(line) > 16 << 20)
+                throw new RpcError(-32700, 'Message exceeds 16 MiB');
+            if (!line.trim())
+                continue;
+            let value;
+            try {
+                value = JSON.parse(line);
+            }
+            catch {
+                throw new RpcError(-32700, 'Invalid JSON');
+            }
+            const message = objectValue(value);
+            if (message.jsonrpc !== '2.0')
+                throw new RpcError(-32600, 'Invalid JSON-RPC message');
+            const receiving = this.#receive(message).catch(error => this.close(error instanceof Error ? error : new Error(String(error))));
+            this.#receiving.add(receiving);
+            void receiving.finally(() => this.#receiving.delete(receiving));
+        }
+        if (Buffer.byteLength(this.#buffer) > 16 << 20)
+            throw new RpcError(-32700, 'Message exceeds 16 MiB');
+    }
+    async #receive(message) {
+        if (message.method !== undefined) {
+            const request = message.id !== undefined;
+            this.#inbound++;
+            try {
+                const result = await this.handler(message.method, message.params ?? {}, request);
+                if (request)
+                    await this.#write({ jsonrpc: '2.0', id: message.id, result: result ?? {} });
+            }
+            catch (error) {
+                if (request) {
+                    const e = error instanceof RpcError ? error : new RpcError(-32603, error instanceof Error ? error.message : String(error));
+                    await this.#write({ jsonrpc: '2.0', id: message.id, error: { code: e.code, message: e.message, ...(e.data === undefined ? {} : { data: e.data }) } });
+                }
+            }
+            finally {
+                this.#inbound--;
+                this.onIdle();
+            }
+            return;
+        }
+        if (message.id === undefined || message.id === null)
+            return;
+        this.onResponse(message);
+        const pending = this.pending.get(message.id);
+        if (!pending)
+            return;
+        this.pending.delete(message.id);
+        clearTimeout(pending.timer);
+        pending.cleanup?.();
+        if (message.error)
+            pending.reject(new RpcError(message.error.code, message.error.message, message.error.data));
+        else
+            pending.resolve(message.result);
+        this.onIdle();
+    }
+    request(method, params, timeoutMs = 120_000, signal) {
+        if (this.#closed)
+            return Promise.reject(this.#closed);
+        if (signal?.aborted)
+            return Promise.reject(signal.reason instanceof Error ? signal.reason : new Error('Request interrupted'));
+        const id = `shard-${this.#namespace}-${++this.#next}`;
+        return new Promise((resolve, reject) => {
+            const cleanup = () => signal?.removeEventListener('abort', abort);
+            const timer = timeoutMs > 0 ? setTimeout(() => { this.pending.delete(id); cleanup(); reject(new RpcError(-32000, 'Request timed out', { code: 'timeout', fix: 'Try the message again.' })); this.onIdle(); }, timeoutMs) : undefined;
+            const abort = () => { this.pending.delete(id); clearTimeout(timer); cleanup(); reject(signal?.reason instanceof Error ? signal.reason : new Error('Request interrupted')); this.onIdle(); };
+            this.pending.set(id, { resolve, reject, timer, cleanup });
+            signal?.addEventListener('abort', abort, { once: true });
+            void this.#write({ jsonrpc: '2.0', id, method, params }).catch((error) => { this.pending.delete(id); clearTimeout(timer); cleanup(); reject(error instanceof Error ? error : new Error(String(error))); this.onIdle(); });
+        });
+    }
+    notify(method, params) { return this.#write({ jsonrpc: '2.0', method, params }); }
+    close(error = new Error('Connection closed')) {
+        this.#closed = error;
+        for (const pending of this.pending.values()) {
+            clearTimeout(pending.timer);
+            pending.cleanup?.();
+            pending.reject(error);
+        }
+        this.pending.clear();
+    }
+    async drain() { await Promise.all([...this.#receiving]); }
+}

package/dist/acp.d.ts

@@ -0,0 +1,29 @@
+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;
+export declare function parseAcpModel(value: unknown): {
+    app: App;
+    id: string;
+};
+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: {
+    id: string;
+    nativeId?: string;
+    folder: string;
+}, root: string, inbound?: boolean): unknown;
+/** One provider; model catalogs belong to their guest/account/session. */
+export declare class ShardfluxAcp {
+    #private;
+    constructor(ctx: Ctx, client: AcpRpc, errors?: ErrorMapper, lifecycle?: AcpLifecycle);
+    handle(method: string, params: ObjectValue, request: boolean): Promise<unknown>;
+    close(): Promise<void>;
+}
+export declare function runAcp(ctx: Ctx, errors?: ErrorMapper): Promise<number>;
+export {};

package/dist/acp.js

@@ -0,0 +1,464 @@
+import { randomUUID } from 'node:crypto';
+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_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 { 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 { ensureMenubar, MenubarManager } from "./menubar.js";
+const PREFIX = 'shardflux:';
+export function acpModel(app, id) { return `${PREFIX}${app}:${id}`; }
+export function parseAcpModel(value) {
+    if (typeof value !== 'string')
+        throw new RpcError(-32602, 'Choose a model from Shardflux.');
+    const match = /^shardflux:(claude|codex):(.+)$/.exec(value);
+    if (!match)
+        throw new RpcError(-32602, 'Choose a model from Shardflux.');
+    return { app: match[1], id: match[2] };
+}
+export function acpModelOptions(catalog) {
+    return ['claude', 'codex'].flatMap(app => {
+        return nativeModelOptions(catalog[app] ?? {}).map((option) => {
+            return { ...option, value: acpModel(app, option.value), name: `${app === 'claude' ? 'Claude Code' : 'Codex'} · ${option.name}` };
+        });
+    });
+}
+export function acpError(error) {
+    if (error instanceof RpcError) {
+        if (error.code === -32000 && /authentication required|oauth.*(?:revoked|expired)|not (?:signed|logged) in/i.test(error.message))
+            return new RpcError(-32000, `${error.message} Run shard setup.`, { code: 'unauthenticated', fix: 'Run shard setup.' });
+        return error;
+    }
+    const info = describeError(error);
+    const fix = info.code === 'unauthenticated' ? 'Run shard setup.' : info.code === 'not_found' || info.details?.reason === 'workspace_deleted' ? 'Open a new conversation.' : ownHint(error) ?? (info.code === 'quota_exceeded' || info.code === 'allowance_exhausted' ? 'Run shard billing plans.' : 'Try the message again.');
+    return new RpcError(-32000, `${info.message} ${fix}`, { code: info.code, fix, ...(info.details?.reason ? { reason: info.details.reason } : {}) });
+}
+/** Rewrite structural session/file references, never the agent's prose or command output. */
+export function acpReferences(value, record, root, inbound = false) {
+    if (Array.isArray(value))
+        return value.map(v => acpReferences(v, record, root, inbound));
+    if (!value || typeof value !== 'object')
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, leaf]) => {
+        if (key === 'sessionId' && leaf === (inbound ? record.id : record.nativeId))
+            return [key, inbound ? record.nativeId : record.id];
+        if (typeof leaf === 'string' && ['path', 'cwd', 'uri'].includes(key)) {
+            const from = inbound ? record.folder : root, to = inbound ? root : record.folder;
+            if (leaf === from || leaf.startsWith(from + '/'))
+                return [key, to + leaf.slice(from.length)];
+            if (leaf.startsWith(`file://${from}/`))
+                return [key, `file://${to}` + leaf.slice(`file://${from}`.length)];
+        }
+        return [key, acpReferences(leaf, record, root, inbound)];
+    }));
+}
+/** One provider; model catalogs belong to their guest/account/session. */
+export class ShardfluxAcp {
+    #ctx;
+    #client;
+    #store;
+    #errors;
+    #sessions = new Map();
+    #lifecycle;
+    #cache;
+    #initialized = false;
+    #probe = false;
+    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 = {}, 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 {
+            return await this.#handle(method, params, request);
+        }
+        catch (error) {
+            throw this.#errors(error);
+        }
+    }
+    async #handle(method, params, request) {
+        if (method === 'initialize') {
+            if (this.#initialized)
+                throw new RpcError(-32600, 'Already initialized');
+            if (params.protocolVersion !== 1 && params.protocolVersion !== 2)
+                throw new RpcError(-32602, 'Unsupported protocol version');
+            this.#initialized = true;
+            this.#probe = objectValue(params.clientInfo).name === 't3-code-provider-test';
+            return { protocolVersion: 1, agentInfo: { name: 'shardflux', title: 'Shardflux', version: CLI_VERSION }, authMethods: [],
+                agentCapabilities: { loadSession: true, promptCapabilities: { image: true, embeddedContext: true }, sessionCapabilities: { list: {}, resume: {}, close: {} } } };
+        }
+        if (!this.#initialized)
+            throw new RpcError(-32600, 'Initialize first');
+        if (method === 'session/list') {
+            const sessions = Object.values(this.#records()).filter(r => r.apiUrl === this.#ctx.apiUrl && (!params.cwd || r.folder === params.cwd));
+            return { sessions: sessions.map(r => ({ sessionId: r.id, cwd: r.folder, updatedAt: r.updatedAt })) };
+        }
+        if (method === 'session/new') {
+            if (this.#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 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, 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);
+        const { record } = session;
+        if (method === 'session/close') {
+            await this.#close(session);
+            return {};
+        }
+        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 (!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;
+            record.app = selected.app;
+            await this.#connect(session);
+            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 }, record.catalog);
+        const mapped = acpReferences(params, record, session.conversation.worktree_path, true);
+        if (method === 'session/prompt') {
+            record.prompted = true;
+            record.updatedAt = new Date().toISOString();
+            this.#save(record);
+        }
+        if (!request)
+            return session.transport.rpc.notify(method, mapped);
+        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];
+        if (!record || record.apiUrl !== this.#ctx.apiUrl || (cwd !== undefined && (typeof cwd !== 'string' || projectIdentity(cwd).folder !== record.folder)))
+            throw new RpcError(-32000, 'Conversation not found.');
+        let session = this.#sessions.get(id);
+        if (!session) {
+            session = { record, stop: new AbortController() };
+            this.#sessions.set(id, session);
+        }
+        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)
+            return;
+        session.connecting = this.#start(session).finally(() => { session.connecting = undefined; });
+        return session.connecting;
+    }
+    async #start(session) {
+        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) {
+            this.#prepare(session);
+            await session.prepared;
+            if (session.preparationError)
+                throw session.preparationError;
+        }
+        {
+            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);
+        }
+        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) => {
+            const result = objectValue(await this.#client.request('session/request_permission', { sessionId: record.id,
+                toolCall: { toolCallId: approval.request_id, title: approval.summary, kind: 'execute', status: 'pending' },
+                options: [{ optionId: 'once', name: 'Allow once', kind: 'allow_once' }, ...(!approval.outside ? [{ optionId: 'always', name: 'Always for this project', kind: 'allow_always' }] : []), { optionId: 'deny', name: 'Deny', kind: 'reject_once' }] }, 0, AbortSignal.any([ctx.signal, session.stop.signal])));
+            const outcome = objectValue(result.outcome);
+            return outcome.outcome === 'selected' && (outcome.optionId === 'once' || outcome.optionId === 'always') ? outcome.optionId : 'deny';
+        });
+        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.');
+        const owner = `${session.ws.id}:${status.pid}:${status.start}`;
+        const initialize = !record.nativeId || record.owner !== owner;
+        if (record.workspaceId !== session.ws.id)
+            record.from_seq = 0;
+        record.workspaceId = session.ws.id;
+        const transport = new AcpJournal(cell, c.id, app, c.worktree_path, record, () => this.#save(record), ctx.signal);
+        transport.rpc.handler = async (method, params, request) => {
+            if (method.startsWith('fs/') || method.startsWith('terminal/'))
+                throw new RpcError(-32601, 'Files and commands run in your cloud workspace.');
+            const mapped = acpReferences(params, record, c.worktree_path);
+            if (method === 'session/update') {
+                const update = objectValue(params.update);
+                if (update.sessionUpdate === 'config_option_update' && Array.isArray(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) {
+                if (method === 'session/request_permission')
+                    transport.pause();
+                try {
+                    return acpReferences(await this.#client.request(method, mapped, 0, AbortSignal.any([ctx.signal, session.stop.signal])), record, c.worktree_path, true);
+                }
+                finally {
+                    if (method === 'session/request_permission')
+                        transport.resume();
+                }
+            }
+            await this.#client.notify(method, mapped);
+        };
+        session.transport = transport;
+        await transport.start();
+        if (initialize) {
+            const initialized = objectValue(await transport.rpc.request('initialize', { protocolVersion: 1, clientInfo: { name: 'shardflux', version: CLI_VERSION }, clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false } }));
+            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: [{ 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;
+            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();
+        session.approvals = undefined;
+    }
+    async close() { await Promise.all([...this.#sessions.values()].map(s => this.#close(s))); }
+}
+export async function runAcp(ctx, errors) {
+    const controller = new AbortController();
+    ctx = { ...ctx, signal: AbortSignal.any([ctx.signal, controller.signal]) };
+    const rpc = new AcpRpc(message => { ctx.io.stdout.write(JSON.stringify(message) + '\n'); return Promise.resolve(); });
+    const server = new ShardfluxAcp(ctx, rpc, errors);
+    rpc.handler = (method, params, request) => server.handle(method, params, request);
+    try {
+        for await (const chunk of ctx.io.stdin) {
+            ctx.signal.throwIfAborted();
+            rpc.feed(Buffer.from(chunk));
+        }
+    }
+    finally {
+        controller.abort();
+        rpc.close();
+        await server.close();
+        await rpc.drain();
+        await server.close();
+    }
+    return 0;
+}