@shardflux/cli 0.24.0 → 0.24.1

package/dist/acp.js

@@ -6,6 +6,8 @@ import { AcpRpc, RpcError, objectValue } from "./acp-rpc.js";
 import { ACP_PROBE_CATALOG, nativeCurrentModel, nativeModelOptions, withoutNativeModel } from "./acp-catalog.js";
 import { ACP_LIFECYCLE, AcpModelCache, acpScope } from "./acp-models.js";
 import { AcpJournal } from "./acp-journal.js";
+import { answeredElsewhere, outcomeFor } from "./acp-permission-elsewhere.js";
+import { conversationClient } from "./conversation-commands.js";
 import { getConversation, conversationWorkspace, preparedInFlight, rememberConversation, resumeConversation, restoreConversationBinding } from "./conversations.js";
 import { seedEvent } from "./seed-phases.js";
 import { projectIdentity } from "./project-identity.js";
@@ -45,6 +47,35 @@ export function acpModelOptions(catalog) {
     });
 }
 const SIGN_IN = 'Sign in to Shardflux from your editor (or run shard acp --login).';
+const CONVERSATION_ID = /^conv_[a-z2-7]{26}$/;
+/** A remote session has no local folder to keep in step: its files stay in the conversation's computer. */
+const NO_FILES = { root: '', conflicts: () => [], reconcile: () => Promise.resolve(), settled: () => true };
+/** The last sequence number in a conversation's ACP journal: a session loaded by id follows from there (its history comes
+ *  from the agent's own session/load replay, not from the journal). */
+async function journalEnd(cell, conversationId) {
+    const path = `/home/user/.local/share/shardflux/acp/${conversationId}/journal.ndjson`;
+    let size;
+    try {
+        size = (await cell.files.stat(path)).size;
+    }
+    catch (error) {
+        if (error.status === 404)
+            return 0;
+        throw error;
+    }
+    for (let want = 64 << 10;; want *= 4) {
+        const start = Math.max(0, size - want), text = Buffer.from(await cell.files.read(path, { offset: start, length: size - start })).toString('utf8');
+        const lines = text.split('\n').filter(Boolean), last = start > 0 && lines.length < 2 ? undefined : lines.at(-1);
+        if (last !== undefined) {
+            const seq = JSON.parse(last).seq;
+            if (Number.isSafeInteger(seq))
+                return seq;
+            throw new Error('Invalid ACP journal entry');
+        }
+        if (start === 0)
+            return 0;
+    }
+}
 function supervisorOwner(workspaceId, conversationId, app, text) {
     const status = JSON.parse(text);
     if (status.conversation_id !== conversationId || status.harness !== app || !Number.isSafeInteger(status.pid) || status.pid <= 0 || !status.start)
@@ -125,7 +156,7 @@ export class ShardfluxAcp {
         if (!this.#initialized)
             throw new RpcError(-32600, 'Initialize first');
         if (method === 'session/list') {
-            const sessions = Object.values(this.#records()).filter(r => r.apiUrl === this.#ctx.apiUrl && (!params.cwd || r.folder === params.cwd));
+            const sessions = Object.values(this.#records()).filter(r => r.apiUrl === this.#ctx.apiUrl && !r.remote && (!params.cwd || r.folder === params.cwd));
             return { sessions: sessions.map(r => ({ sessionId: r.id, cwd: r.folder, updatedAt: r.updatedAt })) };
         }
         if (method === 'session/new') {
@@ -163,12 +194,14 @@ export class ShardfluxAcp {
             throw new RpcError(-32601, 'The provider probe has no conversation.');
         if (typeof params.sessionId !== 'string')
             throw new RpcError(-32602, 'A conversation is required');
-        const session = this.#session(params.sessionId, params.cwd);
+        const session = this.#session(params.sessionId, params.cwd, method);
         const { record } = session;
         if (method === 'session/close') {
             await this.#close(session);
             return {};
         }
+        if (record.remote && !record.model)
+            await this.#remoteHarness(record);
         if (method === 'session/set_model' || (method === 'session/set_config_option' && params.configId === 'model')) {
             const model = String(method === 'session/set_model' ? params.modelId : params.value), selected = parseAcpModel(model);
             if (!record.catalog && record.conversationId)
@@ -272,11 +305,17 @@ export class ShardfluxAcp {
                     record.scope = acpScope(ctx.apiUrl, view);
                     this.#cache.remember(ctx, record.folder, record.scope);
                     if (previous && JSON.stringify(previous) !== JSON.stringify(record.scope)) {
-                        record.catalog = this.#cache.read(record.scope);
-                        const app = record.catalog.claude ? 'claude' : 'codex';
-                        record.model = record.catalog[app] ? acpModel(app, nativeCurrentModel(record.catalog[app])) : '';
-                        if (session.announced)
-                            void this.#modelUpdate(session).catch(() => { });
+                        const cached = this.#cache.read(record.scope);
+                        // A newer template of the same account has no cached models yet: the models this session offered stay
+                        // until its live discovery replaces them, so an editor's first choice is not refused (0.25.0+). Before, the
+                        // list went empty for those seconds and set_model failed with "no longer available".
+                        if (Object.keys(cached).length || previous.organizationId !== record.scope.organizationId) {
+                            record.catalog = cached;
+                            const app = record.catalog.claude ? 'claude' : 'codex';
+                            record.model = record.catalog[app] ? acpModel(app, nativeCurrentModel(record.catalog[app])) : '';
+                            if (session.announced)
+                                void this.#modelUpdate(session).catch(() => { });
+                        }
                     }
                     this.#save(record);
                 },
@@ -354,9 +393,15 @@ export class ShardfluxAcp {
         this.#save(record);
         await this.#modelUpdate(session);
     }
-    #session(id, cwd) {
-        const record = this.#records()[id];
-        if (!record || record.apiUrl !== this.#ctx.apiUrl || (cwd !== undefined && (typeof cwd !== 'string' || projectIdentity(cwd).folder !== record.folder)))
+    #session(id, cwd, method) {
+        let record = this.#records()[id];
+        // Any client can open a conversation it knows by id (session/load or session/resume with a conv_ id): it relays to
+        // the conversation's own ACP session in its computer, with no folder of this computer to sync.
+        if (!record && CONVERSATION_ID.test(id) && (method === 'session/load' || method === 'session/resume')) {
+            record = { id, apiUrl: this.#ctx.apiUrl, folder: typeof cwd === 'string' ? cwd : '', conversationId: id, model: '', from_seq: 0, prompted: true, remote: true, updatedAt: new Date().toISOString() };
+            this.#save(record);
+        }
+        if (!record || record.apiUrl !== this.#ctx.apiUrl || (cwd !== undefined && (typeof cwd !== 'string' || (record.remote ? cwd !== record.folder : projectIdentity(cwd).folder !== record.folder))))
             throw new RpcError(-32000, 'Conversation not found.');
         let session = this.#sessions.get(id);
         if (!session) {
@@ -365,6 +410,17 @@ export class ShardfluxAcp {
         }
         return session;
     }
+    /** A conversation loaded by id: its harness from the API. Only an ACP conversation has a session to relay to. */
+    async #remoteHarness(record) {
+        const c = await getConversation(this.#ctx, record.conversationId);
+        if (c.route !== 'acp')
+            throw new RpcError(-32602, `This conversation runs in ${c.route === 'terminal' ? 'a terminal' : c.route}; open it there.`);
+        if (!c.harness_session_id)
+            throw new RpcError(-32602, 'This conversation has not started its session yet. Try again in a moment.');
+        record.app = c.harness;
+        record.model = acpModel(c.harness, DEFAULT_MODEL);
+        this.#save(record);
+    }
     /** True when this call started the connection (and so reconciled the project files just now). */
     async #connect(session) {
         await session.prepared;
@@ -428,20 +484,21 @@ export class ShardfluxAcp {
             const current = await getConversation(ctx, record.conversationId);
             session.conversation = await resumeConversation(ctx, current);
             session.ws = await conversationWorkspace(ctx, session.conversation);
-            rememberConversation(ctx, session.conversation, record.folder);
+            if (!record.remote)
+                rememberConversation(ctx, session.conversation, record.folder);
             mark('conversation');
         }
         await signIn;
         mark('signed_in');
         let c = session.conversation;
         const cell = session.ws.cell();
-        const menubar = ensureMenubar(ctx.store.dir, ctx.apiUrl, new MenubarManager({ home: ctx.io.env.HOME, signal: ctx.signal }));
+        const menubar = record.remote ? Promise.resolve() : ensureMenubar(ctx.store.dir, ctx.apiUrl, new MenubarManager({ home: ctx.io.env.HOME, signal: ctx.signal }));
         await restoreConversationBinding(ctx, c, session.ws);
         mark('binding');
         // The project files are reconciled, device approvals served and the supervisor launched side by side; the native
         // session starts once the supervisor is up, and the connection is done (the prompt goes) once the files are
         // reconciled too (0.21.1+).
-        const files = (async () => {
+        const files = record.remote ? Promise.resolve(NO_FILES) : (async () => {
             const boundary = await projectSyncBoundary({ ...ctx, signal: AbortSignal.any([ctx.signal, session.stop.signal]) }, session.ws, projectIdentity(record.folder), {
                 root: c.worktree_path, agent: record.id.replace(/^sf-/, 'acp-'), seed: false,
                 stateKey: `acp:${ctx.apiUrl}:${record.id}:${record.folder}`, ...(session.hashes ? { cache: session.hashes } : {}),
@@ -464,7 +521,7 @@ export class ShardfluxAcp {
         session.approvals ??= await serveAcpDeviceApprovals(ctx.store.dir, c.id, async (approval) => {
             const result = objectValue(await this.#client.request('session/request_permission', { sessionId: record.id,
                 toolCall: { toolCallId: approval.request_id, title: approval.summary, kind: 'execute', status: 'pending' },
-                options: [{ optionId: 'once', name: 'Allow once', kind: 'allow_once' }, ...(!approval.outside ? [{ optionId: 'always', name: 'Always for this project', kind: 'allow_always' }] : []), { optionId: 'deny', name: 'Deny', kind: 'reject_once' }] }, 0, AbortSignal.any([ctx.signal, session.stop.signal])));
+                options: [{ optionId: 'once', name: 'Allow once', kind: 'allow_once' }, ...(approval.scope === 'folder' ? [{ optionId: 'always', name: 'Always for this folder', kind: 'allow_always' }] : !approval.outside ? [{ optionId: 'always', name: 'Always for this project', kind: 'allow_always' }] : []), { optionId: 'deny', name: 'Deny', kind: 'reject_once' }] }, 0, AbortSignal.any([ctx.signal, session.stop.signal])));
             const outcome = objectValue(result.outcome);
             return outcome.outcome === 'selected' && (outcome.optionId === 'once' || outcome.optionId === 'always') ? outcome.optionId : 'deny';
         });
@@ -480,7 +537,8 @@ export class ShardfluxAcp {
         if (c.harness !== app)
             throw new Error('The guest did not claim this conversation harness.');
         session.conversation = c;
-        rememberConversation(ctx, c, record.folder);
+        if (!record.remote)
+            rememberConversation(ctx, c, record.folder);
         const owner = supervisorOwner(session.ws.id, c.id, app, statusText);
         if (owner === null)
             throw new Error('ACP supervisor identity does not match this conversation.');
@@ -488,7 +546,8 @@ export class ShardfluxAcp {
         // A cold restore can replace the journal owner without changing the VM id.
         // Its sequence starts at zero; an old cursor would drop initialize/load replies.
         if (record.workspaceId !== session.ws.id || record.owner !== owner) {
-            record.from_seq = 0;
+            // A conversation loaded by id follows its journal from now: the agent's session/load replays its history.
+            record.from_seq = record.remote ? await journalEnd(cell, c.id) : 0;
             delete record.prompt_id;
         }
         record.workspaceId = session.ws.id;
@@ -508,17 +567,28 @@ export class ShardfluxAcp {
                     mapped.update = { ...update, ...this.#configuration(record.model, native, record.catalog) };
                 }
             }
-            if (request) {
-                if (method === 'session/request_permission')
-                    transport.pause();
+            if (request && method === 'session/request_permission') {
+                // The journal relay pauses while the editor shows the prompt (a parked VM stays parked). The person can answer
+                // the same request through the API meanwhile (0.25.0+): then the editor's prompt is withdrawn and the turn goes on.
+                transport.pause();
+                const stop = new AbortController(), signal = AbortSignal.any([ctx.signal, session.stop.signal]);
                 try {
-                    return acpReferences(await this.#client.request(method, mapped, 0, AbortSignal.any([ctx.signal, session.stop.signal])), record, c.worktree_path, true);
+                    const asked = this.#client.request(method, mapped, 0, AbortSignal.any([signal, stop.signal]), true).then(result => ({ result }));
+                    const elsewhere = answeredElsewhere(conversationClient(ctx), c.id, params, Date.now(), AbortSignal.any([signal, stop.signal]))
+                        .then(p => p ? { p } : new Promise(() => undefined));
+                    const first = await Promise.race([asked, elsewhere]);
+                    if ('result' in first)
+                        return acpReferences(first.result, record, c.worktree_path, true);
+                    asked.catch(() => undefined);
+                    return outcomeFor(first.p, mapped);
                 }
                 finally {
-                    if (method === 'session/request_permission')
-                        transport.resume();
+                    stop.abort();
+                    transport.resume();
                 }
             }
+            if (request)
+                return acpReferences(await this.#client.request(method, mapped, 0, AbortSignal.any([ctx.signal, session.stop.signal])), record, c.worktree_path, true);
             await this.#client.notify(method, mapped);
         };
         session.transport = transport;
@@ -530,6 +600,9 @@ export class ShardfluxAcp {
                 throw new Error('Agent protocol version changed');
             mark('initialized');
             const nativeId = c.harness_session_id ?? record.nativeId;
+            // The history a load replays (session/update notifications) reaches the editor under its own session id.
+            if (nativeId)
+                record.nativeId = nativeId;
             const result = objectValue(await transport.rpc.request(nativeId ? 'session/load' : 'session/new', { cwd: c.worktree_path, mcpServers: [{ name: 'shardflux', command: '/usr/local/bin/sf-agent', args: ['conversation', 'mcp'], env: [{ name: 'SF_CONVERSATION_ID', value: c.id }] }], ...(nativeId ? { sessionId: nativeId } : {}) }));
             const id = result.sessionId ?? nativeId;
             mark('session');

package/dist/agent-credentials.d.ts

@@ -9,6 +9,9 @@ export declare function readAgentCredentials(opts?: CredentialSources): Promise<
     app: AgentCredentialApp;
     files: AgentCredentialFile[];
 }>>;
+/** The API's fingerprint of a login as this CLI copies it (the API hashes the same canonical file list), so a login on
+ * this computer can be told apart from the copy in the cloud without uploading it. */
+export declare function credentialFingerprint(files: readonly AgentCredentialFile[]): string;
 /** Reusable by the path launcher (L4). Returns metadata only. */
 export declare function syncAgentCredentials(cloud: Shardflux, opts?: CredentialSources): Promise<import("@shardflux/sdk").AgentCredentialMetadata[]>;
 export declare const AGENT_CREDENTIAL_HANDLERS: Record<string, Handler>;

package/dist/agent-credentials.js

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
@@ -55,6 +56,12 @@ export async function readAgentCredentials(opts = {}) {
         out.push({ app: 'codex', files: [file('~/.codex/auth.json', object(codex, opts.redact), opts.redact)] });
     return out;
 }
+/** The API's fingerprint of a login as this CLI copies it (the API hashes the same canonical file list), so a login on
+ * this computer can be told apart from the copy in the cloud without uploading it. */
+export function credentialFingerprint(files) {
+    const canonical = [...files].sort((a, b) => a.path.localeCompare(b.path)).map(({ path, content_b64, mode }) => ({ path, content_b64, mode }));
+    return createHash('sha256').update(JSON.stringify(canonical)).digest('hex');
+}
 /** Reusable by the path launcher (L4). Returns metadata only. */
 export async function syncAgentCredentials(cloud, opts = {}) {
     const sessions = await readAgentCredentials(opts);

package/dist/args.d.ts

@@ -1,4 +1,4 @@
-export declare const CLI_VERSION = "0.24.0";
+export declare const CLI_VERSION = "0.24.1";
 export interface OptionSpec {
     type: 'string' | 'boolean';
     short?: string;

package/dist/args.js

@@ -11,9 +11,10 @@
  */
 import { parseArgs } from 'node:util';
 import { ACCOUNT_COMMANDS } from "./account-args.js";
+import { BOARD_COMMANDS } from "./board-args.js";
 import { UsageError } from "./errors.js";
 import { DEFAULT_CHOICE, MODEL_CHOICES } from "./agent-models.js";
-export const CLI_VERSION = '0.24.0';
+export const CLI_VERSION = '0.24.1';
 export const GLOBAL_OPTIONS = {
     'api-url': { type: 'string', value: '<url>', description: 'API base URL (default $SHARDFLUX_API_URL, else https://api.shardflux.dev).' },
     json: { type: 'boolean', description: 'Print machine-readable JSON on stdout (errors as JSON on stderr).' },
@@ -147,15 +148,52 @@ const LAYER_HELP = {
 };
 const KEY_COMMANDS = [
     { path: ['conversations', 'list'], summary: 'List project conversations', positionals: [], options: { all: { type: 'boolean', description: 'Fetch every page.' },
-            project: { type: 'string', value: '<id>', description: 'Project ID for a user session.' }, state: { type: 'string', value: '<state>', description: 'Conversation state.' },
-            parent: { type: 'string', value: '<id>', description: 'Children of this conversation.' }, limit: { type: 'string', value: '<count>', description: 'Page size.' }, cursor: { type: 'string', value: '<cursor>', description: 'Next page cursor.' } } },
+            project: { type: 'string', value: '<id>', description: 'Project ID for a user session.' }, org: { type: 'string', value: '<id|slug>', description: 'Signed in: the conversations of every project of this organization you work in (0.25.0+).' }, state: { type: 'string', value: '<state>', description: 'Conversation state.' },
+            parent: { type: 'string', value: '<id>', description: 'Children of this conversation.' }, 'updated-after': { type: 'string', value: '<time>', description: 'Only conversations changed after this time (RFC 3339).' },
+            limit: { type: 'string', value: '<count>', description: 'Page size.' }, cursor: { type: 'string', value: '<cursor>', description: 'Next page cursor.' } },
+        description: 'With an API key: its project’s conversations. Signed in (shard auth login) without a key: the conversations of every project you work in, across your organizations (0.25.0+); --org narrows them to one organization and --project to one project. --org uses your sign-in when you have one.',
+        examples: ['shard c list --state needs_you', 'shard c list --org acme --all --json'] },
+    { path: ['conversations', 'feed'], summary: 'Print project conversations as they change', positionals: [], options: {
+            project: { type: 'string', value: '<id>', description: 'Project ID for a user session.' }, org: { type: 'string', value: '<id|slug>', description: 'Signed in: every project of this organization you work in (0.25.0+).' }, cursor: { type: 'string', value: '<cursor>', description: 'Continue after this feed cursor (--json prints it with each change).' }
+        },
+        description: 'Prints each conversation the moment it changes, until interrupted: "<id>  <title>  <state>", and why it needs you when it does; --json prints one {conversation, cursor} object per line. With an API key: its project. Signed in without a key: every project you work in, on one cursor (0.25.0+); --org follows one organization’s projects and uses your sign-in when you have one.',
+        examples: ['shard c feed', 'shard c feed --org acme --json'] },
     { path: ['conversations', 'resume'], summary: 'Resume a saved conversation in a fresh VM', positionals: [{ name: 'id', required: true }], options: {} },
     { path: ['conversations', 'reader'], summary: 'Open a read-only project space reader', positionals: [{ name: 'project_id', required: true }], options: {} },
-    { path: ['conversations', 'get'], summary: 'Show a conversation and its current VM', positionals: [{ name: 'id', required: true }], options: {} },
-    { path: ['conversations', 'send'], summary: 'Send the next user turn', positionals: [{ name: 'id', required: true }, { name: 'text', required: true, variadic: true, words: true }], options: {} },
+    { path: ['conversations', 'get'], summary: 'Show a conversation and its current VM', positionals: [{ name: 'id', required: true }], options: {},
+        description: 'Prints its title, state and branch, why it needs you when it does, then one line per port a process listens on in its computer: the port, the program, and its URL once exposed (or 127.0.0.1 only). --json returns the conversation with pty_id, listening_ports and listening_ports_at.' },
+    { path: ['conversations', 'watch'], summary: 'Watch a conversation’s terminal live, read-only', positionals: [{ name: 'id', required: true }], options: {},
+        description: 'Shows the terminal the conversation’s agent runs in (its pty_id, terminal conversations) as the agent works: its last 256 KiB, then live output, until the agent’s session exits or you press Ctrl-C. Nothing you type reaches it. Watching never keeps the computer awake while the agent is idle, and ends when the computer sleeps. The output is the terminal’s own bytes, so there is no --json form; shard agents logs <id> --json returns recent output as JSON.',
+        examples: ['shard conversations watch conv_a7k2m4q6s3t5v7x2z4b6d3f5h7'] },
+    { path: ['conversations', 'send'], summary: 'Send the next user turn', positionals: [{ name: 'id', required: true }, { name: 'text', variadic: true, words: true }], options: {
+            file: { type: 'string', multiple: true, value: '<path>', description: 'Attach a file (repeatable, up to 20 of 64 MiB each): it lands in the conversation’s computer before the message, which lists its path there (0.25.0+).' }
+        },
+        description: 'Text and files reach the conversation’s agent as its next turn. A conversation that ended is restored into a fresh computer first. Attached files keep their names under /home/user/.shardflux/attachments/<conversation id>/; each stored path is printed.',
+        examples: ['shard conversations send conv_6qz2dmu4kd3xa7v5l2hgmfnpjy "Fix the failing export test"', 'shard conversations send conv_6qz2dmu4kd3xa7v5l2hgmfnpjy "Why does this page break?" --file screenshot.png --file console.log'] },
     { path: ['conversations', 'wait'], summary: 'Wait for a result or question', positionals: [{ name: 'id', required: true }], options: {
             until: { type: 'string', value: '<states>', description: 'Comma-separated conversation states.' }, timeout: { type: 'string', value: '<seconds>', description: 'Wait for 0..900 seconds (default 900).' }
         } },
+    { path: ['conversations', 'permissions'], summary: 'List what a conversation’s agent asked permission for, oldest first', positionals: [{ name: 'id', required: true }], options: {
+            state: { type: 'string', value: '<state>', description: 'pending, answered or canceled (default every state).' }, all: { type: 'boolean', description: 'Fetch every page.' },
+            limit: { type: 'string', value: '<count>', description: 'Page size (1..200, default 50).' }, cursor: { type: 'string', value: '<cursor>', description: 'Next page cursor.' }
+        },
+        description: 'A conversation is needs_you while its agent waits on a permission request: to run a command, edit a file or fetch a URL. Each line is the request id, its state, what the agent wants to do, the command, path or URL, and the decision once answered. Answer a pending one with shard conversations answer (0.25.0+).',
+        examples: ['shard conversations permissions <conversation-id> --state pending', 'shard c permissions <conversation-id> --all --json'] },
+    { path: ['conversations', 'answer'], summary: 'Answer a permission request (allow, always or deny) or the agent’s question (--pick)', positionals: [{ name: 'id', required: true }, { name: 'permission_id', required: true }, { name: 'decision' }], options: {
+            pick: { type: 'string', multiple: true, value: '<option|question=option>', description: 'The option you pick for the agent’s question (0.25.0+): its label or your own words; repeat it for a multi-select question; "<question>=<option>" when it asks several.' }
+        },
+        description: 'allow lets the agent run the tool this once, always also lets its harness stop asking for this kind of call, deny refuses it (allow_once, allow_always and deny work too). The agent’s question (a request with questions, such as Claude Code’s AskUserQuestion) takes --pick, or deny to decline it; the agent gets exactly what you picked. The agent goes on with its turn, and a parked computer wakes to take the answer. A request answered already, here or where the agent runs, is refused with permission_answered (0.25.0+).',
+        examples: ['shard conversations answer <conversation-id> <permission-id> allow', 'shard c answer <conversation-id> <permission-id> --pick Blue', 'shard c answer <conversation-id> <permission-id> deny'] },
+    { path: ['conversations', 'transcript'], summary: 'Print a conversation’s transcript: its agent’s own JSONL (0.25.0+)', positionals: [{ name: 'id', required: true }], options: {
+            offset: { type: 'string', value: '<bytes>', description: 'Start at this byte offset, such as the next_offset of an earlier read.' },
+            session: { type: 'string', value: '<id>', description: 'An earlier session of the conversation (default: the latest).' },
+            follow: { type: 'boolean', short: 'f', description: 'Keep printing new lines as they are stored, until Ctrl-C.' }
+        },
+        description: 'Prints the Claude Code or Codex transcript byte for byte, as the agent wrote it, for working, parked and finished conversations alike, without waking a VM. With --json: one object (session_id, file, offset, next_offset, size, data); with --follow, one object per line.',
+        examples: ['shard c transcript conv_k3m5q7s2u4w6y3b5d7f2h4j6ln > session.jsonl', 'shard c transcript conv_k3m5q7s2u4w6y3b5d7f2h4j6ln --follow | jq -c \'select(.type=="assistant")\''] },
+    { path: ['conversations', 'events'], summary: 'Follow a conversation live: state, transcript, reply text and tool calls (0.25.0+)', positionals: [{ name: 'id', required: true }], options: {},
+        description: 'Streams the conversation until Ctrl-C, one line per event: state changes, new transcript lines and tool calls, with the reply written as the agent streams it. With --json: one event per line, {"type":"conversation"|"transcript"|"delta","id":…} with the conversation, the transcript lines or the ACP session updates.',
+        examples: ['shard c events conv_k3m5q7s2u4w6y3b5d7f2h4j6ln', 'shard c events conv_k3m5q7s2u4w6y3b5d7f2h4j6ln --json | jq -c \'select(.type=="delta")\''] },
     { path: ['conversations', 'land'], summary: 'Record the landing action performed by the agent', positionals: [{ name: 'id', required: true }, { name: 'action', required: true }], options: { into: { type: 'string', value: '<ref>', description: 'Destination branch or PR URL.' } } },
     { path: ['conversations', 'move'], summary: 'Move at the end of the turn', positionals: [{ name: 'id', required: true }, { name: 'to', required: true }], options: {} },
     { path: ['conversations', 'landing'], summary: 'Show or set how finished conversations reach this checkout', positionals: [{ name: 'mode' }, { name: 'backup' }], options: {
@@ -1296,7 +1334,19 @@ const AGENT_COMMANDS = [
             detach: { type: 'boolean', description: 'Start it in the cloud without opening it here.' },
         }, examples: ['shard move --last', 'shard move --list', 'shard move --session 3d085e35-aa66-4866-9a53-f09719d6767c --detach --json'] },
     { path: ['device', 'requests'], summary: 'Review local device requests waiting for approval', positionals: [], options: {} },
-    ...['approve', 'deny'].map((action) => ({ path: ['device', action], summary: `${action} a local device request`, positionals: [{ name: 'id', required: true }], options: action === 'approve' ? { always: { type: 'boolean', description: 'Allow matching requests for this project; never for outside-folder access.' } } : {} })),
+    ...['approve', 'deny'].map((action) => ({ path: ['device', action], summary: `${action} a local device request`, positionals: [{ name: 'id', required: true }], options: action === 'approve' ? { always: { type: 'boolean', description: 'Allow matching requests for this project, or for a folder request (0.25.0+) that folder and what is inside it; never for other access outside the conversation folder.' } } : {} })),
+    { path: ['conversations', 'start'], summary: 'Start a conversation from the project or on your machine, no folder needed (0.25.0+)', positionals: [], options: {
+            project: { type: 'string', value: '<id>', description: 'The project (default: the API key’s, or this computer’s selected project).' },
+            home: { type: 'boolean', description: 'Start on your machine’s home, without a repository: the agent runs in /home/user and starts threads in the project’s repositories.' },
+            repo: { type: 'string', value: '<remote>', description: 'The repository (default: the project’s most recently active one).' },
+            branch: { type: 'string', value: '<name>', description: 'Start from this branch’s newest saved point in the project (default main, then master).' },
+            app: { type: 'string', value: '<claude|codex>', description: 'Agent app (default claude).' },
+            title: { type: 'string', value: '<text>', description: 'The conversation’s title (default: named by its first message).' },
+            ...MODEL_OPTIONS,
+            prompt: { type: 'string', value: '<text>', description: 'The first message.' },
+            file: { type: 'string', multiple: true, value: '<path>', description: 'Attach a file to the first message (repeatable, up to 20 of 64 MiB each; needs --prompt).' },
+        }, description: 'Starts a Claude Code or Codex conversation in its own cloud computer straight from the project: the repository is checked out from the project’s saved branches, so no local folder is needed. --home starts a coordinator on your machine instead, which spawns threads in the project’s repositories. Prints the conversation id, key and state; open it with shard agents open <id>.',
+        examples: ['shard conversations start --prompt "Add CSV export to the invoices page"', 'shard conversations start --repo https://github.com/acme/app.git --branch main --app codex --prompt "Fix the flaky login test" --file trace.log', 'shard conversations start --home --title "Plan the billing work" --json'] },
     { path: ['conversations', 'try'], summary: 'Try a conversation in a synced local worktree', positionals: [{ name: 'conversation', required: true }], options: { path: { type: 'string', value: '<path>', description: 'Local project checkout.' }, stop: { type: 'boolean', description: 'Stop the device helper’s local sync and ports.' } } },
     { path: ['agents', 'targets'], summary: 'Detect apps or configure managed desktop connections', positionals: [{ name: 'agent' }], options: {
             remove: { type: 'boolean', description: 'Remove this agent’s managed entries, or all entries for this API URL.' },
@@ -1374,12 +1424,97 @@ const SETTINGS_COMMANDS = [{
         description: 'Shows the title marker, where new conversations open and the terminal app (change those two with "shard agents targets --open-in" and "--terminal"). The menu bar and desktop apps change the same settings.',
         examples: ['shard settings', 'shard settings --title-prefix SF', 'shard settings --title-prefix none', 'shard settings --title-prefix default --json'],
     }];
-export const COMMANDS = [...ACCOUNT_COMMANDS.filter((c) => c.path[0] !== 'templates'), ...AGENT_COMMANDS, ...AGENT_CREDENTIAL_COMMANDS, ...AGENT_ACCOUNT_COMMANDS, ...ACCOUNT_ALIASES, ...CLI_PROXY_COMMANDS, ...MENUBAR_COMMANDS, ...SETTINGS_COMMANDS, ...KEY_COMMANDS, ...ACCOUNT_COMMANDS.filter((c) => c.path[0] === 'templates')];
+/** The board's input bar from a terminal (0.25.0+): route a line of input, ask a quick question about the work. */
+const BOARD_SCOPE = {
+    org: { type: 'string', value: '<id|slug>', description: 'Organization whose board to read (default: the saved one, shard orgs use, else your only organization). Slugs need your signed-in session.' },
+    project: { type: 'string', value: '<id|slug>', description: 'A project of it: the input leans to it when nothing else decides.' },
+};
+const BOARD_SCOPE_HELP = 'Reads your organization’s projects and open tasks with your signed-in session; with SHARDFLUX_API_KEY set (or only a saved project API key), that key’s project. It never starts work and never wakes a computer.';
+const ROUTER_COMMANDS = [
+    {
+        path: ['route'],
+        summary: 'Route input like the board’s input bar: its project, task, question or steer, split per task (0.25.0+)',
+        description: [
+            'Decides which project the input belongs to (or your home, for personal work), whether it is a new task, a question or a steer for an open task, and splits input that asks for several tasks into your own words per task, each with a title. "?" or "quick question" at the start makes it a question.',
+            BOARD_SCOPE_HELP,
+            'Prints the kind and where it goes, then each part. With --json: the RouterResult (kind, parts with text, title, project_id and home, task_ref, confidence, uncertain, forced, routed_by, latency_ms).',
+        ].join('\n\n'),
+        positionals: [{ name: 'text', variadic: true, words: true, required: true }],
+        options: {
+            task: { type: 'string', value: '<task-id>', description: 'The open task you point at (task_…): input about it steers it, unless it asks about it.' },
+            ...BOARD_SCOPE,
+        },
+        examples: ['shard route "fix the hero image on the landing page and add a GPU row to the pricing table"', 'shard route --task task_healthzhealthzhealthzhealt return 503 instead of 500 when the database is down', 'shard route "? is the deploy done" --json'],
+    },
+    {
+        path: ['ask'],
+        summary: 'Ask a quick question about your work, answered from the board as it is written (0.25.0+)',
+        description: [
+            'Answers from your tasks, their plans and states, sealed reports, the conversations behind them and what their agents last wrote. The answer streams to standard output as it is written; one that needs work ends with "Make it a task?".',
+            BOARD_SCOPE_HELP,
+            'With --json: the whole answer as one object (text, needs_work, sources, answered_by, first_token_ms, total_ms).',
+        ].join('\n\n'),
+        positionals: [{ name: 'question', variadic: true, words: true, required: true }],
+        options: {
+            task: { type: 'string', value: '<task-id>', description: 'The task the question is about (task_…).' },
+            ...BOARD_SCOPE,
+        },
+        examples: ['shard ask what is the healthz work doing right now', 'shard ask --task task_healthzhealthzhealthzhealt "is it done?"', 'shard ask "what is blocking the pricing page?" --json'],
+    },
+];
+/** The project a drive or models command acts in (0.25.0+). */
+const PROJECT_SCOPE = {
+    project: { type: 'string', value: '<id|slug>', description: 'The project (default: the API key’s, else your default project). Signed in, any of your projects, by id or slug.' },
+};
+const DRIVE_HELP = 'The project drive keeps a project’s files: the screenshots, logs, reports and notes your agents and people save and read by path, the same from a phone, a script or another agent whether the project’s computers are working, asleep or gone. Paths are relative to the project space root, the names agents see under /shardflux/project (tasks/t_ab12/evidence/healthz.png, BOARD.md). Every save is a new version named by the SHA-256 of its bytes, and every version stays readable by its sha256, also after the path is overwritten or removed.';
+const DRIVE_COMMANDS = [
+    { path: ['drive', 'ls'], summary: 'List the project drive’s files: size, saved time, type and path (0.25.0+)', positionals: [{ name: 'prefix' }], options: {
+            ...PROJECT_SCOPE,
+            all: { type: 'boolean', description: 'Fetch every page.' },
+            limit: { type: 'string', value: '<n>', description: 'Page size (1 to 1000, default 200).' },
+            cursor: { type: 'string', value: '<cursor>', description: 'Continue from a previous page.' },
+        }, description: `${DRIVE_HELP} Lists the current version of each file, by path; a prefix such as tasks/t_ab12/ lists only that folder. --json returns data (each file with its sha256) and next_cursor.`,
+        examples: ['shard drive ls', 'shard drive ls tasks/t_ab12/evidence/', 'shard drive ls --all --json'] },
+    { path: ['drive', 'get'], summary: 'Read a file from the project drive: its bytes to standard output, or to a file with -o (0.25.0+)', positionals: [{ name: 'path', required: true }], options: {
+            ...PROJECT_SCOPE,
+            sha256: { type: 'string', value: '<hex>', description: 'Read exactly this version (the current one or an earlier one).' },
+            out: { type: 'string', short: 'o', value: '<file>', description: 'Write the bytes to this file.' },
+        }, description: `${DRIVE_HELP} The bytes are checked against their SHA-256 before they are written. --json without -o returns the file as content_base64 with its sha256, size and content_type.`,
+        examples: ['shard drive get BOARD.md', 'shard drive get tasks/t_ab12/evidence/healthz.png -o healthz.png', 'shard drive get BOARD.md --sha256 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08'] },
+    { path: ['drive', 'put'], summary: 'Save a file to the project drive as a new version, and print its path and sha256 (0.25.0+)', positionals: [{ name: 'local-file', required: true }, { name: 'drive-path' }], options: {
+            ...PROJECT_SCOPE,
+            'content-type': { type: 'string', value: '<type>', description: 'Stored with the file (default: from its extension, e.g. .png image/png, .md text/markdown).' },
+        }, description: `${DRIVE_HELP} The drive path defaults to the file’s name; - reads the file from standard input (name the drive path). Saving the bytes that are already current keeps that version.`,
+        examples: ['shard drive put BOARD.md', 'shard drive put ./out/healthz.png tasks/t_ab12/evidence/healthz.png', 'git diff | shard drive put - tasks/t_ab12/review.diff --json'] },
+    { path: ['drive', 'rm'], summary: 'Remove a file from the project drive; its versions stay readable by sha256 (0.25.0+)', positionals: [{ name: 'path', required: true }], options: { ...PROJECT_SCOPE },
+        description: `${DRIVE_HELP} After rm the path no longer lists or reads; shard drive get <path> --sha256 <hex> still reads each of its versions.`,
+        examples: ['shard drive rm tasks/t_ab12/notes/draft.md'] },
+];
+const MODELS_HELP = 'The model template: which agent app (harness), model and effort each role of a task runs with, from the Claude and Codex accounts your organization connected. master plans and coordinates, builder does the work, hard takes the hardest parts, light the small ones, and reviewer reviews with a fresh context. The primary provider runs master, builder and hard; the other one, light and reviewer. A role whose account waits for its next usage window shows until when, and what the other provider would run now.';
+const MODEL_COMMANDS = [
+    { path: ['models'], summary: 'Show which harness, model and effort each role of a task runs with (0.25.0+)', positionals: [], options: {
+            ...PROJECT_SCOPE,
+            harness: { type: 'string', value: '<claude|codex>', description: 'The provider the task runs on: keeps master, builder and hard work on it.' },
+            attempt: { type: 'string', value: '<n>', description: 'A retry after a failure (1 to 10): retries move to the other provider, or one tier up when only one is connected.' },
+        }, description: `${MODELS_HELP} --json returns the template: primary, secondary, connected and roles, with each role’s harness, model and effort exactly as shard conversations start --app, --model and --effort take them.`,
+        examples: ['shard models', 'shard models --harness codex --attempt 1', 'shard models --json'] },
+    { path: ['models', 'primary'], summary: 'Make Claude or Codex the primary provider of this project or your organization, or clear it (0.25.0+)', positionals: [{ name: 'claude|codex|clear', required: true }], options: {
+            ...PROJECT_SCOPE,
+            org: { type: 'string', value: '<id|slug>', description: 'Set the organization’s default for every project instead (owners and admins, signed in).' },
+        }, description: `${MODELS_HELP} The primary is this project’s choice when it has one, else the organization’s, else the provider connected first; clear removes the choice. Prints the template with the new primary.`,
+        examples: ['shard models primary codex', 'shard models primary claude --org acme', 'shard models primary clear --project web'] },
+];
+export const COMMANDS = [...ACCOUNT_COMMANDS.filter((c) => c.path[0] !== 'templates'), ...AGENT_COMMANDS, ...ROUTER_COMMANDS, ...AGENT_CREDENTIAL_COMMANDS, ...AGENT_ACCOUNT_COMMANDS, ...ACCOUNT_ALIASES, ...CLI_PROXY_COMMANDS, ...MENUBAR_COMMANDS, ...SETTINGS_COMMANDS, ...KEY_COMMANDS, ...BOARD_COMMANDS, ...DRIVE_COMMANDS, ...MODEL_COMMANDS, ...ACCOUNT_COMMANDS.filter((c) => c.path[0] === 'templates')];
 const GROUPS = {
     device: 'Local device approvals',
     'cli-proxy': 'Your hosted CLIProxyAPI, reachable at http://127.0.0.1:8317 on this computer and in every VM',
     menubar: 'macOS menu bar app',
     conversations: 'Project conversations, branches and messages',
+    task: 'Tasks on the board, in your own words: add, show, edit, move, steer, delete and clear them (0.25.0+)',
+    'needs-you': 'Everything your agents wait on, oldest first, and one answer command for each (0.25.0+)',
+    approvals: 'The approval mode and always-allow rules your agents work under (0.25.0+)',
+    drive: 'The project drive: files every agent, phone and person of the project reads and writes, each version kept by its SHA-256 (0.25.0+)',
+    models: 'The model template: which harness, model and effort each role of a task runs with, and the primary provider (0.25.0+)',
     agents: 'Cloud agent sessions and copied credentials',
     auth: 'Create an account and sign in (the session is saved in the credentials file); passwords, email, two-factor authentication and sessions',
     'auth password': 'Change or reset your password',
@@ -1792,7 +1927,7 @@ export const EXIT_CODE_HELP = [
 /** The top help's sections: every command's group (first word) is in exactly one (args.test.ts checks). */
 export const HELP_SECTIONS = [
     { title: 'Account (a user session: shard signup or shard auth login)', groups: ['signup', 'verify', 'auth', 'setup', 'env', 'orgs', 'projects', 'api-keys', 'members', 'invitations', 'billing', 'audit', 'account'] },
-    { title: 'Cloud agents (shard ./ starts one; a project API key)', groups: ['conversations', 'move', 'machine', 'template', 'agents', 'settings', 'accounts', 'device', 'cli-proxy', 'ssh-proxy'] },
+    { title: 'Cloud agents (shard ./ starts one; a project API key)', groups: ['conversations', 'board', 'task', 'needs-you', 'approvals', 'route', 'ask', 'drive', 'models', 'move', 'machine', 'template', 'agents', 'settings', 'accounts', 'device', 'cli-proxy', 'ssh-proxy'] },
     { title: 'Workspaces for your app (a project API key: SHARDFLUX_API_KEY, else the one shard setup saved)', groups: ['login', 'whoami', 'status', 'usage', 'workspaces', 'files', 'operations', 'executions', 'secrets', 'credentials', 'volumes', 'egress'] },
     { title: 'Templates for your app’s workspaces (not for cloud agents; publish and archive use the session, the rest the API key)', groups: ['templates'] },
     { title: 'Other', groups: ['menubar', 'update', 'feedback', 'version'] },

package/dist/board-args.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The Orchestrator board's command table (0.25.0+, SDK 0.28.0): `shard board`, `shard task …`, `shard needs-you …` and
+ * `shard approvals …`. Pure data like args.ts, which merges it into COMMANDS; board-commands.ts has the handlers.
+ */
+import type { CommandSpec } from './args.js';
+export declare const BOARD_COMMANDS: CommandSpec[];