@shardflux/cli 0.18.1 → 0.19.1

package/dist/move.js

@@ -0,0 +1,248 @@
+/**
+ * `shard move` (0.19.0+): a Claude Code or Codex session on this computer continues in a cloud conversation as the same
+ * session, with its full history.
+ *
+ * 1. Waits until the session's current turn has ended (local-sessions.ts); a turn is never cut off.
+ * 2. Starts a conversation from the live twin's snapshot of the project (uncommitted edits included; the working
+ *    tree, index and HEAD are not touched) whose record starts with the session (harness_session_id).
+ * 3. Puts the transcript, its paths rewritten to the VM's folder, at the harness's native path in the VM and as the
+ *    conversation's durable copy in the project space, before the repository is seeded.
+ * 4. The VM's guest resumes it (`claude --resume <id>`, `codex resume <id>`); this command attaches or detaches.
+ * 5. Records the move here; the live twin brings the cloud work back to this checkout, and typing in the local copy
+ *    shows one line saying it diverges (a Claude Code UserPromptSubmit hook; the local process is never stopped).
+ */
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { existsSync, realpathSync } from 'node:fs';
+import { dirname, relative, resolve } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { ShardfluxApiError } from '@shardflux/sdk';
+import { out, str } from "./commands.js";
+import { UsageError } from "./errors.js";
+import { projectIdentity } from "./project-identity.js";
+import { createConversation, conversationEnded, getConversation } from "./conversations.js";
+import { syncAgentCredentials } from "./agent-credentials.js";
+import { cloudClaudeLogin, loginClaudeInWorkspace, requireClaudeTerminal } from "./claude-cloud-login.js";
+import { syncAgentConfig } from "./agent-config-sync.js";
+import { savedMachine } from "./filesystem-state.js";
+import { ensureMenubar, MenubarManager } from "./menubar.js";
+import { conversationTerminal } from "./conversation-terminal.js";
+import { openInChoices } from "./t3-mode.js";
+import { openClaudeDesktopSession, remoteControlUrl } from "./agent-target-commands.js";
+import { openUrl } from "./browser.js";
+import { SYNC_CHUNK_BYTES } from "./project-sync-transfer.js";
+import { completeRecords, continuedAfter, findLocalSession, homeRelativeTranscript, listLocalSessions, readTranscript, rewriteSessionPaths, sessionState } from "./local-sessions.js";
+import { installDivergenceNotice, movedKey, movedSession, movedSessions, rememberMoved } from "./moved-sessions.js";
+const VM_HOME = '/home/user';
+const SPACE = '/shardflux/project';
+/** A transcript above this moves with the repository's history bound. */
+const TRANSCRIPT_LIMIT = 256 << 20;
+// ---------------------------------------------------------------------------------------------------------------
+// Choosing and waiting
+/** The project a folder belongs to: its Git repository's top, or the folder itself. */
+export function projectRoot(folder) {
+    try {
+        return realpathSync(execFileSync('git', ['-C', folder, 'rev-parse', '--show-toplevel'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000 }).trim());
+    }
+    catch {
+        return realpathSync(folder);
+    }
+}
+function harnessOf(values) {
+    if (values.claude === true && values.codex === true)
+        throw new UsageError('Choose --claude or --codex.');
+    return values.claude === true ? 'claude' : values.codex === true ? 'codex' : undefined;
+}
+export function chooseSession(values, env, folder) {
+    const id = str(values.session);
+    if (id) {
+        const s = findLocalSession(id.toLowerCase(), env);
+        if (!s)
+            throw new UsageError('No Claude Code or Codex session with that id on this computer.');
+        return s;
+    }
+    if (values.last !== true)
+        throw new UsageError('Choose --last or --session <id> (shard move --list shows this project’s sessions).');
+    const [s] = listLocalSessions(folder, env, { harness: harnessOf(values), limit: 1 });
+    if (!s)
+        throw new UsageError('This project has no Claude Code or Codex sessions on this computer.');
+    return s;
+}
+/** Until the session's turn has ended: a running turn is never cut off. */
+export async function waitForTurnEnd(ctx, s, env, pollMs = 1000) {
+    let said = false;
+    for (;;) {
+        const state = sessionState(s, env);
+        if (state.turn === 'idle')
+            return state;
+        if (!said && !ctx.json) {
+            ctx.io.stderr.write('Waiting for the current turn to end…\n');
+            said = true;
+        }
+        await delay(pollMs, undefined, { signal: ctx.signal });
+    }
+}
+async function writeChunks(cell, path, bytes) {
+    if (!bytes.length) {
+        await cell.files.write(path, '', { mode: '0600' });
+        return;
+    }
+    for (let at = 0; at < bytes.length; at += SYNC_CHUNK_BYTES)
+        await cell.files.write(path, bytes.subarray(at, at + SYNC_CHUNK_BYTES), { mode: '0600', append: at > 0 });
+}
+/**
+ * The session's transcript in the conversation's VM: at its native path (where the harness resumes it) and, when the
+ * project space is mounted, as the conversation's durable copy with the same checkpoint metadata the guest writes
+ * (transcripts/<id>/meta.json), so the session survives the VM from its first minute.
+ */
+export async function placeTranscript(cell, c, s, bytes, folder, signal) {
+    const sessionCwd = realOr(s.cwd), inside = relative(folder, sessionCwd);
+    if (inside.startsWith('..'))
+        throw new UsageError('The session ran outside this project folder; run shard move in its project.');
+    let moved = rewriteSessionPaths(bytes, folder, c.worktree_path);
+    if (s.cwd !== sessionCwd && !s.cwd.startsWith(`${folder}/`) && s.cwd !== folder) {
+        // The transcript recorded a path through a link (/tmp for /private/tmp): move that spelling too.
+        moved = rewriteSessionPaths(moved, s.cwd.slice(0, s.cwd.length - inside.length).replace(/\/$/, ''), c.worktree_path);
+    }
+    const homeRelative = homeRelativeTranscript(s, c.worktree_path);
+    const native = `${VM_HOME}/${homeRelative}`;
+    await cell.files.mkdir(dirname(native), { parents: true });
+    await writeChunks(cell, native, moved);
+    const mounted = await cell.exec.run(['test', '-d', `${SPACE}/git/hub.git`], { timeoutMs: 10_000, ...(signal ? { signal } : {}) });
+    if (mounted.exitCode !== 0)
+        return { native, durable: false };
+    const dir = `${SPACE}/transcripts/${c.id}`, file = homeRelative.split('/').at(-1);
+    await cell.files.mkdir(dir, { parents: true });
+    await writeChunks(cell, `${dir}/${file}`, moved);
+    const meta = { harness: c.harness, harness_session_id: s.session_id, file, home_relative: homeRelative, cwd: c.worktree_path, bytes: moved.length,
+        sha256: createHash('sha256').update(moved).digest('hex') };
+    await cell.files.write(`${dir}/meta.json`, JSON.stringify(meta), { mode: '0600' });
+    return { native, durable: true };
+}
+const realOr = (path) => { try {
+    return realpathSync(path);
+}
+catch {
+    return resolve(path);
+} };
+async function alreadyMoved(ctx, m) {
+    try {
+        const c = await getConversation(ctx, m.conversation_id);
+        return conversationEnded(c) ? undefined : c;
+    }
+    catch (e) {
+        if (e instanceof ShardfluxApiError && e.status === 404)
+            return undefined;
+        throw e;
+    }
+}
+export async function moveSession(ctx, values) {
+    const env = { ...process.env, ...ctx.io.env };
+    const here = projectRoot(typeof values.path === 'string' ? values.path : process.cwd());
+    const s = chooseSession(values, env, here);
+    const folder = typeof values.path === 'string' ? here : projectRoot(existsSync(s.cwd) ? s.cwd : here);
+    const prior = movedSession(ctx.store.dir, ctx.apiUrl, s.harness, s.session_id);
+    if (prior) {
+        const live = await alreadyMoved(ctx, prior);
+        if (live) {
+            out(ctx, `This session already continues in the cloud as ${prior.key}. Open it: shard agents open ${prior.key}\n`, { already: true, moved: prior, conversation: live });
+            return 0;
+        }
+    }
+    await waitForTurnEnd(ctx, s, env);
+    const bytes = completeRecords(readTranscript(s.file));
+    if (bytes.length > TRANSCRIPT_LIMIT)
+        throw new UsageError('This session’s transcript is above the 256 MiB move bound.');
+    const sha256 = createHash('sha256').update(bytes).digest('hex');
+    if (!ctx.json)
+        ctx.io.stderr.write(`Moving ${s.harness === 'claude' ? 'Claude Code' : 'Codex'} session “${s.title}” to the cloud…\n`);
+    await syncAgentCredentials(ctx.cloud(), { home: ctx.io.env.HOME, redact: value => ctx.addSecret(value) });
+    const signedIn = s.harness === 'claude' ? await cloudClaudeLogin(ctx) : true;
+    if (!signedIn)
+        requireClaudeTerminal(ctx);
+    let created;
+    let placed;
+    try {
+        created = await createConversation(ctx, folder, s.harness, 'terminal', undefined, {}, {
+            session_id: s.session_id, title: s.title,
+            // The workspace's cell handle is shared with the seed that follows: it stays open.
+            beforeSeed: async (ws, c) => { placed = await placeTranscript(ws.cell(), c, s, bytes, folder, ctx.signal); },
+        });
+    }
+    catch (e) {
+        if (e instanceof ShardfluxApiError && e.details?.reason === 'session_already_moved' && typeof e.details.conversation_id === 'string') {
+            const c = await getConversation(ctx, e.details.conversation_id);
+            out(ctx, `This session already continues in the cloud as ${c.key}. Open it: shard agents open ${c.key}\n`, { already: true, conversation: c });
+            return 0;
+        }
+        throw e;
+    }
+    const { conversation: c, workspace: ws } = created;
+    const moved = { api_url: ctx.apiUrl, harness: s.harness, session_id: s.session_id, folder, file: s.file, bytes: bytes.length, sha256,
+        conversation_id: c.id, key: c.key, title: s.title, moved_at: new Date().toISOString() };
+    rememberMoved(ctx.store.dir, moved);
+    try {
+        installDivergenceNotice(ctx.store.dir, env, moved);
+    }
+    catch (e) {
+        ctx.io.stderr.write(`The local divergence notice is unavailable: ${e instanceof Error ? e.message : String(e)}\n`);
+    }
+    if (s.harness === 'claude' && !signedIn)
+        await loginClaudeInWorkspace(ctx, ws);
+    if (!(await savedMachine(ctx))?.template)
+        await syncAgentConfig(ctx, ws);
+    // The live twin (the menu bar's device helper) brings the cloud work back to this checkout.
+    await ensureMenubar(ctx.store.dir, ctx.apiUrl, new MenubarManager({ home: ctx.io.env.HOME, signal: ctx.signal }));
+    const project = projectIdentity(folder), place = project.remote ?? project.folder;
+    const attach = !ctx.json && values.detach !== true && ctx.io.stdin.isTTY === true;
+    if (!attach) {
+        const quiet = { ...ctx, io: { ...ctx.io, stdout: { write: () => true } } };
+        await conversationTerminal(quiet, ws, c, place, { ...values, detach: true });
+        out(ctx, `Moved to the cloud as ${c.key}: the same session, with its history. Open it: shard agents open ${c.key}\n`, { moved, conversation: c, workspace: ws.data, ...(placed ? { transcript: placed } : {}) });
+        return 0;
+    }
+    const where = openInChoices(ctx, project.slug)[s.harness];
+    if (s.harness === 'claude' && (where === 'claude-desktop' || where === 'web')) {
+        const quiet = { ...ctx, io: { ...ctx.io, stdout: { write: () => true } } };
+        await conversationTerminal(quiet, ws, c, place, { ...values, detach: true });
+        if (where === 'claude-desktop')
+            return openClaudeDesktopSession(ctx, ws, c);
+        const url = await remoteControlUrl(ctx, ws, c);
+        if (!openUrl(url, ctx.io.env))
+            throw new Error(`could not open ${url}`);
+        out(ctx, `${url}\n`, { moved, conversation: c, url });
+        return 0;
+    }
+    ctx.io.stderr.write(`Moved to the cloud as ${c.key}: the same session, with its history.\n`);
+    return conversationTerminal(ctx, ws, c, place, values);
+}
+/** `shard move --list`: this project's sessions on this computer, and where each moved one continues. */
+export function listMovable(ctx, values, env, now = Date.now()) {
+    const folder = projectRoot(typeof values.path === 'string' ? values.path : process.cwd());
+    const moved = movedSessions(ctx.store.dir, ctx.apiUrl);
+    const sessions = listLocalSessions(folder, env, { harness: harnessOf(values), limit: 10 }).map(s => {
+        const m = moved[movedKey(s.harness, s.session_id)];
+        const state = sessionState(s, env, now);
+        return { harness: s.harness, session_id: s.session_id, title: s.title, updated_at: s.updated_at, source: s.source, cwd: s.cwd,
+            running: state.running, turn: state.turn,
+            moved: m ? { conversation_id: m.conversation_id, key: m.key, moved_at: m.moved_at, diverged: continuedAfter(s, m.bytes) } : null };
+    });
+    return { folder, sessions };
+}
+const ago = (iso, now = Date.now()) => {
+    const s = Math.max(0, Math.round((now - Date.parse(iso)) / 1000));
+    return s < 90 ? 'just now' : s < 5400 ? `${Math.round(s / 60)} min ago` : s < 129600 ? `${Math.round(s / 3600)} h ago` : `${Math.round(s / 86400)} d ago`;
+};
+export const MOVE_HANDLERS = {
+    async move(ctx, values) {
+        if (values.list === true) {
+            const env = { ...process.env, ...ctx.io.env };
+            const r = listMovable(ctx, values, env);
+            const lines = r.sessions.map(s => `${s.session_id}  ${s.harness.padEnd(6)}  ${s.title}  ·  ${ago(s.updated_at)}${s.turn === 'working' ? '  ·  working' : ''}`
+                + (s.moved ? `  ·  in the cloud as ${s.moved.key}${s.moved.diverged ? ' (continued here too)' : ''}` : ''));
+            out(ctx, lines.length ? `${lines.join('\n')}\n` : `No Claude Code or Codex sessions in ${r.folder} on this computer.\n`, r);
+            return 0;
+        }
+        return moveSession(ctx, values);
+    },
+};

package/dist/moved-sessions.d.ts

@@ -0,0 +1,33 @@
+import type { SessionHarness } from './local-sessions.js';
+export interface MovedSession {
+    api_url: string;
+    harness: SessionHarness;
+    session_id: string;
+    folder: string;
+    /** The local transcript and how much of it moved (bytes, their SHA-256). */
+    file: string;
+    bytes: number;
+    sha256: string;
+    conversation_id: string;
+    key: string;
+    title: string;
+    moved_at: string;
+}
+type Env = Record<string, string | undefined>;
+export declare const movedKey: (harness: SessionHarness, id: string) => string;
+export declare function movedSessions(dir: string, apiUrl?: string): Record<string, MovedSession>;
+export declare function movedSession(dir: string, apiUrl: string, harness: SessionHarness, id: string): MovedSession | undefined;
+export declare function rememberMoved(dir: string, m: MovedSession): void;
+/** Whether the local copy still holds exactly what moved (it may have grown by metadata, never by a turn). */
+export declare function movedUnchanged(m: MovedSession): boolean;
+export declare const NOTICE_SCRIPT = "#!/bin/sh\n# Shardflux (shard move): one line when you type in a session that continues in the cloud. Nothing else.\ninput=$(cat)\nid=\"${CLAUDE_CODE_SESSION_ID:-}\"\n[ -n \"$id\" ] || id=$(printf '%s' \"$input\" | sed -n 's/.*\"session_id\" *: *\"\\([0-9a-f-]*\\)\".*/\\1/p' | head -n 1)\nf=\"$(dirname \"$0\")/$id.json\"\n[ -n \"$id\" ] && [ -f \"$f\" ] && cat \"$f\"\nexit 0\n";
+/** The hook command: silent and successful where the script is absent (a settings file copied into a VM). */
+export declare const noticeCommand: (dir: string) => string;
+export declare const noticeLine: (m: Pick<MovedSession, "key">) => string;
+/**
+ * The one-line divergence notice: a marker per moved session, and (Claude Code) a UserPromptSubmit hook in the user's
+ * settings that prints the marker's systemMessage when one exists. Claude Code reloads its settings, so a session
+ * that is still open shows it on its next prompt. Codex asks people to review new hooks, so Codex sessions get none.
+ */
+export declare function installDivergenceNotice(dir: string, env: Env, m: MovedSession): void;
+export {};

package/dist/moved-sessions.js

@@ -0,0 +1,91 @@
+/**
+ * Sessions this computer moved to the cloud (`shard move`, 0.19.0+): the local record (agents.json "moved_sessions")
+ * and the one-line notice a moved session shows when someone types in its local copy.
+ */
+import { createHash } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { AgentStateStore } from "./agent-state.js";
+import { claudeConfigDir, continuedAfter, readTranscript } from "./local-sessions.js";
+export const movedKey = (harness, id) => `${harness}:${id}`;
+export function movedSessions(dir, apiUrl) {
+    const all = (new AgentStateStore(dir).read().moved_sessions ?? {});
+    return Object.fromEntries(Object.entries(all).filter(([, m]) => !apiUrl || m.api_url === apiUrl));
+}
+export function movedSession(dir, apiUrl, harness, id) {
+    return movedSessions(dir, apiUrl)[movedKey(harness, id)];
+}
+export function rememberMoved(dir, m) {
+    new AgentStateStore(dir).update(doc => {
+        const all = (doc.moved_sessions ?? {});
+        all[movedKey(m.harness, m.session_id)] = m;
+        doc.moved_sessions = all;
+    });
+}
+/** Whether the local copy still holds exactly what moved (it may have grown by metadata, never by a turn). */
+export function movedUnchanged(m) {
+    try {
+        const bytes = readTranscript(m.file);
+        return bytes.length >= m.bytes && createHash('sha256').update(bytes.subarray(0, m.bytes)).digest('hex') === m.sha256
+            && !continuedAfter({ harness: m.harness, file: m.file }, m.bytes);
+    }
+    catch {
+        return false;
+    }
+}
+export const NOTICE_SCRIPT = `#!/bin/sh
+# Shardflux (shard move): one line when you type in a session that continues in the cloud. Nothing else.
+input=$(cat)
+id="\${CLAUDE_CODE_SESSION_ID:-}"
+[ -n "$id" ] || id=$(printf '%s' "$input" | sed -n 's/.*"session_id" *: *"\\([0-9a-f-]*\\)".*/\\1/p' | head -n 1)
+f="$(dirname "$0")/$id.json"
+[ -n "$id" ] && [ -f "$f" ] && cat "$f"
+exit 0
+`;
+const noticeDir = (dir) => join(dir, 'moved');
+/** The hook command: silent and successful where the script is absent (a settings file copied into a VM). */
+export const noticeCommand = (dir) => {
+    const script = join(noticeDir(dir), 'notice.sh').replace(/'/g, `'\\''`);
+    return `f='${script}'; [ -f "$f" ] && /bin/sh "$f"; exit 0`;
+};
+export const noticeLine = (m) => `This session continues in the cloud as ${m.key}; typing here diverges from it. Open it there: shard agents open ${m.key}`;
+/**
+ * The one-line divergence notice: a marker per moved session, and (Claude Code) a UserPromptSubmit hook in the user's
+ * settings that prints the marker's systemMessage when one exists. Claude Code reloads its settings, so a session
+ * that is still open shows it on its next prompt. Codex asks people to review new hooks, so Codex sessions get none.
+ */
+export function installDivergenceNotice(dir, env, m) {
+    const markers = noticeDir(dir);
+    mkdirSync(markers, { recursive: true, mode: 0o700 });
+    writeAtomic(join(markers, 'notice.sh'), NOTICE_SCRIPT, 0o700);
+    writeAtomic(join(markers, `${m.session_id}.json`), JSON.stringify({ systemMessage: noticeLine(m) }) + '\n', 0o600);
+    if (m.harness !== 'claude')
+        return;
+    const file = join(claudeConfigDir(env), 'settings.json');
+    let settings = {};
+    if (existsSync(file)) {
+        try {
+            settings = JSON.parse(readFileSync(file, 'utf8'));
+        }
+        catch {
+            return;
+        } // A settings file someone is editing by hand is theirs; the notice is optional.
+        if (!settings || typeof settings !== 'object' || Array.isArray(settings))
+            return;
+    }
+    const command = noticeCommand(dir);
+    const hooks = (settings.hooks && typeof settings.hooks === 'object' && !Array.isArray(settings.hooks) ? settings.hooks : {});
+    const groups = Array.isArray(hooks.UserPromptSubmit) ? hooks.UserPromptSubmit : [];
+    if (JSON.stringify(groups).includes(JSON.stringify(command).slice(1, -1)))
+        return;
+    hooks.UserPromptSubmit = [...groups, { hooks: [{ type: 'command', command, timeout: 5 }] }];
+    settings.hooks = hooks;
+    mkdirSync(dirname(file), { recursive: true });
+    writeAtomic(file, JSON.stringify(settings, null, 2) + '\n', 0o600);
+}
+function writeAtomic(file, text, mode) {
+    const tmp = `${file}.${process.pid}.tmp`;
+    writeFileSync(tmp, text, { mode });
+    chmodSync(tmp, mode);
+    renameSync(tmp, file);
+}

package/dist/onboarding.d.ts

@@ -48,15 +48,30 @@ export interface Connection {
     found?: boolean;
     /** T3 Code only: optional (never needed to continue), its app (for the icon) and how it connects. */
     optional?: boolean;
+    /** T3 Code over SSH, with --t3-connect: the T3 Connect sign-in just started (its page and code), as `t3_link` names it. */
+    t3_link?: T3SignInRow;
     app_path?: string;
     mode?: 'provider' | 'ssh';
 }
+/** T3 Connect's one-time sign-in, as the card shows it: a page and a code, or no session here to start it with. */
+export interface T3SignInRow {
+    status: 'needs_sign_in';
+    label: string;
+    sign_in?: {
+        verification_uri: string;
+        user_code: string;
+        expires_at?: string;
+    };
+    needs_login?: boolean;
+}
 /**
  * T3 Code, when it is installed: an ACP-capable build (0.0.46+, nightly) has Shardflux as a provider, which every
- * `shard` run writes into T3's settings, so it is connected with nothing to sign in; stable 0.0.45 connects a project
- * over SSH (`shard agents new --in t3`), and says which environment to add. Null when T3 Code is not installed.
+ * `shard` run writes into T3's settings, so it is connected with nothing to sign in. Stable 0.0.45 connects with T3
+ * Connect, once per person: after that one sign-in every project set up for T3 Code (`shard agents new --in t3`)
+ * appears in T3 Code and the T3 app by itself. `startSignIn` (`--t3-connect`) starts that sign-in. Null when T3 Code
+ * is not installed.
  */
-export declare function t3Connection(ctx: Ctx, signedIn: boolean, appDirs?: string[], platform?: NodeJS.Platform): Promise<Connection | null>;
+export declare function t3Connection(ctx: Ctx, signedIn: boolean, appDirs?: string[], platform?: NodeJS.Platform, startSignIn?: boolean): Promise<Connection | null>;
 /** Claude: the account login is ready and Claude itself accepts it right now. */
 export declare function claudeConnection(row: CredentialRow | undefined): Omit<Connection, 'id' | 'picked' | 'found'>;
 /** Codex: this Mac's Codex login is copied and the account's Codex remote device (one executor) is connected. */

package/dist/onboarding.js

@@ -64,10 +64,12 @@ export function parseApps(value) {
 }
 /**
  * T3 Code, when it is installed: an ACP-capable build (0.0.46+, nightly) has Shardflux as a provider, which every
- * `shard` run writes into T3's settings, so it is connected with nothing to sign in; stable 0.0.45 connects a project
- * over SSH (`shard agents new --in t3`), and says which environment to add. Null when T3 Code is not installed.
+ * `shard` run writes into T3's settings, so it is connected with nothing to sign in. Stable 0.0.45 connects with T3
+ * Connect, once per person: after that one sign-in every project set up for T3 Code (`shard agents new --in t3`)
+ * appears in T3 Code and the T3 app by itself. `startSignIn` (`--t3-connect`) starts that sign-in. Null when T3 Code
+ * is not installed.
  */
-export async function t3Connection(ctx, signedIn, appDirs = applicationDirs(ctx.io.env), platform = process.platform) {
+export async function t3Connection(ctx, signedIn, appDirs = applicationDirs(ctx.io.env), platform = process.platform, startSignIn = false) {
     // The same install every T3 command uses (macOS and Linux): a build with ACP providers first.
     const app = t3Install(ctx.io.env, platform, appDirs);
     if (!app)
@@ -85,57 +87,81 @@ export async function t3Connection(ctx, signedIn, appDirs = applicationDirs(ctx.
             return { ...base, mode: 'provider', state: 'action', fact: error instanceof Error ? error.message : 'T3 Code’s settings could not be updated.', action: { title: 'Check again' } };
         }
     }
-    // Stable T3: an SSH environment per project; the newest one this API set up is the one to add. They are recorded in
-    // agents.json (targets.json keeps T3 out of its manifest); a manifest entry from an older CLI still counts.
+    // Stable T3: one T3 Connect sign-in per person (the API's, per account), then each project appears by itself. `next`
+    // is for scripts: a project is set up for T3 Code with it.
+    const ssh = { ...base, mode: 'ssh', next: shard(['agents', 'new', '--in', 't3', '--path', '<project>']) };
+    const offer = { ...ssh, state: 'action', fact: 'Your projects appear in T3 Code and the T3 app once connected.',
+        action: { title: 'Connect T3 Code', command: shard(['setup', '--inspect', '--t3-connect', '--json']) } };
+    if (!signedIn)
+        return offer;
+    const cloud = ctx.cloud();
+    let status;
+    try {
+        status = await cloud.t3.status();
+    }
+    catch {
+        return { ...ssh, state: 'unknown', fact: 'T3 Connect could not be checked just now.', action: { title: 'Retry', retry: true } };
+    }
+    // Remembered for `agents targets`: with the sign-in, every project can start in T3 Code (t3Status).
+    try {
+        new AgentStateStore(ctx.store.dir).saveT3Connected(ctx.apiUrl, status.connected);
+    }
+    catch { /* the next check writes it */ }
+    if (!status.connected) {
+        if (!startSignIn)
+            return offer;
+        const signIn = await startT3SignIn(ctx);
+        if (signIn === 'connected')
+            return t3Connection(ctx, signedIn, appDirs, platform, false);
+        if (signIn.needs_login)
+            return { ...offer, fact: 'Sign in to Shardflux on this computer to connect T3 Code.', t3_link: signIn };
+        return { ...offer, fact: 'Confirm the code on the page that opened. This updates on its own.', t3_link: signIn,
+            action: { title: 'Connect T3 Code', url: signIn.sign_in.verification_uri } };
+    }
+    const connected = { ...ssh, state: 'verified', fact: 'Your projects appear in T3 Code and the T3 app.' };
+    // The newest project set up for T3 Code from this computer (agents.json; a targets.json entry from an older CLI still
+    // counts): where it is. One set up before T3 Connect, or whose link failed, is linked now: it is the person's choice.
     const recorded = new AgentStateStore(ctx.store.dir).t3Environments(ctx.apiUrl).at(-1);
     const manifest = await jsonFile(join(ctx.store.dir, 'targets.json'));
     const entries = Array.isArray(manifest?.entries) ? manifest.entries : [];
-    const legacy = entries.filter(e => e.api_url === ctx.apiUrl && Array.isArray(e.targets) && e.targets.includes('t3') && typeof e.host === 'string').at(-1);
-    const host = recorded?.host ?? legacy?.host;
-    const workspaceKey = recorded?.workspace ?? (typeof legacy?.workspace === 'string' ? legacy.workspace : undefined);
-    if (host) {
-        const desktop = `In T3 Code: Add environment → SSH → ${host}`;
-        const phone = await t3Phone(ctx, workspaceKey);
-        if (!phone)
-            return { ...base, mode: 'ssh', state: 'verified', fact: desktop };
-        return { ...base, mode: 'ssh', ...phone, fact: phone.state === 'verified' ? `${desktop}. On your phone: ${phone.fact}` : phone.fact };
-    }
-    // An SSH environment is per project (shardflux-<project>-main): it is set up once a project is picked.
-    return { ...base, mode: 'ssh', state: 'info', fact: 'Available after you pick a project.', next: shard(['agents', 'new', '--in', 't3', '--path', '<project>']) };
-}
-/**
- * The T3 app on the phone (T3 Connect, 0.17.0+): the workspace is linked with the person's one T3 Connect sign-in. The
- * sign-in is a page to open once; afterwards every project appears in the T3 app by itself. Undefined when the API has
- * no T3 Connect: the desktop route is the whole card then.
- */
-async function t3Phone(ctx, key) {
+    const legacy = entries.filter(e => e.api_url === ctx.apiUrl && Array.isArray(e.targets) && e.targets.includes('t3') && typeof e.workspace === 'string').at(-1);
+    const key = recorded?.workspace ?? legacy?.workspace;
     if (!key)
-        return undefined;
+        return connected;
     try {
         const ws = await resolveWorkspace(ctx, key);
-        const cloud = ctx.cloud();
-        const known = (await cloud.t3.status()).links.find(l => l.workspace_id === ws.id);
-        // A workspace connected to T3 before T3 Connect, or one whose link failed, is linked now: it is the person's choice.
-        const { link, signIn, needsLogin } = !known || known.status === 'error' || known.status === 'needs_sign_in'
-            ? await t3PhoneLink(ctx, ws.id) : { link: known, signIn: undefined, needsLogin: false };
+        const known = status.links.find(l => l.workspace_id === ws.id);
+        const link = !known || known.status === 'error' || known.status === 'needs_sign_in' ? (await t3PhoneLink(ctx, ws.id)).link : known;
+        // Linked to the person's T3 account: T3 Code and the T3 app list it once they are signed in to that account.
         if (link.status === 'linked')
-            return { state: 'verified', fact: `${link.label} in the T3 app.` };
-        if (signIn) {
-            return { state: 'action', fact: `To use it from the T3 app on your phone, confirm ${signIn.user_code} once.`,
-                action: { title: 'Connect phone', url: signIn.verification_uri } };
-        }
-        if (needsLogin)
-            return { state: 'info', fact: 'Sign in to Shardflux on this computer to use it from the T3 app.' };
-        return { state: 'pending', fact: `Adding ${link.label} to the T3 app on your phone…` };
+            return { ...connected, fact: `${link.label} is linked to your T3 account.` };
+        if (link.status === 'linking')
+            return { ...ssh, state: 'pending', fact: `Linking ${link.label} to your T3 account…` };
+        return connected;
     }
     catch (error) {
-        // No T3 Connect on this API, or nothing to ask it: the desktop route stands on its own.
-        if (!(error instanceof ShardfluxApiError) || describeError(error).code === 'not_found')
-            return undefined;
-        // Another member's T3 Connect sign-in links this project: it is in their T3 app, not something to fix here.
+        // Another member's T3 Connect sign-in links this project: it is in their T3 Code, not something to fix here.
         if (error.details?.reason === 't3_linked_by_other_member')
-            return { state: 'info', fact: 'In the T3 app of the member who linked it.' };
-        return { state: 'unknown', fact: 'The T3 app link could not be checked just now.', action: { title: 'Retry', retry: true } };
+            return { ...connected, fact: 'In the T3 Code of the member who linked it.' };
+        // The project's VM is gone or unreachable: the account is connected, and the next project appears by itself.
+        return connected;
+    }
+}
+/**
+ * Starts the person's T3 Connect sign-in (a pending one comes back again). It needs this computer's Shardflux session,
+ * not only an API key. `connected` when the account already has one (409 `t3_signed_in`).
+ */
+async function startT3SignIn(ctx) {
+    if (ctx.store.profile(ctx.apiUrl).session?.state !== 'active')
+        return { status: 'needs_sign_in', label: '', needs_login: true };
+    try {
+        const flow = await ctx.account().t3.signIn();
+        return { status: 'needs_sign_in', label: '', sign_in: { verification_uri: flow.verification_uri, user_code: flow.user_code, expires_at: flow.expires_at } };
+    }
+    catch (error) {
+        if (error instanceof ShardfluxApiError && describeError(error).code === 't3_signed_in')
+            return 'connected';
+        throw error;
     }
 }
 const shard = (words) => ['shard', ...words];
@@ -255,7 +281,7 @@ export async function onboardingReport(ctx, values) {
     const codex = { id: 'codex', picked: apps.includes('codex'), found: found.includes('codex'),
         ...(!connected ? signIn : (credentialError ?? codexError) !== undefined ? failure(credentialError ?? codexError)
             : codexConnection(localCodex, credentials.some(row => row.app === 'codex'), connector, health)) };
-    const t3 = await t3Connection(ctx, connected);
+    const t3 = await t3Connection(ctx, connected, undefined, undefined, values['t3-connect'] === true);
     const connections = [account, claude, codex, ...(t3 ? [t3] : [])];
     // Ready: signed in and at least one agent app connected; the other can be connected later (Settings, or this again).
     const ready = account.state === 'verified' && [claude, codex].some(c => c.state === 'verified');
@@ -268,7 +294,7 @@ export async function onboardingReport(ctx, values) {
             { id: 'account', title: 'Sign in to Shardflux', status: connected ? 'complete' : 'available', command: shard(['signup']) },
             { id: 'connect', title: 'Connect Claude, Codex or both', status: ready ? 'complete' : 'available' },
             { id: 'demo', title: 'Try it once: your agent’s own computer', status: done(state?.demo_finished) ? 'complete' : 'available',
-                action: 'Copy the task, press ⌥⇧Space, paste it, pick Daylight (sample) and start it. The agent installs what it needs, starts it and tests it in its own browser.' },
+                action: 'Copy the task and press ⌥⇧Space. Paste the task, then Start. The agent installs what it needs, starts it and tests it in its own browser.' },
             { id: 'own', title: 'Your own project', status: done(state?.own_key) ? 'complete' : 'available',
                 action: 'Press ⌥⇧Space, pick your project and describe what you want.' },
         ],

package/dist/project-sync-manifest.d.ts

@@ -1,6 +1,4 @@
 import type { FileManifest, FileManifestEntry } from '@shardflux/sdk';
-export declare const MAX_SYNC_FILE_BYTES: number;
-export declare const MAX_SYNC_ENTRIES = 20000;
 export type Manifest = Record<string, FileManifestEntry>;
 export type Common = Record<string, string>;
 export interface SyncChange {
@@ -13,9 +11,25 @@ export declare function excludedSyncPath(path: string): boolean;
 export declare function contentIdentity(entry?: FileManifestEntry): string;
 /** Deletions have an observation timestamp: a detached filesystem has no deletion clock. Ties favor the laptop. */
 export declare function diffManifests(local: Manifest, remote: Manifest, common: Common, observedAt?: number, blocked?: Set<string>): SyncChange[];
+/**
+ * Validates a manifest's wire shape. Any number of entries and any file size are accepted; an entry whose path this
+ * client cannot represent is moved to `manifest.skipped` (reason `unsupported_path`) instead of failing the pass.
+ */
 export declare function parseManifest(manifest: FileManifest): Manifest;
 export declare function projectGit(folder: string, args: string[], signal?: AbortSignal, input?: string): Promise<string>;
-/** Uses the actual Git implementation rather than an approximation of gitignore. */
+/**
+ * Streams Git's NUL-separated path output into `each`: no output buffer and no time bound, so a tree of any size is
+ * listed in full (the signal still cancels it). Exit codes in `ok` count as success (check-ignore exits 1 for none).
+ */
+export declare function projectGitPaths(folder: string, args: string[], each: (path: string) => void, options?: {
+    signal?: AbortSignal;
+    input?: string;
+    ok?: number[];
+}): Promise<void>;
+/**
+ * Uses the actual Git implementation rather than an approximation of gitignore. Any number of paths; a path this
+ * client cannot represent stays in the list and is reported as skipped by `localEntry`.
+ */
 export declare function selectedProjectPaths(folder: string, signal?: AbortSignal): Promise<string[]>;
 export declare function ignoredProjectPaths(folder: string, paths: string[], signal?: AbortSignal): Promise<string[]>;
 /** Refuse parent symlinks, including a tracked file beneath a submodule/link. */
@@ -24,4 +38,18 @@ export type LocalHashCache = Map<string, {
     metadata: string;
     entry: FileManifestEntry;
 }>;
+export type LocalEntry = FileManifestEntry | {
+    path: string;
+    reason: string;
+} | undefined;
+/**
+ * One project file's manifest entry: undefined when it does not exist (ENOENT), `{ path, reason }` when it is skipped
+ * (`unsupported_type`: a socket, device or FIFO; `unsupported_path`: a name the sync cannot carry, such as one with a
+ * backslash; `nested_repository`: a submodule or nested Git repository). Any size is hashed.
+ */
+export declare function localEntry(folder: string, path: string, signal?: AbortSignal, cache?: LocalHashCache): Promise<FileManifestEntry | {
+    path: string;
+    reason: string;
+} | undefined>;
+/** The cache holds one entry per project path: entries for paths that left the project are dropped after each pass. */
 export declare function localManifest(folder: string, signal?: AbortSignal, cache?: LocalHashCache, known?: string[]): Promise<FileManifest>;