@shardflux/cli 0.13.6 → 0.14.0

package/dist/device-bridge.js

@@ -0,0 +1,398 @@
+import { createHash } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync } from 'node:fs';
+import { readFile, writeFile, mkdir, realpath, stat } from 'node:fs/promises';
+import { createConnection, createServer } from 'node:net';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { WorkspaceTunnels } from '@shardflux/sdk';
+import { writePrivateFile } from "./credentials.js";
+import { conversationName, conversationWorkspace, getConversation, localConversations } from "./conversations.js";
+import { gitRunner } from "./agent-git.js";
+import { shardRemote } from "./git-remote.js";
+import { writeSyncBlob } from "./project-sync-transfer.js";
+import { UsageError } from "./errors.js";
+import { conversationClient } from "./conversation-commands.js";
+import { withTargetLock } from "./target-lock.js";
+import { checkConversationWorktree, rememberConversationWorktree } from "./conversation-worktree.js";
+const LIMIT = 256 << 20, OUTPUT = (192 << 10) - 128;
+const inside = (root, target) => target === root || target.startsWith(root + sep);
+const safeId = (value) => { if (!/^[a-zA-Z0-9_-]{1,96}$/.test(value))
+    throw new Error('Invalid device request identity'); return value; };
+/** Resolve every existing ancestor, including symlinks. Missing leaf files do not hide an outside parent. */
+export function devicePath(root, requested = '.') {
+    if (/[\0\r\n]/.test(requested))
+        throw new UsageError('Device path contains invalid characters.');
+    const base = realpathSync(root), target = isAbsolute(requested) ? resolve(requested) : resolve(base, requested);
+    let ancestor = target;
+    while (!existsSync(ancestor)) {
+        const parent = dirname(ancestor);
+        if (parent === ancestor)
+            throw new UsageError('Device path is unavailable.');
+        ancestor = parent;
+    }
+    const canonical = resolve(realpathSync(ancestor), relative(ancestor, target));
+    return { path: canonical, outside: !inside(base, canonical) };
+}
+export class DeviceGrants {
+    file;
+    constructor(dir) { this.file = join(dir, 'device-grants.json'); }
+    key(api, project) { return JSON.stringify([api, project]); }
+    read() {
+        try {
+            if (lstatSync(this.file).isSymbolicLink() || (statSync(this.file).mode & 0o077))
+                throw new UsageError('Device grants must be a private file.');
+            const value = JSON.parse(readFileSync(this.file, 'utf8'));
+            if (!value || typeof value !== 'object' || Array.isArray(value))
+                throw new UsageError('Device grants must be an object.');
+            return value;
+        }
+        catch (e) {
+            if (e.code === 'ENOENT')
+                return {};
+            throw e;
+        }
+    }
+    allows(api, project, root, kind, outside) {
+        const grant = this.read()[this.key(api, project)];
+        return !outside && grant?.root === realpathSync(root) && Array.isArray(grant.kinds) && grant.kinds.includes(kind);
+    }
+    async save(api, project, root, kind) {
+        await withTargetLock(join(dirname(this.file), 'device-grants-lock'), () => {
+            const all = this.read(), key = this.key(api, project), canonical = realpathSync(root);
+            all[key] = { root: canonical, kinds: [...new Set([...(all[key]?.root === canonical ? all[key].kinds : []), kind])] };
+            writePrivateFile(dirname(this.file), this.file, JSON.stringify(all) + '\n');
+        });
+    }
+}
+export function deviceSummary(r) {
+    if (tryLocallyAction(r))
+        return tryLocallyAction(r) === 'stop' ? 'Stop this conversation’s local sync and ports.' : 'Try this conversation in an isolated local worktree with two-way sync and localhost ports.';
+    if (r.kind === 'exec')
+        return `Run on your Mac: ${JSON.stringify(r.exec?.argv)} · directory ${r.exec?.cwd_relative ?? '.'}`;
+    if (r.files)
+        return `${r.kind === 'files_pull' ? 'Send to VM' : 'Save on your Mac'}: ${r.files.local_path_relative} ↔ ${r.files.remote_path}`;
+    return `${r.kind === 'port_forward' ? 'Open VM port on your Mac' : 'Reach your Mac from VM'}: ${r.port?.remote_port} ↔ localhost:${r.port?.local_port}`;
+}
+export function tryLocallyAction(r) {
+    if (r.kind === 'try_locally')
+        return 'start';
+    const argv = r.exec?.argv;
+    if (r.kind !== 'exec' || !argv || argv[0] !== 'shard' || argv[1] !== 'conversations' || argv[2] !== 'try' || argv[3] !== r.conversation_id)
+        return null;
+    if (argv.length === 4)
+        return 'start';
+    return argv.length === 5 && argv[4] === '--stop' ? 'stop' : null;
+}
+export async function ensureConversationWorktree(ctx, c, folder, ws) {
+    return withTargetLock(join(ctx.store.dir, 'conversation-worktree-lock'), async () => {
+        const run = gitRunner(folder, { ...process.env, ...ctx.io.env, SHARDFLUX_CONFIG_DIR: ctx.store.dir, SHARDFLUX_API_URL: ctx.apiUrl }, ctx.signal);
+        const name = conversationName(c), worktree = join(folder, '.shard', 'worktrees', name);
+        if (existsSync(worktree))
+            checkConversationWorktree(ctx, c, folder, worktree);
+        const source = ws ?? await conversationWorkspace(ctx, c);
+        await run(['-c', 'core.hooksPath=/dev/null', 'fetch', '--no-tags', shardRemote(source.key, '/shardflux/project/git/hub.git'), `+refs/heads/${c.branch}:refs/remotes/shardflux/${name}`]);
+        if (!existsSync(worktree)) {
+            await mkdir(dirname(worktree), { recursive: true });
+            await run(['-c', 'core.hooksPath=/dev/null', 'worktree', 'add', '-b', c.branch, worktree, `refs/remotes/shardflux/${name}`]);
+            rememberConversationWorktree(ctx, c, folder, worktree);
+        }
+        else {
+            checkConversationWorktree(ctx, c, folder, worktree);
+            const work = gitRunner(worktree, { ...process.env, ...ctx.io.env }, ctx.signal);
+            if (await work(['symbolic-ref', '--short', 'HEAD']) !== c.branch || await work(['rev-parse', '--show-toplevel']) !== realpathSync(worktree))
+                throw new UsageError('Local conversation worktree belongs to other work.');
+        }
+        return realpathSync(worktree);
+    }, ctx.signal);
+}
+export async function deviceExec(argv, cwd, timeoutSeconds = 300, signal) {
+    if (!Array.isArray(argv) || argv.length < 1 || argv.length > 128 || argv.some(a => typeof a !== 'string' || a.includes('\0') || a.length > 65536) || !argv[0])
+        throw new UsageError('Device exec requires an argument array.');
+    if (!Number.isInteger(timeoutSeconds) || timeoutSeconds < 1 || timeoutSeconds > 3600)
+        throw new UsageError('Device timeout must be 1–3600 seconds.');
+    return new Promise((resolveResult, reject) => {
+        const child = spawn(argv[0], argv.slice(1), { cwd, stdio: ['ignore', 'pipe', 'pipe'], detached: process.platform !== 'win32', env: process.env });
+        const stdout = [], stderr = [];
+        let failure;
+        const stop = () => { try {
+            if (child.pid && process.platform !== 'win32')
+                process.kill(-child.pid, 'SIGKILL');
+            else
+                child.kill('SIGKILL');
+        }
+        catch { /* exited */ } };
+        const timeout = setTimeout(() => { failure = new Error('Device command timed out.'); stop(); }, timeoutSeconds * 1000);
+        const abort = () => { failure = new Error('Device command interrupted.'); stop(); };
+        signal?.addEventListener('abort', abort, { once: true });
+        const collect = (target) => { let bytes = 0; return (data) => { bytes += data.length; if (bytes > OUTPUT) {
+            failure = new Error('Device output exceeds 192 KiB per stream.');
+            stop();
+        }
+        else
+            target.push(data); }; };
+        child.stdout.on('data', collect(stdout));
+        child.stderr.on('data', collect(stderr));
+        child.once('error', error => { clearTimeout(timeout); signal?.removeEventListener('abort', abort); reject(error); });
+        child.once('close', code => {
+            clearTimeout(timeout);
+            signal?.removeEventListener('abort', abort);
+            resolveResult({ state: failure ? 'failed' : 'done', exit_code: code ?? 1, stdout_b64: Buffer.concat(stdout).toString('base64'), stderr_b64: Buffer.concat([...stderr, ...(failure ? [Buffer.from(failure.message)] : [])]).toString('base64') });
+        });
+        if (signal?.aborted)
+            abort();
+    });
+}
+export class DeviceExecutor {
+    #ctx;
+    #ask;
+    #deviceId;
+    #handles = new Map();
+    constructor(ctx, ask, deviceId) { this.#ctx = ctx; this.#ask = ask; this.#deviceId = deviceId; }
+    async result(r, result) {
+        await conversationClient(this.#ctx).deviceRequests.result(safeId(r.id), result, { idempotencyKey: `${this.#deviceId}:${r.id}:${result.state}`, signal: this.#ctx.signal });
+    }
+    async execute(r) {
+        const ctx = this.#ctx;
+        safeId(r.id);
+        if (r.state !== 'pending' || r.device_id !== this.#deviceId)
+            return;
+        const records = localConversations(ctx);
+        const matching = Object.values(records).filter(record => record.project_id === r.project_id);
+        const folders = new Set(matching.map(record => record.folder));
+        const record = records[r.conversation_id] ?? (folders.size === 1 ? matching[0] : undefined);
+        if (!record || record.project_id !== r.project_id)
+            return; // No inferred local path for unknown projects.
+        let c = await getConversation(ctx, r.conversation_id), ws = await conversationWorkspace(ctx, c);
+        if (c.project_id !== r.project_id)
+            throw new Error('Device request project changed.');
+        const root = await ensureConversationWorktree(ctx, c, record.folder, ws);
+        const requested = r.exec?.cwd_relative ?? r.files?.local_path_relative ?? '.';
+        const target = devicePath(root, requested), grants = new DeviceGrants(ctx.store.dir);
+        const choice = grants.allows(ctx.apiUrl, r.project_id, record.folder, r.kind, target.outside) ? 'once' : await this.#ask({ type: 'approval', request_id: r.id, project_id: r.project_id, conversation_id: c.id, summary: deviceSummary(r), outside: target.outside });
+        if (choice === 'deny') {
+            await this.result(r, { state: 'denied' });
+            return;
+        }
+        if (choice !== 'once' && choice !== 'always')
+            throw new Error('Device request was not approved.');
+        if (target.outside && choice === 'always')
+            throw new UsageError('An outside path requires Allow once for this request.');
+        if (choice === 'always')
+            await grants.save(ctx.apiUrl, r.project_id, record.folder, r.kind);
+        // Re-read after the approval, before claiming or touching data.
+        if (devicePath(root, requested).path !== target.path)
+            throw new Error('Device path changed during approval.');
+        const current = await getConversation(ctx, r.conversation_id);
+        if (current.project_id !== c.project_id || current.branch !== c.branch || current.state === 'done' || current.state === 'archived')
+            throw new Error('The conversation changed or ended during device approval.');
+        if (current.workspace_id !== c.workspace_id) {
+            ws.cell().close();
+            ws = await conversationWorkspace(ctx, current);
+        }
+        c = current;
+        await this.result(r, { state: 'approved' });
+        await this.result(r, { state: 'running' });
+        const cell = ws.cell();
+        try {
+            let result;
+            if (r.kind === 'try_locally' || tryLocallyAction(r)) {
+                const action = tryLocallyAction(r);
+                for (const [id, handle] of this.#handles)
+                    if (handle.conversation === c.id) {
+                        await handle.stop();
+                        this.#handles.delete(id);
+                    }
+                if (action === 'stop') {
+                    await this.result(r, { state: 'done', stdout_b64: Buffer.from('Local sync and ports stopped.').toString('base64') });
+                    return;
+                }
+                const { tryConversationLocally } = await import("./conversation-local.js");
+                const handle = await tryConversationLocally(ctx, c, record.folder);
+                this.#handles.set(r.id, { conversation: c.id, workspace: ws.id, async stop() { await handle.stop(); cell.close(); } });
+                result = { state: 'done', files_artifact: handle.folder };
+            }
+            else if (r.kind === 'exec') {
+                if (!r.exec)
+                    throw new UsageError('Device exec has no command.');
+                result = await deviceExec(r.exec.argv, target.path, r.exec.timeout_seconds, ctx.signal);
+            }
+            else if (r.kind === 'files_pull' || r.kind === 'files_push') {
+                const f = r.files;
+                if (!f || !f.remote_path.startsWith('/') || /[\0\r\n]/.test(f.remote_path))
+                    throw new UsageError('Device transfer requires an absolute VM path.');
+                const max = f.max_bytes ?? LIMIT;
+                if (!Number.isSafeInteger(max) || max < 1 || max > LIMIT)
+                    throw new UsageError('Device transfer maximum is 256 MiB.');
+                if (r.kind === 'files_pull') {
+                    if (!(await stat(target.path)).isFile() || (await stat(target.path)).size > max)
+                        throw new UsageError('Local transfer file exceeds the requested size or is not a file.');
+                    const bytes = await readFile(target.path);
+                    if (bytes.length > max)
+                        throw new UsageError('Local transfer file grew during reading.');
+                    await writeSyncBlob(cell, f.remote_path, bytes);
+                }
+                else {
+                    const info = await cell.files.stat(f.remote_path);
+                    if (info.type !== 'file' || info.size > max)
+                        throw new UsageError('VM transfer file exceeds the requested size or is not a file.');
+                    const bytes = await cell.files.read(f.remote_path, { length: max + 1 });
+                    if (bytes.length > max || bytes.length !== info.size)
+                        throw new UsageError('VM transfer file changed during reading.');
+                    await mkdir(dirname(target.path), { recursive: true, mode: 0o700 });
+                    const parent = await realpath(dirname(target.path));
+                    if (!target.outside && !inside(root, parent))
+                        throw new Error('Transfer parent escaped the worktree.');
+                    await writeFile(target.path, bytes, { mode: 0o600, flag: 'wx' }); // Existing files need a fresh explicit request, never silent clobber.
+                }
+                result = { state: 'done', files_artifact: r.kind === 'files_pull' ? f.remote_path : relative(root, target.path) };
+            }
+            else {
+                if (!r.port || ![r.port.local_port, r.port.remote_port].every(p => Number.isInteger(p) && p > 0 && p <= 65535))
+                    throw new UsageError('Device ports must be 1–65535.');
+                const handle = await devicePort(ws, cell, r.kind, r.port, ctx.signal);
+                this.#handles.set(r.id, { conversation: c.id, workspace: ws.id, stop: () => handle.stop() });
+                result = { state: 'done' };
+            }
+            await this.result(r, result);
+        }
+        catch (e) {
+            await this.result(r, { state: 'failed', stderr_b64: Buffer.from(e instanceof Error ? e.message : String(e)).toString('base64') });
+        }
+        finally {
+            if (!this.#handles.has(r.id))
+                cell.close();
+        }
+    }
+    async reap() {
+        for (const [id, handle] of this.#handles) {
+            const c = await getConversation(this.#ctx, handle.conversation);
+            const file = join(this.#ctx.store.dir, 'device-stops', `${c.id}.json`);
+            let stopped = false;
+            if (existsSync(file)) {
+                const record = JSON.parse(readFileSync(file, 'utf8'));
+                stopped = record.api_url === this.#ctx.apiUrl;
+            }
+            if (stopped || c.state === 'done' || c.state === 'archived' || c.workspace_id !== handle.workspace) {
+                await handle.stop();
+                this.#handles.delete(id);
+                if (stopped)
+                    rmSync(file);
+            }
+        }
+    }
+    async close() { await Promise.all([...this.#handles.values()].map(h => h.stop())); this.#handles.clear(); }
+}
+export async function devicePort(ws, cell, kind, ports, signal) {
+    const tunnels = new WorkspaceTunnels(() => cell, () => ws.grantedTools);
+    if (kind === 'port_reverse') {
+        const handle = await tunnels.reverse({ remotePort: ports.remote_port, target: `127.0.0.1:${ports.local_port}`, bindAddress: '127.0.0.1', signal });
+        let stopping;
+        return { stop() { return stopping ??= handle.close().finally(() => cell.close()); } };
+    }
+    const peers = new Set();
+    const handles = new Set();
+    const server = createServer(socket => {
+        peers.add(socket);
+        socket.once('close', () => peers.delete(socket));
+        socket.on('error', () => socket.destroy());
+        void tunnels.forward({ remotePort: ports.remote_port, stream: socket, signal }).then(handle => { handles.add(handle); void handle.closed.finally(() => handles.delete(handle)).catch(() => socket.destroy()); }).catch(() => socket.destroy());
+    });
+    await new Promise((resolveListen, reject) => { server.once('error', reject); server.listen(ports.local_port, '127.0.0.1', resolveListen); });
+    let stopping;
+    const abort = () => { void stop().catch(() => undefined); };
+    const stop = () => stopping ??= (async () => { signal.removeEventListener('abort', abort); for (const socket of peers)
+        socket.destroy(); await Promise.all([...handles].map(h => h.close())); await new Promise(resolveClose => server.close(() => resolveClose())); cell.close(); })();
+    signal.addEventListener('abort', abort, { once: true });
+    if (signal.aborted)
+        abort();
+    return { stop };
+}
+const approvalSocket = (dir, id) => {
+    const hash = createHash('sha256').update(resolve(dir)).update(safeId(id)).digest('hex').slice(0, 20);
+    const path = join(dir, 'acp-device', `${hash}.sock`);
+    return Buffer.byteLength(path) < 100 ? path : join('/tmp', `sf-device-${process.getuid?.() ?? 'user'}`, `${hash}.sock`);
+};
+export async function serveAcpDeviceApprovals(dir, id, ask) {
+    const path = approvalSocket(dir, id);
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const parent = lstatSync(dirname(path));
+    if (parent.isSymbolicLink() || (parent.mode & 0o077) || (process.getuid && parent.uid !== process.getuid()))
+        throw new Error('Device approval socket directory must be private and owned by this user.');
+    const peers = new Set();
+    const server = createServer(socket => {
+        peers.add(socket);
+        socket.once('close', () => peers.delete(socket));
+        let body = '';
+        socket.setTimeout(3600_000, () => socket.destroy());
+        socket.on('error', () => socket.destroy());
+        socket.on('data', chunk => {
+            body += String(chunk);
+            if (body.length > 64 << 10)
+                socket.destroy();
+            if (!body.includes('\n'))
+                return;
+            socket.removeAllListeners('data');
+            let approval;
+            try {
+                approval = JSON.parse(body);
+                if (approval.conversation_id !== id || approval.type !== 'approval')
+                    throw new Error('Invalid approval');
+            }
+            catch {
+                socket.destroy();
+                return;
+            }
+            void ask(approval).then(choice => socket.end(JSON.stringify({ choice }) + '\n')).catch(() => socket.end('{"choice":"deny"}\n'));
+        });
+    });
+    await withTargetLock(join(dirname(path), `${id}-lock`), async () => {
+        if (existsSync(path)) {
+            const old = lstatSync(path);
+            if (!old.isSocket() || (process.getuid && old.uid !== process.getuid()))
+                throw new Error('Device approval socket belongs to other work.');
+            const active = await new Promise((resolveActive, reject) => {
+                const probe = createConnection(path);
+                probe.setTimeout(1000, () => { probe.destroy(); reject(new Error('Device approval socket owner is unverified.')); });
+                probe.once('connect', () => { probe.destroy(); resolveActive(true); });
+                probe.once('error', error => { if (error.code === 'ECONNREFUSED')
+                    resolveActive(false);
+                else
+                    reject(error); });
+            });
+            if (active)
+                throw new Error('This ACP conversation already has a laptop bridge.');
+            if (lstatSync(path).ino !== old.ino)
+                throw new Error('Device approval socket owner changed.');
+            rmSync(path);
+        }
+        await new Promise((resolveListen, reject) => { server.once('error', reject); server.listen(path, resolveListen); });
+        chmodSync(path, 0o600);
+    });
+    const inode = lstatSync(path).ino;
+    let stopping;
+    return { stop() { return stopping ??= (async () => { for (const peer of peers)
+            peer.destroy(); await new Promise(resolveClose => server.close(() => resolveClose())); if (existsSync(path) && lstatSync(path).ino === inode)
+            rmSync(path); })(); } };
+}
+export async function askConnectedAcp(dir, approval, signal) {
+    const path = approvalSocket(dir, approval.conversation_id);
+    if (!existsSync(path))
+        return null;
+    return new Promise((resolveChoice, reject) => {
+        const socket = createConnection(path);
+        let text = '';
+        const abort = () => { socket.destroy(); reject(signal.reason instanceof Error ? signal.reason : new Error('Device approval interrupted')); };
+        signal.addEventListener('abort', abort, { once: true });
+        socket.on('connect', () => socket.write(JSON.stringify(approval) + '\n'));
+        socket.on('data', bytes => { text += String(bytes); if (text.length > 1024)
+            socket.destroy(); });
+        socket.once('error', () => { signal.removeEventListener('abort', abort); resolveChoice(null); });
+        socket.once('end', () => { signal.removeEventListener('abort', abort); try {
+            const choice = JSON.parse(text).choice;
+            resolveChoice(['once', 'always', 'deny'].includes(choice) ? choice : 'deny');
+        }
+        catch {
+            resolveChoice('deny');
+        } });
+    });
+}

package/dist/device-helper.d.ts

@@ -0,0 +1,3 @@
+import type { Ctx } from './commands.js';
+/** The menu bar owns this helper and its stdin; VM data can request actions but cannot answer approvals. */
+export declare function runDeviceHelper(ctx: Ctx): Promise<number>;

package/dist/device-helper.js

@@ -0,0 +1,104 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { DeviceExecutor, askConnectedAcp } from "./device-bridge.js";
+import { mirrorProjectConversations } from "./conversation-stash.js";
+import { withTargetLock } from "./target-lock.js";
+import { join } from 'node:path';
+import { conversationsUnavailable } from "./conversations.js";
+import { localConversations } from "./conversations.js";
+import { randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { writePrivateFile } from "./credentials.js";
+import { conversationClient } from "./conversation-commands.js";
+import { Readable } from 'node:stream';
+/** The menu bar owns this helper and its stdin; VM data can request actions but cannot answer approvals. */
+export async function runDeviceHelper(ctx) {
+    const abort = new AbortController(), signal = AbortSignal.any([ctx.signal, abort.signal]);
+    ctx = { ...ctx, signal };
+    const pending = new Map();
+    const inputSource = Readable.from(ctx.io.stdin, { objectMode: false, signal });
+    const input = (async () => {
+        let tail = '';
+        for await (const bytes of inputSource) {
+            tail += Buffer.from(bytes).toString();
+            if (tail.length > 64 << 10)
+                throw new Error('Device approval input exceeds 64 KiB.');
+            for (let newline; (newline = tail.indexOf('\n')) >= 0;) {
+                const line = tail.slice(0, newline);
+                tail = tail.slice(newline + 1);
+                const approval = JSON.parse(line);
+                const resolve = pending.get(approval.request_id);
+                if (resolve && ['once', 'always', 'deny'].includes(approval.choice)) {
+                    pending.delete(approval.request_id);
+                    resolve(approval.choice);
+                }
+            }
+        }
+    })().finally(() => abort.abort());
+    void input.catch(() => abort.abort());
+    const ask = async (approval) => {
+        const acp = await askConnectedAcp(ctx.store.dir, approval, signal);
+        if (acp)
+            return acp;
+        return new Promise(resolve => {
+            const denied = () => { pending.delete(approval.request_id); resolve('deny'); };
+            signal.addEventListener('abort', denied, { once: true });
+            pending.set(approval.request_id, choice => { signal.removeEventListener('abort', denied); resolve(choice); });
+            ctx.io.stdout.write(JSON.stringify(approval) + '\n');
+            if (signal.aborted)
+                denied();
+        });
+    };
+    const working = new Map();
+    const mirrored = new Map();
+    const deviceFile = join(ctx.store.dir, 'device-id');
+    let deviceId;
+    try {
+        deviceId = readFileSync(deviceFile, 'utf8').trim();
+    }
+    catch {
+        deviceId = randomUUID();
+        writePrivateFile(ctx.store.dir, deviceFile, deviceId + '\n');
+    }
+    const executor = new DeviceExecutor(ctx, ask, deviceId);
+    const report = (e) => { ctx.io.stderr.write(`Device bridge: ${e instanceof Error ? e.message : String(e)}\n`); };
+    try {
+        return await withTargetLock(join(ctx.store.dir, 'device-helper-lock'), async () => {
+            while (!signal.aborted) {
+                try {
+                    for (const projectId of new Set(Object.values(localConversations(ctx)).map(r => r.project_id))) {
+                        await conversationClient(ctx).deviceRequests.heartbeat({ projectId, deviceId, leaseSeconds: 30 });
+                        let cursor;
+                        do {
+                            const page = await conversationClient(ctx).deviceRequests.list({ projectId, state: 'pending', limit: 200, ...(cursor ? { cursor } : {}) });
+                            for (const r of page.data) {
+                                if (r.device_id !== deviceId || working.has(r.id) || working.size >= 8)
+                                    continue;
+                                const work = executor.execute(r).catch(report).finally(() => working.delete(r.id));
+                                working.set(r.id, work);
+                            }
+                            cursor = page.nextCursor ?? undefined;
+                        } while (cursor && !signal.aborted);
+                    }
+                    await executor.reap();
+                    await mirrorProjectConversations(ctx, mirrored);
+                }
+                catch (e) {
+                    if (!signal.aborted && !conversationsUnavailable(e))
+                        report(e);
+                }
+                await delay(1000, undefined, { signal }).catch(() => undefined);
+            }
+            return 0;
+        }, signal);
+    }
+    finally {
+        abort.abort();
+        inputSource.destroy();
+        for (const resolve of pending.values())
+            resolve('deny');
+        pending.clear();
+        await executor.close();
+        await Promise.all([...working.values()]);
+        await input.catch(() => undefined);
+    }
+}

package/dist/errors.js

@@ -146,6 +146,11 @@ function isNamed(err, name) {
     return typeof err === 'object' && err !== null && err.name === name;
 }
 export function describeError(err) {
+    // Tunnel teardown and cleanup failures aggregate their causes: name them all, and let the first decide the code.
+    if (err instanceof AggregateError && err.errors.length) {
+        const inner = err.errors.map(e => describeError(e));
+        return { ...inner[0], message: `${err.message}: ${inner.map(i => i.message).join('; ')}` };
+    }
     // A processful command that could not start (0.5.1; the SDK's ExecStartError): the workspace's reason, no HTTP status
     // (the start itself was answered 201) and details.error, details.session_id.
     if (err instanceof ExecStartError)

package/dist/format.js

@@ -960,15 +960,16 @@ export function dataExportText(e, out) {
     ]);
 }
 export function volumeTable(rows) {
-    return table(['ID', 'NAME', 'STATE', 'QUOTA', 'SHARED', 'ATTACHED', 'CREATED'], rows.map((v) => [v.id, v.name, `${v.state}${v.deleted_at ? ' (deleted)' : ''}`, `${v.quota_gib} GiB`, v.org_shared ? 'organization' : 'project', String(v.live_attachments), time(v.created_at)]));
+    return table(['ID', 'NAME', 'KIND', 'STATE', 'QUOTA', 'SHARED', 'ATTACHED', 'CREATED'], rows.map((v) => [v.id, v.name, v.kind ?? 'shared', `${v.state}${v.deleted_at ? ' (deleted)' : ''}`, v.kind === 'project_space' ? 'platform managed' : `${v.quota_gib} GiB`, v.org_shared ? 'organization' : 'project', String(v.live_attachments), time(v.created_at)]));
 }
 export function volumeDetail(v) {
     const err = v.error;
     return kv([
         ['id', v.id],
         ['name', v.name],
+        ['kind', v.kind ?? 'shared'],
         ['state', `${v.state}${v.state_reason ? ` (${v.state_reason})` : ''}`],
-        ['quota', `${v.quota_gib} GiB`],
+        ['quota', v.kind === 'project_space' ? 'platform managed' : `${v.quota_gib} GiB`],
         ['shared', v.org_shared ? 'every project of the organization' : `project ${v.project_id}`],
         ['attachments', String(v.live_attachments)],
         ['usage', pairs(v.usage)],

package/dist/handlers.js

@@ -1,4 +1,5 @@
 import { CREDENTIAL_HANDLERS } from "./credential-prompts.js";
+import { CONVERSATION_HANDLERS } from "./conversation-commands.js";
 /**
  * Every command's handler, keyed by its path ("workspaces open", "auth login"): the project-key commands of
  * commands.ts and the account plane of account-commands.ts (0.5.0). args.test.ts checks that it matches COMMANDS.
@@ -13,4 +14,5 @@ import { AGENT_GIT_HANDLERS } from "./agent-git-commands.js";
 import { MENUBAR_HANDLERS } from "./menubar.js";
 import { UPDATE_HANDLERS } from "./update.js";
 import { FILESYSTEM_HANDLERS } from "./filesystem-commands.js";
-export const HANDLERS = { ...CREDENTIAL_HANDLERS, ...AGENT_CREDENTIAL_HANDLERS, ...KEY_HANDLERS, ...ACCOUNT_HANDLERS, ...AGENT_HANDLERS, ...CENTER_HANDLERS, ...TARGET_HANDLERS, ...AGENT_GIT_HANDLERS, ...MENUBAR_HANDLERS, ...FILESYSTEM_HANDLERS, ...UPDATE_HANDLERS };
+import { CONVERSATION_HANDLERS as LOCAL_CONVERSATION_HANDLERS } from "./conversation-local.js";
+export const HANDLERS = { ...CONVERSATION_HANDLERS, ...LOCAL_CONVERSATION_HANDLERS, ...CREDENTIAL_HANDLERS, ...AGENT_CREDENTIAL_HANDLERS, ...KEY_HANDLERS, ...ACCOUNT_HANDLERS, ...AGENT_HANDLERS, ...CENTER_HANDLERS, ...TARGET_HANDLERS, ...AGENT_GIT_HANDLERS, ...MENUBAR_HANDLERS, ...FILESYSTEM_HANDLERS, ...UPDATE_HANDLERS };

package/dist/main.js

@@ -15,6 +15,10 @@ import { statSync } from 'node:fs';
 import { SDK_VERSION, Shardflux, ShardfluxAccount, isSessionToken } from '@shardflux/sdk';
 import { CLI_VERSION, CENTER_COMMAND, PROJECT_COMMAND, commandHelp, parseCommandLine, resolveApiUrl, resolveWake, resolveWakeTimeout } from "./args.js";
 import { commandCenter } from "./command-center.js";
+import { launchConversationProject } from "./conversation-terminal.js";
+import { runAcp } from "./acp.js";
+import { registerInstalledT3 } from "./t3-provider.js";
+import { runDeviceHelper } from "./device-helper.js";
 import { housekeeping, startupHousekeeping } from "./agent-git-commands.js";
 import { CredentialStore, configDir } from "./credentials.js";
 import { recordInstall } from "./update.js";
@@ -365,6 +369,7 @@ function feedbackHint(info, credentialHint) {
 }
 export async function run(argv, io, opts = {}) {
     const signal = opts.signal ?? new AbortController().signal;
+    await registerInstalledT3(io.env, configDir(io.env), signal);
     const distribution = opts.distribution ?? CLI_DISTRIBUTION;
     const rawKey = io.env.SHARDFLUX_API_KEY;
     // Every credential this command loaded or received: redacted from anything printed on failure.
@@ -626,7 +631,7 @@ export async function run(argv, io, opts = {}) {
             },
         };
         // The update check runs next to the command (not for `version`, which reports it itself).
-        if (!updateCheckDisabled(io.env) && !['version', 'update', 'ssh-proxy'].includes(parsed.command.path[0])) {
+        if (!updateCheckDisabled(io.env) && !['version', 'update', 'ssh-proxy', 'acp', 'device-helper'].includes(parsed.command.path[0])) {
             try {
                 updates = new UpdateCheck({ dir: store.dir, apiUrl, distribution, fetch: base, userAgent });
                 updates.start();
@@ -639,10 +644,11 @@ export async function run(argv, io, opts = {}) {
     catch (err) {
         return report(err);
     }
-    const handler = parsed.command === PROJECT_COMMAND || parsed.command === CENTER_COMMAND ? commandCenter : HANDLERS[parsed.command.path.join(' ')];
+    const handler = parsed.command.path[0] === 'acp' ? (ctx) => runAcp(ctx) : parsed.command.path[0] === 'device-helper' ? runDeviceHelper : parsed.command === PROJECT_COMMAND ? launchConversationProject : parsed.command === CENTER_COMMAND ? commandCenter : HANDLERS[parsed.command.path.join(' ')];
     if (!handler)
         return report(new UsageError(`unknown command "${parsed.command.path.join(' ')}"`));
-    await housekeeping(ctx);
+    if (!['acp', 'device-helper'].includes(parsed.command.path[0]))
+        await housekeeping(ctx);
     const running = handler(ctx, parsed.values, parsed.positionals).then((code) => ({ code }), (err) => ({ err }));
     // On Ctrl-C give the command a moment to clean up (exec sends a cancel), then stop regardless.
     const interrupted = new Promise((resolve) => {
@@ -693,6 +699,12 @@ export async function main(opts = {}) {
             process.exit(130);
         controller.abort(new Error('interrupted'));
     });
+    for (const name of ['SIGTERM', 'SIGHUP'])
+        process.once(name, () => controller.abort(new Error(name)));
+    // A reader that closed its end (ssh after a ProxyCommand session, `| head`) has nothing left to receive.
+    for (const stream of [process.stdout, process.stderr])
+        stream.on('error', (e) => { if (e.code !== 'EPIPE')
+            throw e; });
     const flush = (stream) => new Promise((resolve) => stream.write('', () => resolve()));
     const runtime = { node: process.execPath, script: process.argv[1] ?? '' };
     // The menu bar's update button runs this shard; it finds it here (macOS only, written when it changes).

package/dist/project-sync.d.ts

@@ -35,4 +35,8 @@ export declare function projectReconciler(options: {
     report: (message: string) => void;
     signal?: AbortSignal;
 }): () => Promise<void>;
-export declare function startProjectSync(ctx: Ctx, ws: Workspace, project: ReturnType<typeof projectIdentity>): Promise<ProjectSync>;
+export declare function startProjectSync(ctx: Ctx, ws: Workspace, project: ReturnType<typeof projectIdentity>, options?: {
+    root?: string;
+    agent?: string;
+    seed?: boolean;
+}): Promise<ProjectSync>;

package/dist/project-sync.js

@@ -111,13 +111,14 @@ export function projectReconciler(options) {
     };
     return () => { const next = serial.then(run); serial = next.catch(() => undefined); return next; };
 }
-export async function startProjectSync(ctx, ws, project) {
-    if (ws.labels.agent && ws.labels.agent !== 'main')
-        throw new Error('two-way project sync is only available for the main agent');
-    const root = projectWorkspacePath(project);
+export async function startProjectSync(ctx, ws, project, options = {}) {
+    if (!options.root && ws.labels.agent && ws.labels.agent !== 'main')
+        throw new Error('two-way project sync requires a conversation worktree');
+    const root = options.root ?? projectWorkspacePath(project);
     const cell = ws.cell({ agentLabel: ctx.agentLabel, transitionTimeoutMs: ctx.wakeTimeoutMs });
     await cell.files.mkdir(root, { parents: true });
-    await seedAgentRepository(ctx, ws, project.folder, { root });
+    if (options.seed !== false)
+        await seedAgentRepository(ctx, ws, project.folder, { root });
     const store = new AgentStateStore(ctx.store.dir);
     const key = `${ws.id}:${project.folder}`;
     const states = store.read().project_sync;
@@ -130,7 +131,7 @@ export async function startProjectSync(ctx, ws, project) {
         });
     };
     const report = (message) => { ctx.io.stderr.write(`${message}\n`); };
-    const reconcile = projectReconciler({ folder: project.folder, root, agent: ws.labels.agent ?? 'main', cell, state, save, report, signal: ctx.signal });
+    const reconcile = projectReconciler({ folder: project.folder, root, agent: options.agent ?? ws.labels.agent ?? 'main', cell, state, save, report, signal: ctx.signal });
     const abort = new AbortController();
     const signal = ctx.signal ? AbortSignal.any([ctx.signal, abort.signal]) : abort.signal;
     let stopped = false, dirty = false;