@shardflux/cli 0.13.5 → 0.14.0

package/dist/command-center-actions.js

@@ -8,6 +8,9 @@ import { cellConnector, PtyOutputCursor } from "./agent-terminal.js";
 import { rememberGitAgent } from "./agent-git-commands.js";
 import { rememberLaunch } from "./agent-live.js";
 import { agentName as gitAgentName } from "./agent-git.js";
+import { randomUUID } from 'node:crypto';
+import { prepareAgentMachine } from "./agent-machine.js";
+import { OperationFailedError } from '@shardflux/sdk';
 /** L9 can register target-specific handlers after detecting the installed applications. */
 export async function availableTargets(ctx) {
     const { HANDLERS } = await import("./handlers.js");
@@ -19,7 +22,7 @@ export async function availableTargets(ctx) {
     if (code !== 0)
         throw new Error('open target detection failed');
     const result = JSON.parse(output);
-    return ['terminal', ...result.targets.filter(target => ['claude-desktop', 'codex-app', 'web'].includes(target) && HANDLERS[`agents open ${target}`])];
+    return ['terminal', ...result.targets.filter(target => ['claude-desktop', 'codex-app', 'web', 't3'].includes(target) && HANDLERS[`agents open ${target}`])];
 }
 export async function agentAction(ctx, action, values, args) {
     const { HANDLERS } = await import("./handlers.js");
@@ -42,19 +45,39 @@ export const CENTER_HANDLERS = {
         const source = await resolveWorkspace(ctx, ref);
         const key = `${source.labels.shard_project || source.key.split('/')[0]}/${name}`;
         const labels = { ...source.labels, shard_project: source.labels.shard_project || source.key.split('/')[0], agent: name,
-            agent_pty_name: source.labels.agent_pty_name || agentName(source.key, source.labels) };
+            agent_pty_name: source.labels.agent_pty_name || agentName(source.key, source.labels), t3_environment_id: randomUUID() };
         const caps = workspaceCaps(values);
         const started = Date.now();
         const result = await ctx.cloud().workspaces.fork(source.id, { key, labels, ...(caps ? { caps } : {}) }, {
             agentLabel: ctx.agentLabel, wait: values.wait === false ? false : { timeoutMs: waitTimeout(values), signal: ctx.signal },
+        }).catch(async (error) => {
+            // Older cells can copy an external agent workspace and then fail their
+            // PTY-only repair. Keep the failure, but never leave the copy's T3 identity shared.
+            const forkError = error instanceof OperationFailedError ? error.operation.error : undefined;
+            const details = forkError?.details;
+            if (error instanceof OperationFailedError && error.operation.kind === 'fork' && error.errorCode === 'agent_fork_failed' && details && typeof details === 'object' && !Array.isArray(details) && 'workspace_state' in details && details.workspace_state === 'running' && error.operation.workspace_id) {
+                const child = await ctx.cloud().workspaces.get(error.operation.workspace_id);
+                if (child.key !== key || child.data.forked_from_workspace_id !== source.id || child.labels?.t3_environment_id !== labels.t3_environment_id)
+                    throw new Error(`Fork ${key} identity could not be reconciled: copied workspace does not match this fork`, { cause: error });
+                await prepareAgentMachine(ctx, child);
+                await ctx.cloud().workspaces.setRetention(child.id, { delete_after_idle_days: 7 });
+                if (ctx.json && forkError)
+                    forkError.details = { ...details, workspace_identity_reconciled: true };
+                else
+                    ctx.io.stderr.write(`Copied ${key} has its own T3 identity; fork operation ${error.operationId} still failed.\n`);
+            }
+            throw error;
         });
         const agent = result.operation.result?.agent;
         const receipt = agent && typeof agent === 'object' ? agent : undefined;
-        if (result.operation.state === 'succeeded' && (!receipt ||
+        const workspaceOnly = result.operation.result?.agent_fork_mode === 'workspace' && !agent;
+        if (result.operation.state === 'succeeded' && !workspaceOnly && (!receipt ||
             ['id', 'workspace_key', 'session_id'].some(field => typeof receipt[field] !== 'string' || !receipt[field]) ||
             receipt.workspace_key !== key || !['working', 'waiting'].includes(String(receipt.state)))) {
             throw new Error(`Fork ${key} has no independent agent session receipt`);
         }
+        if (result.operation.state === 'succeeded')
+            await prepareAgentMachine(ctx, result.workspace);
         await ctx.cloud().workspaces.setRetention(result.workspace.id, { delete_after_idle_days: 7 });
         if (agent)
             rememberLaunch(ctx, result.workspace.id, started);

package/dist/command-center.js

@@ -2,6 +2,8 @@ import { json } from "./format.js";
 import { UsageError } from "./errors.js";
 import { projectIdentity } from "./project-identity.js";
 import { AgentStateStore } from "./agent-state.js";
+import { installedTargets } from "./agent-targets.js";
+import { randomUUID } from 'node:crypto';
 import { agentAction, availableTargets } from "./command-center-actions.js";
 import { centerRows, loadCenter } from "./command-center-model.js";
 import { AnsiRenderer, renderCenter } from "./command-center-renderer.js";
@@ -259,11 +261,16 @@ export async function showCenter(ctx, scope, options = {}) {
             menu('Start here', [app, app === 'claude' ? 'codex' : 'claude'].map(app => ({ label: `Start ${app === 'claude' ? 'Claude' : 'Codex'} here`, run: () => dispatch('new', { path: scope.folder, app }, [], true) })));
             return;
         }
-        if (key === 'enter')
-            await dispatch('open', { app, project, in: 'terminal' }, [row.key], true);
+        if (key === 'enter') {
+            const target = new AgentStateStore(ctx.store.dir).target(project, ['terminal', ...installedTargets(ctx.io.env).targets]);
+            await dispatch('open', { app, project, in: target }, [row.key], true);
+        }
         else if (key === 'o') {
             const targets = await availableTargets(ctx);
-            menu('Open in…', targets.map(target => ({ label: target, run: () => dispatch('open', { app, project, in: target }, [row.key], true) })));
+            menu('Open in…', targets.map(target => ({ label: target, run: async () => {
+                    new AgentStateStore(ctx.store.dir).saveTarget(project, target);
+                    await dispatch('open', { app, project, in: target }, [row.key], true);
+                } })));
         }
         else if (key === 'n') {
             menu('New session', ['claude', 'codex'].map(app => ({ label: `${app === 'claude' ? 'Claude' : 'Codex'} (reattach if running)`, run: () => dispatch('new', { app, project }, [row.key], true) })));
@@ -310,8 +317,12 @@ export async function showCenter(ctx, scope, options = {}) {
 export const commandCenter = async (ctx, values, [path, app]) => {
     // `shard <path> claude|codex` names the agent: start (or reattach) it without the picker; --json starts it detached.
     if (path && (app === 'claude' || app === 'codex'))
-        return agentAction(ctx, 'new', { ...values, path, app }, []);
+        return agentAction(ctx, 'new', { ...values, path, app, ...(values.new === true ? { name: `agent-${randomUUID().slice(0, 8)}` } : {}) }, []);
     const scope = path ? projectIdentity(path) : undefined;
+    if (scope && values.new === true) {
+        const target = new AgentStateStore(ctx.store.dir).target(scope.remote ?? scope.folder, ['terminal', ...installedTargets(ctx.io.env).targets]);
+        return agentAction(ctx, 'new', { ...values, path: scope.folder, name: `agent-${randomUUID().slice(0, 8)}`, in: target === 'web' ? 'terminal' : target }, []);
+    }
     if (ctx.json) {
         const data = await loadCenter(ctx);
         const rows = centerRows(data, scope);
@@ -319,5 +330,10 @@ export const commandCenter = async (ctx, values, [path, app]) => {
         ctx.io.stdout.write(json({ projects, workspaces: data.workspaces.filter(w => rows.some(r => r.workspace?.id === w.id)), agents: data.agents.filter(a => rows.some(r => r.agent?.id === a.id)) }));
         return 0;
     }
+    if (scope) {
+        const target = new AgentStateStore(ctx.store.dir).target(scope.remote ?? scope.folder, ['terminal', ...installedTargets(ctx.io.env).targets]);
+        if (target === 't3')
+            return agentAction(ctx, 'new', { ...values, path: scope.folder, in: target }, []);
+    }
     return showCenter(ctx, scope, { approvals: values.approvals === true, ...(app === 'claude' || app === 'codex' ? { app } : {}) });
 };

package/dist/conversation-commands.d.ts

@@ -0,0 +1,3 @@
+import type { Ctx, Handler } from './commands.js';
+export declare function conversationClient(ctx: Ctx): import("@shardflux/sdk").Shardflux | import("@shardflux/sdk").ShardfluxAccount;
+export declare const CONVERSATION_HANDLERS: Record<string, Handler>;

package/dist/conversation-commands.js

@@ -0,0 +1,36 @@
+import { out, str } from "./commands.js";
+import { UsageError } from "./errors.js";
+export function conversationClient(ctx) {
+    const key = Boolean(ctx.io.env.SHARDFLUX_API_KEY?.trim()) || ctx.store.profile(ctx.apiUrl).api_key !== undefined;
+    const session = Boolean(ctx.io.env.SHARDFLUX_SESSION_TOKEN?.trim()) || ctx.store.profile(ctx.apiUrl).session !== undefined;
+    return key || !session ? ctx.cloud() : ctx.account();
+}
+export const CONVERSATION_HANDLERS = {
+    async 'conversations resume'(ctx, _values, [id]) { const r = await conversationClient(ctx).conversations.resume(id, { signal: ctx.signal }); out(ctx, `${r.conversation.title}: resumed.\n`, r); return 0; },
+    async 'conversations reader'(ctx, _values, [id]) { const r = await conversationClient(ctx).conversations.spaceReader(id, { signal: ctx.signal }); out(ctx, `${r.workspace.workspace_key}\n`, r); return 0; },
+    async 'conversations list'(ctx, values) {
+        const state = str(values.state);
+        const page = await conversationClient(ctx).conversations.list({ projectId: str(values.project), state, parentId: str(values.parent), cursor: str(values.cursor), limit: values.limit ? Number(values.limit) : undefined });
+        out(ctx, page.data.map(c => `${c.id}\t${c.title}\t${c.state}\t${c.branch}`).join('\n') + '\n', page);
+        return 0;
+    },
+    async 'conversations get'(ctx, _values, [id]) { const c = await conversationClient(ctx).conversations.get(id); out(ctx, `${c.title}\n${c.state}\n${c.branch}\n`, c); return 0; },
+    async 'conversations send'(ctx, _values, [id, text]) { const r = await conversationClient(ctx).conversations.send(id, text, { signal: ctx.signal }); out(ctx, `Message sent (${r.seq}).\n`, r); return 0; },
+    async 'conversations wait'(ctx, values, [id]) {
+        const seconds = values.timeout === undefined ? 900 : Number(values.timeout);
+        if (!Number.isInteger(seconds) || seconds < 0 || seconds > 900)
+            throw new UsageError('--timeout must be 0..900 seconds.');
+        const until = str(values.until)?.split(',');
+        const r = await conversationClient(ctx).conversations.wait(id, { until, timeoutSeconds: seconds, signal: ctx.signal });
+        out(ctx, 'timeout' in r ? 'Still working.\n' : `${r.conversation.title}: ${r.event.kind}\n${r.event.question ?? r.event.result?.summary ?? ''}\n`, r);
+        return 0;
+    },
+    async 'conversations land'(ctx, values, [id, action]) {
+        if (!['merge', 'pr', 'keep', 'discard'].includes(action))
+            throw new UsageError('Choose merge, pr, keep or discard.');
+        const r = await conversationClient(ctx).conversations.land(id, action, { into: str(values.into), signal: ctx.signal });
+        out(ctx, `${r.title}: ${r.landed.how}\n`, r);
+        return 0;
+    },
+    async 'conversations move'(ctx, _values, [id, to]) { const r = await conversationClient(ctx).conversations.move(id, to, { signal: ctx.signal }); out(ctx, `Move scheduled for the end of the turn.\n`, r); return 0; },
+};

package/dist/conversation-local-resume.d.ts

@@ -0,0 +1,8 @@
+import type { Ctx } from './commands.js';
+import type { Conversation } from './conversations.js';
+/** Native local continuation uses a worktree. It never checks out the saved branch in the user's main tree. */
+export declare function prepareLocalResume(ctx: Pick<Ctx, 'io' | 'store' | 'apiUrl' | 'signal'>, c: Conversation, folder: string): Promise<{
+    folder: string;
+    argv: string[];
+}>;
+export declare function localResumeTerminal(ctx: Ctx, c: Conversation, folder: string): Promise<number>;

package/dist/conversation-local-resume.js

@@ -0,0 +1,56 @@
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { conversationName } from "./conversations.js";
+import { gitRunner } from "./agent-git.js";
+import { transcriptDestination, rewriteTranscript } from "./conversation-stash.js";
+import { writePrivateFile } from "./credentials.js";
+import { UsageError } from "./errors.js";
+import { checkConversationWorktree, rememberConversationWorktree } from "./conversation-worktree.js";
+import { withTargetLock } from "./target-lock.js";
+/** Native local continuation uses a worktree. It never checks out the saved branch in the user's main tree. */
+export async function prepareLocalResume(ctx, c, folder) {
+    return withTargetLock(join(ctx.store.dir, 'conversation-worktree-lock'), async () => {
+        if (!c.harness_session_id || !['done', 'archived'].includes(c.state))
+            throw new UsageError('This conversation has no ended native session.');
+        const run = gitRunner(folder, { ...process.env, ...ctx.io.env }, ctx.signal), name = conversationName(c);
+        const root = join(folder, '.shard', 'worktrees', name);
+        // This ref was fetched before the handoff receipt. Missing work is an error, never an empty branch.
+        await run(['rev-parse', '--verify', `refs/remotes/shardflux/${name}^{commit}`]);
+        if (!existsSync(root)) {
+            mkdirSync(dirname(root), { recursive: true });
+            const exists = await run(['show-ref', '--verify', `refs/heads/${c.branch}`]).then(() => true, () => false);
+            await run(['-c', 'core.hooksPath=/dev/null', 'worktree', 'add', ...(exists ? [] : ['-b', c.branch]), root, exists ? c.branch : `refs/remotes/shardflux/${name}`]);
+            rememberConversationWorktree(ctx, c, folder, root);
+        }
+        else
+            checkConversationWorktree(ctx, c, folder, root);
+        const work = gitRunner(root, { ...process.env, ...ctx.io.env }, ctx.signal);
+        if (await work(['symbolic-ref', '--short', 'HEAD']) !== c.branch)
+            throw new UsageError('The local worktree belongs to another branch.');
+        if (c.harness === 'claude') {
+            const filename = `${c.harness_session_id}.jsonl`;
+            const source = transcriptDestination(c, folder, filename, ctx.io.env), dest = transcriptDestination(c, root, filename, ctx.io.env);
+            if (!existsSync(source))
+                throw new UsageError('Native transcript handoff is missing.');
+            if (!existsSync(dest))
+                writePrivateFile(dirname(dest), dest, Buffer.from(rewriteTranscript(readFileSync(source), folder, root)).toString('utf8'));
+            return { folder: root, argv: ['claude', '--resume', c.harness_session_id] };
+        }
+        return { folder: root, argv: ['codex', 'resume', c.harness_session_id, '--all', '-C', root] };
+    }, ctx.signal);
+}
+export async function localResumeTerminal(ctx, c, folder) {
+    if (!ctx.io.stdin.isTTY || ctx.json)
+        throw new UsageError('Native local resume requires a terminal.');
+    const launch = await prepareLocalResume(ctx, c, folder);
+    const child = spawn(launch.argv[0], launch.argv.slice(1), { cwd: launch.folder, env: { ...process.env, ...ctx.io.env }, stdio: 'inherit' });
+    return new Promise((resolve, reject) => {
+        const abort = () => child.kill('SIGTERM');
+        ctx.signal.addEventListener('abort', abort, { once: true });
+        child.once('error', e => { ctx.signal.removeEventListener('abort', abort); reject(e); });
+        child.once('exit', code => { ctx.signal.removeEventListener('abort', abort); resolve(code ?? 130); });
+        if (ctx.signal.aborted)
+            abort();
+    });
+}

package/dist/conversation-local.d.ts

@@ -0,0 +1,7 @@
+import type { Ctx, Handler } from './commands.js';
+import type { Conversation } from './conversations.js';
+export declare function tryConversationLocally(ctx: Ctx, c: Conversation, folder: string): Promise<{
+    folder: string;
+    stop(): Promise<void>;
+}>;
+export declare const CONVERSATION_HANDLERS: Record<string, Handler>;

package/dist/conversation-local.js

@@ -0,0 +1,61 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { getConversation, resolveConversation, conversationWorkspace, localConversations } from "./conversations.js";
+import { ensureConversationWorktree, devicePort } from "./device-bridge.js";
+import { startProjectSync } from "./project-sync.js";
+import { projectIdentity } from "./project-identity.js";
+import { UsageError } from "./errors.js";
+import { out } from "./commands.js";
+import { join } from 'node:path';
+import { writePrivateFile } from "./credentials.js";
+export async function tryConversationLocally(ctx, c, folder) {
+    const ws = await conversationWorkspace(ctx, c), worktree = await ensureConversationWorktree(ctx, c, folder, ws);
+    const project = { ...projectIdentity(folder), folder: worktree };
+    const sync = await startProjectSync(ctx, ws, project, { root: c.worktree_path, agent: c.key.split('/').at(-1), seed: false });
+    const ports = [];
+    try {
+        for (const port of c.ports ?? [])
+            ports.push(await devicePort(ws, ws.cell(), 'port_forward', { remote_port: port, local_port: port }, ctx.signal));
+        return { folder: worktree, async stop() { try {
+                await sync.stop();
+            }
+            finally {
+                await Promise.all(ports.map(p => p.stop()));
+                ws.cell().close();
+            } } };
+    }
+    catch (e) {
+        await sync.stop();
+        await Promise.all(ports.map(p => p.stop()));
+        throw e;
+    }
+}
+export const CONVERSATION_HANDLERS = {
+    async 'conversations try'(ctx, values, [ref]) {
+        if (!ref)
+            throw new UsageError('Choose a conversation.');
+        const c = await resolveConversation(ctx, ref), record = localConversations(ctx)[c.id];
+        if (values.stop === true) {
+            const dir = join(ctx.store.dir, 'device-stops');
+            writePrivateFile(dir, join(dir, `${c.id}.json`), JSON.stringify({ api_url: ctx.apiUrl }) + '\n');
+            out(ctx, `Stopping local sync for ${c.key}.\n`, { conversation_id: c.id, stopping: true });
+            return 0;
+        }
+        const folder = typeof values.path === 'string' ? values.path : record?.folder;
+        if (!folder)
+            throw new UsageError('Use --path to name the local project checkout.');
+        const handle = await tryConversationLocally(ctx, c, folder);
+        out(ctx, `Trying ${c.key} in ${handle.folder}. Press Ctrl-C to stop sync.\n`, { conversation: c, folder: handle.folder });
+        try {
+            while (!ctx.signal.aborted) {
+                const next = await getConversation(ctx, c.id);
+                if (next.state === 'done' || next.state === 'archived' || next.workspace_id !== c.workspace_id)
+                    break;
+                await delay(1000, undefined, { signal: ctx.signal }).catch(() => undefined);
+            }
+        }
+        finally {
+            await handle.stop();
+        }
+        return 0;
+    },
+};

package/dist/conversation-router.d.ts

@@ -0,0 +1,12 @@
+import type { Workspace } from '@shardflux/sdk';
+import type { Ctx } from './commands.js';
+export declare const ROUTER_CONFIG = "/home/user/.config/shardflux/conversation-router.json";
+export declare function routerConfiguration(ctx: Pick<Ctx, 'apiUrl'>, ws: Workspace, commit: string, cwd?: string): {
+    api_url: string;
+    project_id: string;
+    repo_remote: string;
+    cwd: string;
+    base_commit: string;
+};
+/** CVE reads this config on every request; old guests keep their existing SSH path. */
+export declare function prepareDesktopRouter(ctx: Ctx, source: Workspace): Promise<Workspace>;

package/dist/conversation-router.js

@@ -0,0 +1,89 @@
+import { randomUUID } from 'node:crypto';
+import { ShardfluxApiError } from '@shardflux/sdk';
+import { workspaceRepositoryPath, projectWorkspacePath, HISTORY_BUNDLE_LIMIT } from "./agent-repository.js";
+import { writeSyncBlob } from "./project-sync-transfer.js";
+import { UsageError } from "./errors.js";
+import { conversationClient } from "./conversation-commands.js";
+export const ROUTER_CONFIG = '/home/user/.config/shardflux/conversation-router.json';
+export function routerConfiguration(ctx, ws, commit, cwd = workspaceRepositoryPath(ws)) {
+    const remote = ws.labels.repo_remote || ws.labels.shard_repo_remote;
+    if (!ws.data.project_id || !remote || !/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/.test(commit) || !cwd.startsWith('/home/user/'))
+        throw new UsageError('Project routing requires a project, repository and its actual commit.');
+    return { api_url: ctx.apiUrl, project_id: ws.data.project_id, repo_remote: remote, cwd, base_commit: commit };
+}
+/** CVE reads this config on every request; old guests keep their existing SSH path. */
+export async function prepareDesktopRouter(ctx, source) {
+    const cloud = conversationClient(ctx);
+    try {
+        await cloud.conversations.list({ projectId: source.data.project_id, limit: 1 });
+    }
+    catch (error) {
+        if (error instanceof ShardfluxApiError && (error.status === 404 || error.status === 503 && error.details?.reason === 'conversations_unavailable'))
+            return source;
+        throw error;
+    }
+    const cell = source.cell();
+    const probe = await cell.exec.run(['sf-agent', 'app-router-info'], { timeoutMs: 10_000, maxOutputBytes: 8192, signal: ctx.signal });
+    if (probe.exitCode !== 0)
+        return source;
+    let info;
+    try {
+        info = JSON.parse(probe.stdout);
+    }
+    catch {
+        return source;
+    }
+    if (info.version !== 1)
+        return source;
+    const mounted = await cell.exec.run(['test', '-d', '/shardflux/project/git/hub.git'], { timeoutMs: 10_000, signal: ctx.signal });
+    if (mounted.exitCode !== 0)
+        return source;
+    const head = await cell.exec.run(['git', '-C', workspaceRepositoryPath(source), 'rev-parse', 'HEAD'], { timeoutMs: 10_000, signal: ctx.signal });
+    if (head.exitCode !== 0)
+        throw new UsageError('The project repository has no commit to route from.');
+    const commit = head.stdout.trim(), config = routerConfiguration(ctx, source, commit);
+    const project = source.key.split('/')[0], key = `${project}/router`;
+    let router = await cloud.workspaces.findByKey(key, { includeDeleted: false, signal: ctx.signal });
+    if (router && (router.key !== key || router.data.project_id !== config.project_id || router.labels.shard_router !== 'project' || router.labels.repo_remote !== config.repo_remote))
+        throw new UsageError('The project router key belongs to another workspace.');
+    const created = !router;
+    const labels = { ...source.labels, shard_project: project, shard_router: 'project', agent: 'router', shard_agent: 'router', repo_remote: config.repo_remote, repo_path: projectWorkspacePath({ slug: project }) };
+    delete labels.shard_conversation;
+    delete labels.shard_branch;
+    if (!router)
+        router = await cloud.workspaces.open({ key, like: source.id, labels, wait: { timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal } });
+    if (!router.ready)
+        await router.wake({ timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal });
+    const destination = router.cell(), root = workspaceRepositoryPath(router);
+    const archive = `/tmp/shard-router-${randomUUID()}.bundle`;
+    try {
+        if (created) {
+            const packed = await cell.exec.run(['git', '-C', workspaceRepositoryPath(source), '-c', 'core.hooksPath=/dev/null', 'bundle', 'create', archive, 'HEAD'], { timeoutMs: 120_000, signal: ctx.signal });
+            if (packed.exitCode !== 0)
+                throw new Error(`Project router seed failed: ${packed.stderr.trim()}`);
+            const info = await cell.files.stat(archive);
+            if (info.size > HISTORY_BUNDLE_LIMIT)
+                throw new UsageError('Project router history exceeds the 256 MiB transfer bound.');
+            const bytes = await cell.files.read(archive, { length: info.size + 1 });
+            if (bytes.length !== info.size)
+                throw new Error('Project router history changed during copying.');
+            await writeSyncBlob(destination, archive, bytes);
+            await destination.files.mkdir(root, { parents: true });
+            const imported = await destination.exec.run(['sh', '-c', 'set -eu; git -C "$1" init -q; git -C "$1" -c core.hooksPath=/dev/null fetch -q "$2" HEAD:refs/heads/shardflux-router; git -C "$1" -c core.hooksPath=/dev/null checkout -q shardflux-router', 'sh', root, archive], { timeoutMs: 120_000, signal: ctx.signal });
+            if (imported.exitCode !== 0)
+                throw new Error(`Project router repository could not be prepared: ${imported.stderr.trim()}`);
+        }
+        await destination.files.mkdir('/home/user/.config/shardflux', { parents: true, mode: '0700' });
+        await destination.files.write(ROUTER_CONFIG, JSON.stringify({ ...config, cwd: root }) + '\n', { mode: '0600' });
+        return router;
+    }
+    catch (e) {
+        if (created)
+            await cloud.workspaces.delete(router.id).catch(() => undefined);
+        throw e;
+    }
+    finally {
+        await cell.files.remove(archive).catch(() => undefined);
+        await destination.files.remove(archive).catch(() => undefined);
+    }
+}

package/dist/conversation-stash.d.ts

@@ -0,0 +1,11 @@
+import type { Workspace } from '@shardflux/sdk';
+import type { Ctx } from './commands.js';
+import type { Conversation, LocalConversation } from './conversations.js';
+export declare function rewriteTranscript(bytes: Uint8Array, remoteCwd: string, localCwd: string): Uint8Array;
+export declare function transcriptDestination(c: Conversation, folder: string, filename: string, env: Record<string, string | undefined>): string;
+/** Keep growing copies away from native session discovery until the control plane ends the conversation. */
+export declare function mirrorConversation(ctx: Ctx, record: LocalConversation, source: Workspace): Promise<void>;
+export declare function handoffConversation(ctx: Pick<Ctx, 'io' | 'store' | 'apiUrl' | 'signal'>, c: Conversation, folder: string, dir: string, source?: Pick<Workspace, 'key'> | {
+    hub: string;
+}): Promise<void>;
+export declare function mirrorProjectConversations(ctx: Ctx, mirrored?: Map<string, string>): Promise<void>;

package/dist/conversation-stash.js

@@ -0,0 +1,158 @@
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { conversationName, listConversations, localConversations, rememberConversation } from "./conversations.js";
+import { gitRunner } from "./agent-git.js";
+import { shardRemote } from "./git-remote.js";
+import { writePrivateFile } from "./credentials.js";
+import { conversationClient } from "./conversation-commands.js";
+const MAX = 256 << 20;
+export function rewriteTranscript(bytes, remoteCwd, localCwd) {
+    const text = new TextDecoder('utf8', { fatal: true }).decode(bytes);
+    const rewrite = (value) => {
+        if (Array.isArray(value))
+            return value.map(rewrite);
+        if (!value || typeof value !== 'object')
+            return value;
+        return Object.fromEntries(Object.entries(value).map(([key, leaf]) => {
+            if (typeof leaf === 'string' && ['cwd', 'workdir', 'working_directory'].includes(key) && (leaf === remoteCwd || leaf.startsWith(remoteCwd + '/')))
+                return [key, localCwd + leaf.slice(remoteCwd.length)];
+            return [key, rewrite(leaf)];
+        }));
+    };
+    if (!text.endsWith('\n'))
+        throw new Error('Transcript has an incomplete final record; preserved in stash.');
+    return Buffer.from(text.split('\n').filter(Boolean).map(line => JSON.stringify(rewrite(JSON.parse(line)))).join('\n') + '\n');
+}
+export function transcriptDestination(c, folder, filename, env) {
+    if (!/^[a-zA-Z0-9_.-]+\.jsonl$/.test(filename))
+        throw new Error('Transcript filename is not a native JSONL file.');
+    const home = env.HOME || homedir();
+    if (c.harness === 'claude')
+        return join(env.CLAUDE_CONFIG_DIR || join(home, '.claude'), 'projects', resolve(folder).replace(/[^a-zA-Z0-9]/g, '-'), filename);
+    const match = /^rollout-(\d{4})-(\d{2})-(\d{2})T/.exec(filename);
+    if (!match)
+        throw new Error('Codex transcript has no native rollout date.');
+    return join(env.CODEX_HOME || join(home, '.codex'), 'sessions', match[1], match[2], match[3], filename);
+}
+function privateDirectory(path) {
+    let at = path;
+    while (!existsSync(at)) {
+        const parent = dirname(at);
+        if (parent === at)
+            break;
+        at = parent;
+    }
+    if (existsSync(at) && lstatSync(at).isSymbolicLink())
+        throw new Error('Transcript directory must not be a symlink.');
+    mkdirSync(path, { recursive: true, mode: 0o700 });
+    if (lstatSync(path).isSymbolicLink())
+        throw new Error('Transcript directory must not be a symlink.');
+}
+/** Keep growing copies away from native session discovery until the control plane ends the conversation. */
+export async function mirrorConversation(ctx, record, source) {
+    const c = record.conversation;
+    const dir = join(ctx.store.dir, 'conversations', c.project_id, c.id), root = `/shardflux/project/transcripts/${c.id}`;
+    privateDirectory(dir);
+    const cell = source.cell({ wake: null });
+    try {
+        const manifest = await cell.files.manifest(root, { maxFileBytes: MAX, signal: ctx.signal });
+        if (manifest.skipped.length)
+            throw new Error('Project transcript copy includes files outside the mirror bound.');
+        let count = 0;
+        for (const entry of manifest.entries) {
+            if (entry.symlink || entry.path.includes('/') || !/^[a-zA-Z0-9_.-]+\.(jsonl|json)$/.test(entry.path))
+                throw new Error('Project transcript copy has an unsafe entry.');
+            const file = join(dir, entry.path), expected = existsSync(file) ? createHash('sha256').update(readFileSync(file)).digest('hex') : '';
+            if (expected !== entry.sha256) {
+                const bytes = await cell.files.read(`${root}/${entry.path}`, { length: Math.min(MAX + 1, entry.size + 1) });
+                if (bytes.length !== entry.size || createHash('sha256').update(bytes).digest('hex') !== entry.sha256)
+                    throw new Error('Transcript changed during copying; retaining the previous stash.');
+                writePrivateFile(dir, file, new TextDecoder('utf8', { fatal: true }).decode(bytes));
+            }
+            if (entry.path.endsWith('.jsonl'))
+                count++;
+        }
+        if (count === 0)
+            throw new Error('Project space has no transcript bytes to mirror.');
+        if ((c.state === 'done' || c.state === 'archived') && !record.handed_off) {
+            const binding = await conversationClient(ctx).workspaces.get(c.workspace_id);
+            if (!binding.data.deleted_at)
+                return;
+            const meta = JSON.parse(readFileSync(join(dir, 'meta.json'), 'utf8'));
+            if (!c.harness_session_id || meta.harness !== c.harness || meta.harness_session_id !== c.harness_session_id || !/^[a-zA-Z0-9_.-]+\.jsonl$/.test(meta.file))
+                throw new Error('Transcript handoff metadata does not match the ended conversation.');
+            const bytes = readFileSync(join(dir, meta.file));
+            if (bytes.length !== meta.bytes || createHash('sha256').update(bytes).digest('hex') !== meta.sha256)
+                throw new Error('Transcript handoff checkpoint differs from its durable metadata.');
+            await handoffConversation(ctx, { ...c, worktree_path: meta.cwd }, record.folder, dir, source);
+        }
+    }
+    finally {
+        cell.close();
+    }
+}
+export async function handoffConversation(ctx, c, folder, dir, source) {
+    if (c.state !== 'done' && c.state !== 'archived')
+        throw new Error('Only an ended conversation can enter native history.');
+    const files = readdirSync(dir).filter(f => f.endsWith('.jsonl'));
+    if (!files.length)
+        throw new Error('Conversation has no transcript to hand off.');
+    const writes = files.map(name => ({ dest: transcriptDestination(c, folder, name, ctx.io.env), bytes: rewriteTranscript(readFileSync(join(dir, name)), c.worktree_path, folder) }));
+    // Check every destination before the first write. Preserve local native history on any collision.
+    for (const { dest, bytes } of writes) {
+        if (existsSync(dest) && (lstatSync(dest).isSymbolicLink() || !readFileSync(dest).equals(Buffer.from(bytes))))
+            throw new Error(`Native transcript already exists with different bytes: ${dest}`);
+    }
+    if (!source)
+        throw new Error('Project hub is required before transcript handoff.');
+    const name = conversationName(c);
+    const run = gitRunner(folder, { ...process.env, ...ctx.io.env, SHARDFLUX_CONFIG_DIR: ctx.store.dir, SHARDFLUX_API_URL: ctx.apiUrl }, ctx.signal);
+    const hub = 'hub' in source ? source.hub : shardRemote(source.key, '/shardflux/project/git/hub.git');
+    await run(['-c', 'core.hooksPath=/dev/null', 'fetch', '--no-tags', hub, `+${c.state === 'archived' ? `refs/shard/archive/${name}` : `refs/heads/${c.branch}`}:refs/remotes/shardflux/${name}`]);
+    for (const { dest, bytes } of writes) {
+        privateDirectory(dirname(dest));
+        if (!existsSync(dest))
+            writePrivateFile(dirname(dest), dest, new TextDecoder('utf8', { fatal: true }).decode(bytes));
+    }
+    rememberConversation(ctx, c, folder, true);
+    writePrivateFile(dir, join(dir, 'handoff.json'), JSON.stringify({ conversation_id: c.id, branch: c.branch, destinations: writes.map(w => w.dest), at: new Date().toISOString() }) + '\n');
+}
+export async function mirrorProjectConversations(ctx, mirrored = new Map()) {
+    const records = localConversations(ctx);
+    if (!Object.keys(records).length)
+        return;
+    const all = await listConversations(ctx);
+    for (const record of Object.values(records)) {
+        const c = all.find(c => c.id === record.conversation.id);
+        if (!c || record.handed_off || !c.harness_session_id)
+            continue;
+        const revision = JSON.stringify([c.workspace_id, c.harness_session_id, c.state, c.durable, c.last_activity_at, c.summary]);
+        if (mirrored.get(c.id) === revision)
+            continue;
+        rememberConversation(ctx, c, record.folder);
+        let source;
+        for (const candidate of [c, ...all.filter(other => other.project_id === c.project_id && other.id !== c.id)]) {
+            try {
+                const ws = await conversationClient(ctx).workspaces.get(candidate.workspace_id);
+                if (!ws.data.deleted_at && ws.ready) {
+                    source = ws;
+                    break;
+                }
+            }
+            catch { /* Another binding may be available. */ }
+        }
+        if (!source) {
+            const client = conversationClient(ctx);
+            const reader = await client.conversations.spaceReader(c.project_id, { signal: ctx.signal });
+            source = await client.workspaces.get(reader.workspace.id);
+            if (!source.ready)
+                await source.wake({ timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal });
+        }
+        await mirrorConversation(ctx, { ...record, conversation: c }, source);
+        // An ended record may precede its VM tombstone; retry until the handoff receipt is written.
+        if (c.state !== 'done' && c.state !== 'archived')
+            mirrored.set(c.id, revision);
+    }
+}

package/dist/conversation-terminal.d.ts

@@ -0,0 +1,3 @@
+import type { Handler } from './commands.js';
+/** Select a durable conversation, then use the harness's native terminal for all interaction. */
+export declare const launchConversationProject: Handler;