@shardflux/cli 0.13.6 → 0.14.1

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 0.14.1
+
+- `shard ssh-proxy` connects faster: host trust (host key pin and device key) runs alongside the tunnel start, with no guest byte reaching OpenSSH before the host key is pinned, and a reconnect checks its device key with one read.
+
+## 0.14.0
+
+- Ask for device approval before preparing the VM-backed local worktree; report a failed preparation as the request's result and bound preparation to 30 seconds.
+- Keep desktop programs running after a command returns with detached `setsid -f` guidance.
+- Allocate one VM per new ACP conversation, with cached initial model choices and live updates from that same VM.
+
+- Populate ACP model choices from the cloud adapters for each session, following the VM's native Claude Code and Codex executables. Refresh choices on attachment and model updates, and remove models the live adapter rejects.
+- Register the bound Shardflux conversation MCP server for cloud ACP sessions, so plain chat can fork, join, move, land and request device actions.
+- Request valid 64 MiB file manifests when mirroring native transcripts; the device helper and native history handoff no longer fail with invalid argument.
+- Carry Git fetch/push through the platform binary transport so native protocol flush packets arrive before stdin EOF.
+- Seed the shared project hub before writing Desktop connections so a new thread can initialize its separate VM.
+
+- Parallel conversation launches preserve both sessions in local history.
+
+- Help an agent can set up cloud agents from: `shard --help` has a Cloud agents section (conversations, machine, template, agents) and says how a VM is made (the coding template, then your machine, then the project template), that machine and project templates are saved from an agent's VM, that `shard templates` is for your own app's workspaces (a repository bound to one is refused with `template_not_agent_capable`), and that Claude Code and Codex in the VM have the `shardflux-computer` tools. `shard machine`, `shard template` and `shard templates init|build|draft open` help say the same.
+- Register one desktop app connection per project, named Shardflux · <project>; preserve older SSH aliases and CLI 0.13.x target manifests.
+- Resume saved conversations in a fresh VM under the same identity; open a read-only project-space reader for final branches and transcripts.
+- Conversation follow-up: read-only reviewer joins, Try locally device requests, and project usage with workspace-scoped guest resize.
+
+- **Breaking:** `shard ./` starts a conversation in its own VM and opens Claude Code or Codex directly. `--resume` selects a saved project conversation. Two-way sync is now opened with `shard conversations try <name>` in an isolated local worktree.
+- Register one Shardflux provider in T3 Code silently, with Claude Code and Codex models. ACP sessions attach to guest supervision and replay missed updates after reconnect.
+- Run device tools through the Mac helper with local approvals and project grants; mirror transcripts into the Shardflux stash and hand ended sessions to native history after fetching their branch.
+- Volume lists and details show `kind`; project-space quota is labelled platform managed. Includes SDK 0.19.0.
+- Add project conversations with durable VM bindings, messages, moves, landing records and device requests.
+
+- Local connections to the target-update lock cannot keep its owner running after release.
+
+- `ssh-proxy` closes its guest forwarder on EOF, signals and transport failure, reuses the cached helper, and waits for target updates with automatic recovery of dead PID owners.
+- `ssh-proxy` finishes when the guest closes its output, including sshd's pre-authentication admission refusals, so OpenSSH receives EOF and reconnects without hanging.
+
+- Fork externally started desktop/SDK agent workspaces as full-state copies without a managed PTY receipt; give copied T3 workspaces their own identity even when an older platform's PTY repair fails.
+- The managed `~/.ssh/config` Include line is written unquoted when the path needs no quotes, so tools that list SSH hosts from it (T3 Code) find Shardflux hosts.
+- Open cloud projects in T3 Code with `shard agents open t3 <key>`, prewarm its matching server in the background, name environments `Shardflux · <project>`, and give forked agents a separate T3 identity.
+- `shard ssh-proxy` sends a prewake hint and uses a passive tunnel so open desktop SSH connections join the existing parking lifecycle.
+- `shard ssh-proxy` connects to a workspace whose host has no passive attach as an ordinary SSH connection.
+- `shard` exits quietly when the reader has closed its output (OpenSSH after a `ssh-proxy` session, `| head`), instead of printing a write error.
+- An error with several causes (tunnel teardown, cleanup) names each cause, and its first cause decides the error code.
+
 ## 0.13.6
 
 - `shard` makes the macOS menu bar app's executable runnable when it installs or starts the app, so a menu bar copied

package/README.md

@@ -52,7 +52,7 @@ Use `shard` for your projects, machine, templates and account.
 
 ## Quick start
 
-Start your coding agent on a local project (0.13.2+):
+Start a conversation on a local project (0.14.0+):
 
 ```sh
 shard setup
@@ -61,10 +61,27 @@ shard ./
 ```
 
 Choose Claude Code or Codex. Claude asks for one cloud sign-in per Shardflux account; Codex uses your copied login.
-The agent is usable immediately while setup prepares the project in the background. `shard` opens the command
-center for every project; `shard ./` returns to this project. On macOS the menu bar starts automatically the first
+Each `shard ./` starts its own conversation VM and opens your agent’s native terminal. Later turns stay in that
+VM; `shard ./ --resume` selects a saved project conversation. Native terminal and ACP sessions receive the conversation tools for their own conversation, so the agent can fork, ask for a review, and report to its parent (0.14.0+). You can open conversations in separate terminals at the same time; each stays in the project's local history. `shard` opens the optional command center. On macOS the menu bar starts automatically the first
 time `shard` runs, with launch at login enabled; `shard menubar stop` turns it off. See [Cloud agents](https://docs.shardflux.dev/guides/cloud-agents).
 
+T3 Code uses one **Shardflux** provider; choose a Claude Code or Codex model to start that agent in the cloud.
+Model choices come from your cloud agent's session and use the same coding tools and settings as its terminal.
+The provider is registered automatically when T3 Code is installed. Use a T3 build that supports ACP providers.
+
+Git fetch and push use the coding guest’s platform transport when available, preserving Git’s binary packets (0.14.0+). Older guests retain their existing transport.
+
+To try a conversation on your Mac:
+
+```sh
+shard conversations try <conversation>
+```
+
+Your branch opens in `.shard/worktrees/<name>`, syncs both ways, and its dev servers appear at localhost.
+Ctrl-C stops local sync. Your main checkout stays available for your own work.
+Device tools ask Allow once or Always for this project on your Mac before preparing the conversation’s local worktree. Live transcripts stay in
+`~/.config/shardflux/conversations/`; ended sessions enter Claude Code’s or Codex’s native history. Transcript files up to 64 MiB are supported (0.14.0+).
+
 For application workspace commands, `shard signup` creates an account and saves a project key, or set
 `SHARDFLUX_API_KEY` to a key from the console and run `shard login`. `shard --help` lists every command.
 
@@ -1163,4 +1180,27 @@ Remembered credentials: stored encrypted with AWS KMS and filled straight into t
 [Machine and template](https://docs.shardflux.dev/guides/machine-and-template) ·
 [Credentials](https://docs.shardflux.dev/guides/credentials)
 
-`shard templates` remains the platform template build and management group.
+A VM is the `coding` template, then your machine, then the project template. Machine and project templates are
+always saved from an agent's VM, so they keep Claude Code, Codex and the agent runtime. `shard templates` builds
+templates for your own app's workspaces (SDK/API), not for cloud agents: a repository bound to one of those is
+refused with `template_not_agent_capable` (0.14.0+).
+
+Inside the VM, Claude Code and Codex have Shardflux computer use next to their own tools (0.14.0+, `coding` 13+): the
+`shardflux-computer` MCP server's `computer` and `computer_batch` drive the VM's desktop. The agent starts a program
+on it with `DISPLAY=:1`, detached so it outlives the command, for example
+`DISPLAY=:1 setsid -f chromium http://localhost:3000`, then takes a screenshot.
+
+Volume lists and details (0.14.0+) show `kind`. Project spaces show their measured storage and a platform-managed quota.
+
+## Conversations
+
+From 0.14.0, `shard conversations list|get|send|wait|land|move` manages project conversations. `shard c` is the short form. Conversations retain their branch and transcript as their VM binding changes.
+
+
+Desktop project connections (0.14.0+): `shard agents open codex-app <project>/<workspace>` and
+`shard agents open claude-desktop <project>/<workspace>` register **Shardflux · <project>** in the app.
+Open that project connection to start conversations and return to their saved threads. The project hub supplies the base commit to each new thread’s VM (0.14.0+).
+
+Conversation JSON includes `join_mode` and the worktree used by reviewers and workers.
+
+`shard conversations resume <id>` continues a saved conversation in a fresh VM under the same identity (0.14.0+). `shard ./ --resume` uses this same path. `shard conversations reader <project-id>` opens a small read-only workspace for saved branches and transcripts; the Mac transcript mirror opens it automatically when no project VM is live. Adaptive idle reclaims the reader.

package/dist/acp-catalog.d.ts

@@ -0,0 +1,7 @@
+import type { ObjectValue } from './acp-rpc.js';
+export type AcpApp = 'claude' | 'codex';
+export type AcpCatalog = Partial<Record<AcpApp, ObjectValue>>;
+export declare const ACP_PROBE_CATALOG: AcpCatalog;
+export declare function nativeModelOptions(session: ObjectValue): ObjectValue[];
+export declare function nativeCurrentModel(session: ObjectValue): string;
+export declare function withoutNativeModel(session: ObjectValue, id: string): ObjectValue;

package/dist/acp-catalog.js

@@ -0,0 +1,40 @@
+import { objectValue } from "./acp-rpc.js";
+// T3's installation probe works offline, without a VM. These are harness
+// labels only. Real sessions always replace them with guest metadata.
+export const ACP_PROBE_CATALOG = {
+    claude: { models: { currentModelId: 'default', availableModels: [{ modelId: 'default', name: 'Claude Code' }] } },
+    codex: { models: { currentModelId: 'default', availableModels: [{ modelId: 'default', name: 'Codex' }] } },
+};
+export function nativeModelOptions(session) {
+    const configs = Array.isArray(session.configOptions) ? session.configOptions.map(objectValue) : [];
+    const model = configs.find(c => c.category === 'model' || c.id === 'model');
+    const options = model && Array.isArray(model.options)
+        ? model.options.flatMap(raw => {
+            const option = objectValue(raw);
+            return Array.isArray(option.options) ? option.options.map(objectValue) : [option];
+        })
+        : (Array.isArray(objectValue(session.models).availableModels) ? objectValue(session.models).availableModels : [])
+            .map(raw => { const m = objectValue(raw); return { value: m.modelId, name: m.name, ...(m.description ? { description: m.description } : {}) }; });
+    const seen = new Set();
+    return options.map(option => {
+        if (typeof option.value !== 'string' || !option.value || typeof option.name !== 'string' || !option.name || seen.has(option.value))
+            throw new Error('Agent model metadata omitted a unique ID or name');
+        seen.add(option.value);
+        return option;
+    });
+}
+export function nativeCurrentModel(session) {
+    const configs = Array.isArray(session.configOptions) ? session.configOptions.map(objectValue) : [];
+    const current = configs.find(c => c.category === 'model' || c.id === 'model')?.currentValue ?? objectValue(session.models).currentModelId;
+    const options = nativeModelOptions(session);
+    if (typeof current === 'string' && options.some(o => o.value === current))
+        return current;
+    throw new Error('The guest adapter returned no current model among its available models.');
+}
+export function withoutNativeModel(session, id) {
+    const options = nativeModelOptions(session).filter(o => o.value !== id);
+    const configs = Array.isArray(session.configOptions) ? session.configOptions.map(objectValue) : [];
+    const current = configs.find(c => c.category === 'model' || c.id === 'model')?.currentValue ?? objectValue(session.models).currentModelId;
+    return { ...session, configOptions: [{ id: 'model', category: 'model', type: 'select', options,
+                ...(options.some(o => o.value === current) ? { currentValue: current } : {}) }, ...configs.filter(c => c.category !== 'model' && c.id !== 'model')] };
+}

package/dist/acp-journal.d.ts

@@ -0,0 +1,18 @@
+import type { CellClient } from '@shardflux/sdk';
+import { AcpRpc } from './acp-rpc.js';
+import type { RpcId } from './acp-rpc.js';
+export interface AcpCursor {
+    from_seq: number;
+    prompt_id?: RpcId;
+}
+export declare const ACP_INPUT_SCRIPT = "import json, os, socket, sys\npayload = sys.stdin.buffer.readline((2 << 20) + 1024)\nif not payload.endswith(b'\\n') or len(json.dumps(json.loads(payload)['message'], separators=(',', ':'), ensure_ascii=False).encode()) > 2 << 20:\n    raise ValueError('ACP input exceeds 2 MiB')\nfolder = os.open(sys.argv[1], os.O_RDONLY)\ntry:\n    with socket.socket(socket.AF_UNIX) as peer:\n        peer.settimeout(10)\n        address = os.path.join(sys.argv[1], 'control.sock')\n        if len(address.encode()) >= 108: address = '/proc/self/fd/%d/control.sock' % folder\n        peer.connect(address)\n        peer.sendall(payload)\n        response = peer.makefile('rb').readline(65536)\n        result = json.loads(response)\n        if result.get('accepted') is not True: raise ValueError(result.get('error', 'ACP input was not acknowledged'))\n        sys.stdout.buffer.write(response)\nfinally:\n    os.close(folder)\n";
+/** Replay is finite; a live follower exists only while a turn/RPC needs output. Native supervision is CVB's. */
+export declare class AcpJournal {
+    #private;
+    readonly rpc: AcpRpc;
+    constructor(cell: CellClient, conversation: string, _harness: 'claude' | 'codex', cwd: string, cursor: AcpCursor, save: () => void, signal: AbortSignal);
+    start(): Promise<void>;
+    pause(): void;
+    resume(): void;
+    close(): Promise<void>;
+}

package/dist/acp-journal.js

@@ -0,0 +1,232 @@
+import { randomUUID } from 'node:crypto';
+import { StringDecoder } from 'node:string_decoder';
+import { AcpRpc } from "./acp-rpc.js";
+// InputACP's private, same-uid socket receipt protocol. Stdin avoids Linux's 128 KiB per-argument limit.
+export const ACP_INPUT_SCRIPT = `import json, os, socket, sys
+payload = sys.stdin.buffer.readline((2 << 20) + 1024)
+if not payload.endswith(b'\\n') or len(json.dumps(json.loads(payload)['message'], separators=(',', ':'), ensure_ascii=False).encode()) > 2 << 20:
+    raise ValueError('ACP input exceeds 2 MiB')
+folder = os.open(sys.argv[1], os.O_RDONLY)
+try:
+    with socket.socket(socket.AF_UNIX) as peer:
+        peer.settimeout(10)
+        address = os.path.join(sys.argv[1], 'control.sock')
+        if len(address.encode()) >= 108: address = '/proc/self/fd/%d/control.sock' % folder
+        peer.connect(address)
+        peer.sendall(payload)
+        response = peer.makefile('rb').readline(65536)
+        result = json.loads(response)
+        if result.get('accepted') is not True: raise ValueError(result.get('error', 'ACP input was not acknowledged'))
+        sys.stdout.buffer.write(response)
+finally:
+    os.close(folder)
+`;
+/** Replay is finite; a live follower exists only while a turn/RPC needs output. Native supervision is CVB's. */
+export class AcpJournal {
+    rpc;
+    #cell;
+    #conversation;
+    #cwd;
+    #cursor;
+    #save;
+    #controller = new AbortController();
+    #signal;
+    #initial;
+    #ready = false;
+    #reading;
+    #reader;
+    #follower;
+    #writing = Promise.resolve();
+    #paused = 0;
+    constructor(cell, conversation, _harness, cwd, cursor, save, signal) {
+        if (!/^[a-zA-Z0-9_-]{1,96}$/.test(conversation))
+            throw new Error('Invalid ACP conversation identity');
+        this.#cell = cell;
+        this.#conversation = conversation;
+        this.#cwd = cwd;
+        this.#cursor = cursor;
+        this.#save = save;
+        this.#signal = AbortSignal.any([signal, this.#controller.signal]);
+        this.rpc = new AcpRpc(message => {
+            const encoded = JSON.stringify(message);
+            if (Buffer.byteLength(encoded) > 2 << 20)
+                return Promise.reject(new Error('ACP input exceeds 2 MiB'));
+            const inputId = randomUUID();
+            if (message.method === 'session/prompt' && message.id != null) {
+                this.#cursor.prompt_id = message.id;
+                this.#save();
+            }
+            const run = this.#writing.then(async () => {
+                await this.#deliver(inputId, encoded);
+                this.#follow();
+            });
+            this.#writing = run.catch(error => { this.rpc.close(error instanceof Error ? error : new Error(String(error))); });
+            return run;
+        });
+        this.rpc.onIdle = () => { if (!this.#wanted())
+            this.#reader?.abort(); };
+    }
+    #wanted() { return !this.#signal.aborted && !this.rpc.closed && this.#paused === 0 && (this.rpc.busy || this.#cursor.prompt_id !== undefined); }
+    async #deliver(inputId, message) {
+        const dir = `/home/user/.local/share/shardflux/acp/${this.#conversation}`;
+        const payload = Buffer.from(`{"mode":"input","input_id":${JSON.stringify(inputId)},"message":${message}}\n`);
+        const session = await this.#cell.exec.start({ argv: ['python3', '-c', ACP_INPUT_SCRIPT, dir], cwd: this.#cwd, stdin_open: true, timeout_ms: 15_000 }, this.#signal);
+        let offset = 0, stdout = '';
+        try {
+            while (offset < payload.length) {
+                const bytes = payload.subarray(offset, offset + 65536);
+                const ack = await this.#cell.exec.input(session.session_id, bytes, { offset, close: offset + bytes.length === payload.length, signal: this.#signal });
+                const accepted = ack.offset - offset;
+                if (!Number.isSafeInteger(accepted) || accepted <= 0 || accepted > bytes.length || (ack.closed && ack.offset !== payload.length))
+                    throw new Error('Invalid ACP input acknowledgement');
+                offset = ack.offset;
+            }
+            let exit;
+            for await (const event of await this.#cell.exec.output(session.session_id, { follow: true, signal: this.#signal })) {
+                if (event.type === 'error')
+                    throw new Error(event.error?.error.message ?? 'ACP input failed');
+                if (event.type === 'exit')
+                    exit = event.session?.exit_code;
+                if (event.type === 'output' && event.stream === 'stdout' && event.data)
+                    stdout += Buffer.from(event.data, 'base64').toString();
+                if (stdout.length > 65536)
+                    throw new Error('Invalid ACP input receipt');
+            }
+            if (exit !== 0 || JSON.parse(stdout).accepted !== true)
+                throw new Error('ACP delivery is unverified; load this session before continuing.');
+        }
+        finally {
+            await this.#cell.exec.cancel(session.session_id, 0).catch(() => undefined);
+        }
+        // Never resend an uncertain mutation. Its stable input identity is fenced by CVB before provider stdin.
+    }
+    start() {
+        this.#initial ??= this.#replay().then(() => { this.#ready = true; this.#follow(); }).catch(error => { this.rpc.close(error instanceof Error ? error : new Error(String(error))); throw error; });
+        return this.#initial;
+    }
+    pause() { this.#paused++; this.#reader?.abort(); void this.#detach(); }
+    resume() { this.#paused = Math.max(0, this.#paused - 1); this.#follow(); }
+    async #entry(line) {
+        if (!line.trim())
+            return;
+        const entry = JSON.parse(line);
+        if (entry.error)
+            throw new Error(entry.error);
+        if (!Number.isSafeInteger(entry.seq) || entry.seq < 1)
+            throw new Error('Invalid ACP journal entry');
+        if (entry.seq <= this.#cursor.from_seq)
+            return;
+        if (entry.seq !== this.#cursor.from_seq + 1)
+            throw new Error('ACP journal has a sequence gap');
+        if (entry.message) {
+            if (entry.message.method === undefined && entry.message.id === this.#cursor.prompt_id) {
+                delete this.#cursor.prompt_id;
+            }
+            this.rpc.feed(Buffer.from(JSON.stringify(entry.message) + '\n'));
+            await this.rpc.drain();
+        }
+        this.#cursor.from_seq = entry.seq;
+        this.#save();
+        if (entry.ended)
+            this.rpc.close(new Error('Native ACP session ended'));
+    }
+    async #replay() {
+        const path = `/home/user/.local/share/shardflux/acp/${this.#conversation}/journal.ndjson`;
+        this.#signal.throwIfAborted();
+        const snapshot = await this.#cell.files.stat(path);
+        const decoder = new StringDecoder('utf8');
+        let tail = '';
+        for (let offset = 0; offset < snapshot.size;) {
+            this.#signal.throwIfAborted();
+            const bytes = await this.#cell.files.read(path, { offset, length: Math.min(1 << 20, snapshot.size - offset) });
+            if (!bytes.length)
+                throw new Error('ACP journal changed during replay');
+            offset += bytes.length;
+            tail += decoder.write(bytes);
+            let newline;
+            while ((newline = tail.indexOf('\n')) >= 0) {
+                const line = tail.slice(0, newline);
+                tail = tail.slice(newline + 1);
+                await this.#entry(line);
+            }
+            if (Buffer.byteLength(tail) > 4 << 20)
+                throw new Error('ACP journal frame exceeds 4 MiB');
+        }
+        // An append can straddle the snapshot cut. The follower replays that whole frame from the saved sequence.
+        decoder.end();
+    }
+    #follow() {
+        if (!this.#ready || this.#reading || !this.#wanted())
+            return;
+        const reader = new AbortController();
+        this.#reader = reader;
+        this.#reading = this.#read(reader).finally(() => { this.#reading = undefined; if (this.#reader === reader)
+            this.#reader = undefined; this.#follow(); });
+    }
+    async #read(reader) {
+        const signal = AbortSignal.any([this.#signal, reader.signal]);
+        try {
+            let failures = 0;
+            while (this.#wanted() && !signal.aborted) {
+                const decoder = new StringDecoder('utf8');
+                let tail = '', offset = 0;
+                try {
+                    const session = await this.#cell.exec.start({ argv: ['sf-agent', 'acp', 'attach', '--conversation', this.#conversation, '--from-seq', String(this.#cursor.from_seq), '--follow'], cwd: this.#cwd, timeout_ms: 0 }, signal);
+                    this.#follower = session.session_id;
+                    for await (const event of await this.#cell.exec.output(session.session_id, { follow: true, signal })) {
+                        if (event.type === 'error')
+                            throw new Error(event.error?.error.message ?? 'ACP journal failed');
+                        if (event.type === 'exit')
+                            throw new Error('ACP journal detached');
+                        if (event.type !== 'output' || event.stream !== 'stdout' || !event.data)
+                            continue;
+                        const bytes = Buffer.from(event.data, 'base64'), at = event.offset ?? offset;
+                        if (at > offset)
+                            throw new Error('ACP follower output has a byte gap');
+                        const fresh = bytes.subarray(Math.max(0, offset - at));
+                        offset = Math.max(offset, at + bytes.length);
+                        tail += decoder.write(fresh);
+                        for (let newline; (newline = tail.indexOf('\n')) >= 0;) {
+                            const line = tail.slice(0, newline);
+                            tail = tail.slice(newline + 1);
+                            await this.#entry(line);
+                            failures = 0;
+                        }
+                        if (Buffer.byteLength(tail) > 4 << 20)
+                            throw new Error('ACP journal frame exceeds 4 MiB');
+                        if (!this.#wanted())
+                            return;
+                    }
+                    if (!signal.aborted)
+                        throw new Error('ACP journal connection ended');
+                }
+                catch (error) {
+                    if (signal.aborted)
+                        break;
+                    if (++failures > 3)
+                        throw error;
+                }
+                finally {
+                    await this.#detach();
+                }
+            }
+        }
+        catch (error) {
+            this.rpc.close(error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+    async #detach() {
+        const follower = this.#follower;
+        this.#follower = undefined;
+        if (follower)
+            await this.#cell.exec.cancel(follower, 0).catch(() => undefined);
+    }
+    async close() {
+        this.#controller.abort();
+        this.rpc.close();
+        await this.#writing;
+        await this.#initial?.catch(() => undefined);
+        await this.#reading;
+        await this.#detach();
+    }
+}

package/dist/acp-models.d.ts

@@ -0,0 +1,36 @@
+import type { Workspace, WorkspaceView } from '@shardflux/sdk';
+import type { Ctx } from './commands.js';
+import type { Conversation } from './conversations.js';
+import type { AcpCatalog } from './acp-catalog.js';
+/** No prompts, login, logout or credential writes. Every child process group is
+ * terminated, including initialization failures and interrupted clients. */
+export declare const ACP_MODELS_SCRIPT: string;
+export interface AcpScope {
+    apiUrl: string;
+    organizationId: string;
+    template: string;
+}
+export declare function acpScope(apiUrl: string, ws: Pick<WorkspaceView, 'organization_id' | 'template'>): AcpScope;
+/** 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 declare class AcpModelCache {
+    #private;
+    constructor(dir: string);
+    lookup(ctx: Ctx, folder: string): {
+        scope: AcpScope;
+        catalog: AcpCatalog;
+    } | undefined;
+    remember(ctx: Ctx, folder: string, scope: AcpScope): void;
+    read(scope: AcpScope): AcpCatalog;
+    write(scope: AcpScope, catalog: AcpCatalog): void;
+}
+export declare function discoverAcpCatalog(ctx: Ctx, ws: Workspace, root: string): Promise<AcpCatalog>;
+export interface AcpPreparation {
+    allocated(conversation: Conversation, workspace: WorkspaceView): void;
+    ready(workspace: Workspace): void;
+    prepared(): void;
+}
+export interface AcpLifecycle {
+    prepare(ctx: Ctx, folder: string, name: string, callbacks: AcpPreparation): Promise<AcpCatalog>;
+}
+export declare const ACP_LIFECYCLE: AcpLifecycle;

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;
+    } };