@shardflux/cli 0.20.0 → 0.22.0

package/dist/account-scope.js

@@ -0,0 +1,246 @@
+/**
+ * Which organization and project an account command acts in: --org/--project (id or slug), else the saved default
+ * (`shard orgs use`, `shard projects use`, `shard setup`), else the only one there is; with several the usage error
+ * lists them. Also the checks that say plainly when the saved default or the API key belongs to an organization the
+ * person is no longer in, with the command that fixes it (0.20.2+), and the project a T3 Connect sign-in is scoped by.
+ */
+import { Shardflux, ShardfluxApiError } from '@shardflux/sdk';
+import { UUID } from "./args.js";
+import { AuthConfigError, NotFoundError, UsageError } from "./errors.js";
+/** commands.ts's `str`, here so this module does not import commands.ts (which imports it). */
+const str = (v) => (typeof v === 'string' ? v : undefined);
+export async function allOrgs(account) {
+    const rows = [];
+    for await (const o of account.organizations.listAll())
+        rows.push(o);
+    return rows;
+}
+export async function allProjects(account, organizationId) {
+    const rows = [];
+    for await (const p of account.projects.listAll(organizationId))
+        rows.push(p);
+    return rows;
+}
+export const choices = (rows) => rows.map((r) => `  ${r.id}  ${r.slug}  ${r.name}`).join('\n');
+export function byRef(rows, ref) {
+    const exact = rows.find((r) => r.id === ref || r.slug === ref);
+    if (exact)
+        return exact;
+    const named = rows.filter((r) => r.name.toLowerCase() === ref.toLowerCase());
+    return named.length === 1 ? named[0] : undefined;
+}
+export const gone = (err) => err instanceof ShardfluxApiError && (err.status === 404 || err.status === 403);
+export async function findOrg(account, ref) {
+    if (UUID.test(ref)) {
+        try {
+            return await account.organizations.get(ref);
+        }
+        catch (err) {
+            if (!gone(err))
+                throw err;
+            throw new NotFoundError(`Organization ${ref} is not one of yours.`, 'list yours: shard orgs list');
+        }
+    }
+    const hit = byRef(await allOrgs(account), ref);
+    if (!hit)
+        throw new NotFoundError(`No organization "${ref}" among yours.`, 'list them: shard orgs list');
+    return hit;
+}
+/** `<slug>` of the only organization, else the placeholder: the fix commands below are exact when they can be. */
+const orgArg = (orgs) => (orgs.length === 1 ? orgs[0].slug : '<id|slug>');
+/** The fix for a saved default organization the person is no longer in. */
+export function staleDefaultOrg(saved, orgs) {
+    const list = orgs.length ? `\nYour organizations:\n${choices(orgs)}\n` : '\n';
+    return new UsageError(`Your saved default organization ${saved} is no longer one of yours (it is not in shard orgs list).${list}`, orgs.length
+        ? `save another: shard orgs use ${orgArg(orgs)}   (with a new API key for it: shard setup --org ${orgArg(orgs)} --new-key)`
+        : 'create one with a project and an API key: shard setup');
+}
+/** `ref` (a positional), else --org, else the saved default, else the only organization. */
+export async function resolveOrg(ctx, account, values, ref) {
+    const given = ref ?? str(values.org);
+    if (given !== undefined)
+        return findOrg(account, given);
+    const saved = ctx.store.profile(ctx.apiUrl).organization_id;
+    if (saved) {
+        try {
+            return await account.organizations.get(saved);
+        }
+        catch (err) {
+            if (gone(err))
+                throw staleDefaultOrg(saved, await allOrgs(account));
+            throw err;
+        }
+    }
+    const orgs = await allOrgs(account);
+    if (orgs.length === 1)
+        return orgs[0];
+    if (orgs.length === 0)
+        throw new UsageError('You have no organization yet.', 'create one with a project and an API key: shard setup (or shard orgs create <name>)');
+    throw new UsageError(`You belong to ${orgs.length} organizations; pick one with --org <id|slug>:\n${choices(orgs)}\n`, 'or save a default: shard orgs use <id|slug>');
+}
+/** `ref` (a positional), else --project, else the saved default (unless --org names another), else the only project. */
+export async function resolveProject(ctx, account, values, ref) {
+    const given = ref ?? str(values.project);
+    const orgFlag = str(values.org);
+    if (given !== undefined && UUID.test(given)) {
+        const p = await account.projects.get(given);
+        if (orgFlag !== undefined) {
+            const org = await findOrg(account, orgFlag);
+            if (p.organization_id !== org.id)
+                throw new UsageError(`project ${given} is not in organization ${org.slug}`);
+        }
+        return p;
+    }
+    const profile = ctx.store.profile(ctx.apiUrl);
+    if (given === undefined && profile.project_id && orgFlag === undefined) {
+        try {
+            return await account.projects.get(profile.project_id);
+        }
+        catch (err) {
+            if (!gone(err))
+                throw err;
+            const orgs = await allOrgs(account);
+            // The whole saved default is from an organization this person left: say that, not only "the project".
+            if (profile.organization_id && !orgs.some((o) => o.id === profile.organization_id))
+                throw staleDefaultOrg(profile.organization_id, orgs);
+            throw new NotFoundError(`The default project ${profile.project_id} is no longer available to you.`, 'pick another: shard projects use <project> (list: shard projects list)');
+        }
+    }
+    const org = await resolveOrg(ctx, account, values);
+    const projects = await allProjects(account, org.id);
+    if (given !== undefined) {
+        const hit = byRef(projects, given);
+        if (!hit)
+            throw new NotFoundError(`No project "${given}" in ${org.name} (${org.slug}).`, 'list them: shard projects list');
+        return hit;
+    }
+    const saved = profile.project_id ? projects.find((p) => p.id === profile.project_id) : undefined;
+    if (saved)
+        return saved;
+    if (projects.length === 1)
+        return projects[0];
+    if (projects.length === 0)
+        throw new UsageError(`${org.name} (${org.slug}) has no project yet.`, 'create one: shard projects create <name> (or shard setup)');
+    throw new UsageError(`${org.name} has ${projects.length} projects; pick one with --project <id|slug>:\n${choices(projects)}\n`, 'or save a default: shard projects use <id|slug>');
+}
+export async function keyScope(ctx) {
+    let token;
+    let source;
+    try {
+        ({ token, source } = ctx.apiKey());
+    }
+    catch (err) {
+        if (err instanceof AuthConfigError)
+            return null;
+        throw err;
+    }
+    try {
+        const me = await new Shardflux({ ...ctx.accountOptions(), apiKey: token }).me();
+        if (me.type !== 'api_key' || !me.api_key)
+            return null;
+        return { keyId: token.split('_')[1] ?? '', source, organizationId: me.api_key.organization_id, projectId: me.api_key.project_id };
+    }
+    catch (err) {
+        // A rejected or unreadable key is reported where it is used; here it only means "no key to compare".
+        if (err instanceof ShardfluxApiError || (err instanceof Error && /apiKey must be/.test(err.message)))
+            return null;
+        throw err;
+    }
+}
+const keyName = (k) => (k.source === 'env' ? `The API key in SHARDFLUX_API_KEY (${k.keyId})` : `The saved API key ${k.keyId}`);
+/**
+ * Plain warnings about defaults that point into an organization the signed-in person is no longer in: the saved
+ * default organization, and the API key's organization. Each names the command that fixes it.
+ */
+export function staleScopeWarnings(ctx, orgs, key) {
+    const out = [];
+    const mine = (id) => orgs.some((o) => o.id === id);
+    const arg = orgArg(orgs);
+    const saved = ctx.store.profile(ctx.apiUrl).organization_id;
+    if (saved && !mine(saved)) {
+        out.push({ code: 'default_organization_gone', message: `Your saved default organization ${saved} is no longer one of yours (it is not in shard orgs list).`, fix: `shard orgs use ${arg}` });
+    }
+    const target = orgs.find((o) => o.id === saved);
+    const warning = key ? keyOrganizationWarning(key, orgs, target) : null;
+    if (warning)
+        out.push(warning);
+    return out;
+}
+/** Compare membership before defaults: a departed organization is different from another one still accessible. */
+export function keyOrganizationWarning(key, orgs, target, projectId) {
+    const departed = !orgs.some((o) => o.id === key.organizationId);
+    if (!departed && (!target || key.organizationId === target.id))
+        return null;
+    const arg = target?.slug ?? orgArg(orgs);
+    const command = target || orgs.length ? `shard setup --org ${arg}${projectId ? ` --project ${projectId}` : ''} --new-key` : 'shard setup --new-key';
+    return {
+        code: departed ? 'api_key_organization_gone' : 'api_key_in_other_organization',
+        message: departed
+            ? `${keyName(key)} belongs to organization ${key.organizationId}, which you are no longer in; commands that use the key still act there.`
+            : keyElsewhere(key, target),
+        fix: `${command}${key.source === 'env' ? ', then unset SHARDFLUX_API_KEY' : ''}`,
+    };
+}
+/**
+ * The stale-default warnings for the signed-in person, or none: without a session (or with one the API no longer
+ * accepts) there is no list of their organizations to compare with, and the command itself goes on either way.
+ */
+export async function sessionScopeWarnings(ctx, key) {
+    if (ctx.sessionSource() === null)
+        return [];
+    let orgs;
+    try {
+        orgs = await allOrgs(ctx.account());
+    }
+    catch (err) {
+        if (err instanceof ShardfluxApiError || err instanceof AuthConfigError)
+            return [];
+        throw err;
+    }
+    return staleScopeWarnings(ctx, orgs, key);
+}
+/** Warnings on stderr, one `warning:` line and its `fix:` each (text mode). */
+export function writeWarnings(ctx, warnings) {
+    if (ctx.json)
+        return;
+    for (const w of warnings)
+        ctx.io.stderr.write(`warning: ${w.message}\nfix: ${w.fix}\n`);
+}
+/** The note for a default just saved in `org` while the API key acts in another organization (orgs use, projects use). */
+export function keyElsewhere(key, org) {
+    return `${keyName(key)} belongs to organization ${key.organizationId}, not ${org.name} (${org.slug}): workspace, agent and usage commands use the key, so they still act there.`;
+}
+// ---- T3 Connect --------------------------------------------------------------------------------------------------
+/**
+ * The project a T3 Connect sign-in is scoped by (0.20.2+). A sign-in is per person and organization, and a session in
+ * more than one organization must name one (the API answers 422 without `project_id`). --project, else a project of
+ * --org (the saved default or the key's project when it is in that organization, else its first), else the API key's
+ * project (T3 links the key's workspaces with the sign-in of the key's organization, and the onboarding row checks it
+ * with the key), else the saved default project. Undefined when none is known: one organization needs none.
+ */
+export async function t3SignInProject(ctx, values) {
+    const profile = ctx.store.profile(ctx.apiUrl);
+    const project = str(values.project);
+    if (project !== undefined && UUID.test(project) && str(values.org) === undefined)
+        return project;
+    if (project !== undefined)
+        return (await resolveProject(ctx, ctx.account(), values)).id;
+    if (str(values.org) !== undefined) {
+        const account = ctx.account();
+        const org = await resolveOrg(ctx, account, values);
+        const projects = await allProjects(account, org.id);
+        const pick = projects.find((p) => p.id === profile.project_id) ?? projects.find((p) => p.id === profile.api_key?.project_id) ?? projects[0];
+        if (!pick)
+            throw new UsageError(`${org.name} (${org.slug}) has no project yet.`, `create one: shard projects create <name> --org ${org.slug}`);
+        return pick.id;
+    }
+    // The saved key's project is in the credentials file; a key in SHARDFLUX_API_KEY (which wins) is asked where it acts.
+    const key = ctx.io.env.SHARDFLUX_API_KEY?.trim() ? (await keyScope(ctx))?.projectId : profile.api_key?.project_id;
+    return key ?? profile.project_id;
+}
+/** The API's 422 for a session in several organizations without a project (production before train 22): what to run. */
+export function t3NeedsProject(err) {
+    if (!(err instanceof ShardfluxApiError) || err.code !== 'validation_failed' || err.details?.field !== 'project_id')
+        return null;
+    return new UsageError('You belong to more than one organization, and T3 Connect signs you in for one of them.', 'name it: --project <id|slug> (or --org <id|slug>), or save a default: shard projects use <id|slug>');
+}

package/dist/acp-login.d.ts

@@ -1,7 +1,8 @@
 import type { Ctx } from './commands.js';
 /**
- * The ACP terminal sign-in method. An editor (T3 Code) runs `shard acp --login` in its own terminal when the user
- * chooses it, then reconnects; ACP appends these args to the configured `shard acp` invocation.
+ * The ACP terminal sign-in method. An editor runs it in its own terminal when the user chooses it, then reconnects:
+ * T3 Code appends these args to the configured `shard acp` (`shard acp --login`); ACP registry clients run the agent
+ * with them in place of `acp` (`shard --login`). Both start the same flow.
  */
 export declare const ACP_LOGIN_METHOD: {
     readonly id: "shardflux-login";
@@ -14,7 +15,7 @@ export declare const ACP_LOGIN_METHOD: {
 export declare function acpSignedIn(ctx: Ctx): boolean;
 /**
  * `shard acp --login`: everything a first conversation needs, each step skipped when it is already done: the
- * account (signed up or in with this Mac's Codex login, else an email), its API key, the Codex login copy and the
+ * account (signed up or in with this computer's Codex login, else an email), its API key, the Codex login copy and the
  * cloud Claude sign-in.
  */
 export declare function runAcpLogin(ctx: Ctx): Promise<number>;

package/dist/acp-login.js

@@ -5,9 +5,11 @@ import { join } from 'node:path';
 import { describeError } from "./errors.js";
 import { cloudClaudeLogin, loginClaudeInWorkspace } from "./claude-cloud-login.js";
 import { syncAgentCredentials } from "./agent-credentials.js";
+import { thisComputer } from "./this-computer.js";
 /**
- * The ACP terminal sign-in method. An editor (T3 Code) runs `shard acp --login` in its own terminal when the user
- * chooses it, then reconnects; ACP appends these args to the configured `shard acp` invocation.
+ * The ACP terminal sign-in method. An editor runs it in its own terminal when the user chooses it, then reconnects:
+ * T3 Code appends these args to the configured `shard acp` (`shard acp --login`); ACP registry clients run the agent
+ * with them in place of `acp` (`shard --login`). Both start the same flow.
  */
 export const ACP_LOGIN_METHOD = {
     id: 'shardflux-login',
@@ -44,7 +46,7 @@ async function accountReady(ctx) {
 const say = (ctx, text) => { ctx.io.stderr.write(text); };
 /**
  * `shard acp --login`: everything a first conversation needs, each step skipped when it is already done: the
- * account (signed up or in with this Mac's Codex login, else an email), its API key, the Codex login copy and the
+ * account (signed up or in with this computer's Codex login, else an email), its API key, the Codex login copy and the
  * cloud Claude sign-in.
  */
 export async function runAcpLogin(ctx) {
@@ -63,7 +65,7 @@ export async function runAcpLogin(ctx) {
             await setup();
         }
         else if (codex) {
-            say(ctx, 'Signing in with the Codex login on this Mac…\n');
+            say(ctx, `Signing in with the Codex login on ${thisComputer()}…\n`);
             await HANDLERS.signup(quiet, { setup: false }, []);
             await setup();
         }
@@ -95,7 +97,7 @@ export async function runAcpLogin(ctx) {
         say(ctx, 'Already signed in.\n');
     if (codex) {
         await syncAgentCredentials(ctx.cloud(), { home, redact: (value) => ctx.addSecret(value) });
-        say(ctx, 'Codex: connected with the login on this Mac.\n');
+        say(ctx, `Codex: connected with the login on ${thisComputer()}.\n`);
     }
     if (await cloudClaudeLogin(ctx))
         say(ctx, 'Claude Code: connected.\n');

package/dist/acp-models.js

@@ -1,14 +1,13 @@
 import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
 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 { localChanges, seedAgentRepository } from "./agent-repository.js";
+import { checkoutConversationBranch, createConversationRecord, conversationWorkspace } from "./conversations.js";
 import { AgentStateStore } from "./agent-state.js";
 import { objectValue } from "./acp-rpc.js";
 import { nativeCurrentModel, nativeModelOptions } from "./acp-catalog.js";
-import { recordSeedSnapshot } from "./files-mirror.js";
-import { sendTwinSeed, twinCheckoutArgv } from "./worktree-twin.js";
+import { sendTwinSeed } from "./worktree-twin.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 `
@@ -131,29 +130,35 @@ export async function discoverAcpCatalog(ctx, ws, root) {
         throw new Error('The guest adapters returned no available models. Check your cloud agent sign-ins.');
     return catalog;
 }
+/** The project files the adapters read for their settings and MCP servers. */
+const ACP_INITIAL_FILES = ['.claude/settings.json', '.claude/settings.local.json', '.codex/config.toml', '.mcp.json'];
 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);
+        // This computer's changes are read while the VM starts (0.21.1+). Its agent config follows the first prompt (acp.ts).
+        const changes = localChanges(folder, ctx.signal);
+        changes.catch(() => undefined);
         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 });
+        const background = [];
         let initialReady, initialFailed;
         const initialFiles = new Promise((resolve, reject) => { initialReady = resolve; initialFailed = reject; });
+        // The adapters read the project's own agent settings when it has any: discovery then waits for those files. A
+        // project without them is discovered while it seeds (0.21.1+): the catalog depends on the account, not the files.
+        const projectSettings = ACP_INITIAL_FILES.some(path => existsSync(join(folder, path)));
         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 });
+            await seedAgentRepository(ctx, ws, folder, { root: c.worktree_path, populate: true, changes, background: started => background.push(started),
+                initialFiles: ACP_INITIAL_FILES, onInitialFiles: initialReady });
             await sendTwinSeed(ctx.store.dir, ws.cell(), c, folder, ctx.signal);
-            const result = await ws.cell().exec.run(twinCheckoutArgv(ctx.store.dir, c), { timeoutMs: 30_000, signal: ctx.signal });
-            if (result.exitCode !== 0)
-                throw new Error(`Conversation branch could not be prepared: ${result.stderr.trim()}`);
-            await recordSeedSnapshot(ws, c, ctx.signal);
+            await checkoutConversationBranch(ctx, ws.cell(), c);
+            await Promise.all(background);
             callbacks.prepared();
         })();
         void seeded.catch(initialFailed);
-        const models = (async () => { await initialFiles; return discoverAcpCatalog(ctx, ws, c.worktree_path); })();
+        const models = (async () => { if (projectSettings)
+            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]);

package/dist/acp.js

@@ -8,12 +8,16 @@ 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 { projectSyncBoundary } from "./project-sync.js";
+import { localManifest } from "./project-sync-manifest.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 { ACP_LOGIN_METHOD, acpSignedIn } from "./acp-login.js";
 import { ensureMenubar, MenubarManager } from "./menubar.js";
+import { syncAgentConfigAfterStart } from "./agent-config-sync.js";
+import { savedMachine } from "./filesystem-state.js";
 const PREFIX = 'shardflux:';
 export function acpModel(app, id) { return `${PREFIX}${app}:${id}`; }
 export function parseAcpModel(value) {
@@ -196,11 +200,16 @@ export class ShardfluxAcp {
         }
         if (!record.model)
             throw new RpcError(-32602, 'Choose an available model before sending a message.');
-        await this.#connect(session);
+        const started = 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);
+        const first = method === 'session/prompt' && !record.prompted;
         if (method === 'session/prompt') {
+            // A connection this prompt started has just reconciled the project files, and settled them unless that pass
+            // moved some (0.21.1+).
+            if (!started || !session.files.settled())
+                await session.files.reconcile();
             record.prompted = true;
             record.updatedAt = new Date().toISOString();
             this.#save(record);
@@ -209,13 +218,23 @@ export class ShardfluxAcp {
             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));
+            const answer = session.transport.rpc.request(method, mapped, method === 'session/prompt' ? 0 : 120_000);
+            // Without a saved machine this computer's agent config is copied in once the first prompt is on its way, never
+            // before it (0.21.1+), as for a terminal conversation.
+            if (first && session.ws && !(await savedMachine(this.#ctx).catch(() => undefined))?.template)
+                void syncAgentConfigAfterStart(this.#ctx, session.ws);
+            result = objectValue(await answer);
         }
         catch (e) {
             if (method === 'session/prompt')
                 await this.#rejectModel(session, parseAcpModel(record.model).id, e);
             throw e;
         }
+        finally {
+            // T3 snapshots the local checkout as soon as the prompt response arrives.
+            if (method === 'session/prompt' && !this.#ctx.signal.aborted && !session.stop.signal.aborted)
+                await session.files.reconcile();
+        }
         return this.#configuration(record.model, acpReferences(result, record, session.conversation.worktree_path), record.catalog);
     }
     #prepare(session) {
@@ -226,6 +245,12 @@ export class ShardfluxAcp {
         // 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; });
+        // This computer's file hashes are read while the VM starts and seeds: the first prompt's reconcile then hashes only
+        // what changed since (0.21.1+). Best effort; the reconcile reads whatever is missing.
+        if (!session.hashes) {
+            session.hashes = new Map();
+            void localManifest(record.folder, ctx.signal, session.hashes).catch(() => undefined);
+        }
         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('-', '')}`, {
@@ -329,25 +354,34 @@ export class ShardfluxAcp {
         }
         return session;
     }
+    /** True when this call started the connection (and so reconciled the project files just now). */
     async #connect(session) {
         await session.prepared;
         if (session.preparationError)
             throw session.preparationError;
-        if (session.connecting)
-            return session.connecting;
+        if (session.connecting) {
+            await session.connecting;
+            return false;
+        }
         if (session.transport && !session.transport.rpc.closed)
-            return;
+            return false;
         session.connecting = this.#start(session).finally(() => { session.connecting = undefined; });
-        return session.connecting;
+        await session.connecting;
+        return true;
     }
     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, 'Authentication required: connect Claude Code.', { code: 'unauthenticated', fix: SIGN_IN });
+        // The sign-in is checked beside reading the conversation and its VM; it passes before anything starts in the VM.
+        const signIn = (async () => {
+            await syncAgentCredentials(ctx.cloud(), { home: ctx.io.env.HOME, redact: value => ctx.addSecret(value) });
+            if (app === 'claude' && !(await cloudClaudeLogin(ctx)))
+                throw new RpcError(-32000, 'Authentication required: connect Claude Code.', { code: 'unauthenticated', fix: SIGN_IN });
+        })();
+        signIn.catch(() => undefined);
         if (!record.conversationId) {
+            await signIn;
             this.#prepare(session);
             await session.prepared;
             if (session.preparationError)
@@ -361,10 +395,26 @@ export class ShardfluxAcp {
             session.ws = await conversationWorkspace(ctx, session.conversation);
             rememberConversation(ctx, session.conversation, record.folder);
         }
+        await signIn;
         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 }));
+        const menubar = ensureMenubar(ctx.store.dir, ctx.apiUrl, new MenubarManager({ home: ctx.io.env.HOME, signal: ctx.signal }));
         await restoreConversationBinding(ctx, c, session.ws);
+        // The project files are reconciled, device approvals served and the supervisor launched side by side; the native
+        // session starts once all three are done (0.21.1+).
+        const files = (async () => {
+            const boundary = await projectSyncBoundary({ ...ctx, signal: AbortSignal.any([ctx.signal, session.stop.signal]) }, session.ws, projectIdentity(record.folder), {
+                root: c.worktree_path, agent: record.id.replace(/^sf-/, 'acp-'), seed: false,
+                stateKey: `acp:${ctx.apiUrl}:${record.id}:${record.folder}`, ...(session.hashes ? { cache: session.hashes } : {}),
+                // Before its first prompt the VM holds what this computer seeded it with, so edits made here since are not conflicts.
+                vmBaseline: !record.prompted,
+            });
+            await boundary.reconcile();
+            return boundary;
+        })();
+        const launch = cell.exec.run(['sf-agent', 'acp', app, '--conversation', c.id, '--detach'], { cwd: c.worktree_path, timeoutMs: 30_000, signal: ctx.signal, maxOutputBytes: 1 << 20 });
+        files.catch(() => undefined);
+        launch.catch(() => undefined);
         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' },
@@ -372,15 +422,18 @@ export class ShardfluxAcp {
             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 });
+        session.files = await files;
+        const launched = await launch;
+        await menubar;
         if (launched.exitCode !== 0)
             throw new Error(`ACP supervisor could not attach: ${launched.stderr.trim()}`);
-        c = await getConversation(ctx, c.id);
+        const [claimed, statusText] = await Promise.all([getConversation(ctx, c.id), cell.files.readText(`/home/user/.local/share/shardflux/acp/${c.id}/status.json`, { length: 8192 })]);
+        c = claimed;
         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 }));
+        const status = JSON.parse(statusText);
         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}`;

package/dist/agent-commands.d.ts

@@ -7,13 +7,15 @@ import type { ModelChoice } from './agent-models.js';
 export declare function disambiguatedSlug(slug: string, identity: string): string;
 export declare function projectTemplate(ctx: Ctx, remote: string | null): Promise<string>;
 /** `place` is the repository or folder name session titles end with ("todo-app"), `task` what a new session is titled
- * with before the guest names it from its first prompt (a first prompt line or the conversation's title). */
+ * with before the guest names it from its first prompt (a first prompt line or the conversation's title), and
+ * `launch.titlePrefix` the marker titles start with when this computer chose one ("" for none; 0.20.1+). */
 export declare function agentPty(cell: CellClient, app: 'claude' | 'codex', agent: string, approvals: boolean, term: string, signal?: AbortSignal, place?: string, setupHash?: string, cwd?: string, ptyName?: string, onLaunch?: () => void, deferSetup?: boolean, conversation?: {
     id: string;
     session: string | null;
 }, task?: string, launch?: {
     choice?: ModelChoice;
     help?: () => Promise<string>;
+    titlePrefix?: string;
 }): Promise<PtySession>;
 /** The first non-empty line of a prompt or title, bounded; the guest makes it the task part of the session title. */
 export declare function sessionTask(text: string | undefined): string | undefined;
@@ -24,6 +26,7 @@ export declare function terminal(ctx: Ctx, ws: Workspace, app: 'claude' | 'codex
     title?: string;
     choice?: ModelChoice;
     afterStart?: () => Promise<void> | undefined;
+    setupLabelled?: Promise<void>;
 }): Promise<number>;
 export declare const launchProject: Handler;
 /** The project VM launch; with `--in t3` a first message becomes a thread on the T3 server in it (SSH mode, 0.17.0+). */