@shardflux/cli 0.25.0 → 0.28.1

package/dist/brain-commands.js

@@ -0,0 +1,78 @@
+/**
+ * Your brain (0.27.0+, SDK 0.29.0): `shard brain ls|get`, read-only, through @shardflux/sdk's `brain` namespace. The
+ * signed-in session reads the person's brain in an organization (--org, else the saved one, else their only one);
+ * SHARDFLUX_API_KEY in the environment (or a saved key without a session) reads the brain of the member who created
+ * that key (person-scope.ts). Output is shaped like `shard drive ls|get`.
+ */
+import { writeFile } from 'node:fs/promises';
+import { encodeBrainPath } from '@shardflux/sdk';
+import { out, str } from "./commands.js";
+import { driveTable } from "./drive-commands.js";
+import { EXIT, UsageError } from "./errors.js";
+import { humanBytes } from "./files-mirror.js";
+import { json } from "./format.js";
+import { inScope } from "./person-scope.js";
+const SHA256 = /^[0-9a-f]{64}$/i;
+const orgOnly = (scope) => (scope.organizationId ? { organizationId: scope.organizationId } : {});
+/** A brain path checked as the SDK sends it: relative, no empty, `.` or `..` segments (exit 2 before any request). */
+function brainPath(path) {
+    try {
+        encodeBrainPath(path);
+    }
+    catch (err) {
+        if (err instanceof TypeError)
+            throw new UsageError(`brain path: ${err.message}`);
+        throw err;
+    }
+    return path;
+}
+export const BRAIN_HANDLERS = {
+    async 'brain ls'(ctx, values, [prefix]) {
+        const limitText = str(values.limit);
+        const limit = limitText === undefined ? undefined : Number(limitText);
+        if (limit !== undefined && (!Number.isInteger(limit) || limit < 1 || limit > 1000))
+            throw new UsageError('--limit must be 1 to 1000.');
+        const { rows, next, version } = await inScope(ctx, values, async (client, scope) => {
+            const rows = [];
+            const seen = new Set();
+            let cursor = str(values.cursor), next, version;
+            do {
+                const page = await client.brain.list({ ...orgOnly(scope), ...(prefix ? { prefix } : {}), ...(limit ? { limit } : values.all === true ? { limit: 1000 } : {}), ...(cursor ? { cursor } : {}), signal: ctx.signal });
+                rows.push(...page.data);
+                next = page.nextCursor;
+                version = page.version;
+                cursor = next ?? undefined;
+                if (values.all === true && cursor) {
+                    if (seen.has(cursor))
+                        throw new UsageError('The brain listing repeated its cursor. Try again.');
+                    seen.add(cursor);
+                }
+            } while (values.all === true && cursor);
+            return { rows, next, version };
+        });
+        out(ctx, rows.length ? driveTable(rows) : 'No files.\n', { data: rows, next_cursor: next, version });
+        if (!ctx.json && next)
+            ctx.io.stderr.write(`more: shard brain ls${prefix ? ` ${prefix}` : ''} --cursor ${next}\n`);
+        return EXIT.ok;
+    },
+    async 'brain get'(ctx, values, [path]) {
+        brainPath(path);
+        const sha256 = str(values.sha256)?.toLowerCase();
+        if (sha256 !== undefined && !SHA256.test(sha256))
+            throw new UsageError('--sha256 takes the 64 hex characters of a version’s SHA-256 (shard brain ls --json shows them).');
+        const file = await inScope(ctx, values, (client, scope) => client.brain.read(path, { ...orgOnly(scope), ...(sha256 ? { sha256 } : {}), signal: ctx.signal }));
+        const dest = str(values.out);
+        const meta = { path, sha256: file.sha256, size: file.size, content_type: file.contentType };
+        if (dest !== undefined) {
+            await writeFile(dest, file.bytes);
+            out(ctx, `Wrote ${path} to ${dest} (${humanBytes(file.size)}, sha256 ${file.sha256})\n`, { ...meta, out: dest });
+        }
+        else if (ctx.json) {
+            ctx.io.stdout.write(json({ ...meta, content_base64: Buffer.from(file.bytes).toString('base64') }));
+        }
+        else {
+            ctx.io.stdout.write(file.bytes);
+        }
+        return EXIT.ok;
+    },
+};

package/dist/cli-proxy.d.ts

@@ -16,8 +16,7 @@ export declare const cliProxyTools: {
     inVm: () => boolean;
     kill: (pid: number) => void;
 };
-/** The launchd agent that keeps the forwarder on 127.0.0.1:8317 on a Mac. */
-export declare const FORWARD_LABEL = "dev.shardflux.cli-proxy-forward";
+export { FORWARD_LABEL, forwarderPlistPath, refreshForwarderAgent } from './forwarder-refresh.js';
 /** Where every VM finds the hub info (the machine template carries it). */
 export declare const VM_HUB_INFO_PATH = "/home/user/.config/shardflux-cli-proxy.json";
 export interface LocalLogin {
@@ -151,7 +150,6 @@ export interface PlistOptions {
 }
 /** The launchd agent: `shard cli-proxy forward` at login, started again whenever it exits. */
 export declare function forwarderPlist(o: PlistOptions): string;
-export declare function forwarderPlistPath(home: string): string;
 /** Whether Shardflux's forwarder answers on 127.0.0.1:port, and for which hub. */
 export interface ForwarderIdentity {
     hub: string | null; /** `mac`: shard cli-proxy forward; `vm`: sf-agent cli-proxy-forward. */
@@ -168,16 +166,6 @@ export interface LaunchdDeps {
     identity?: () => Promise<ForwarderIdentity | null>;
     sleep?: (ms: number) => Promise<void>;
 }
-/**
- * After `shard` is updated, the launchd forwarder still runs the program it started with. Called on every shard run
- * (one file read on macOS): an installed forwarder agent recorded for another shard version is started again, on this
- * one. Returns whether it was.
- */
-export declare function refreshForwarderAgent(env: Record<string, string | undefined>, dir: string, deps?: {
-    run?: ProgramRunner;
-    uid?: number;
-    platform?: NodeJS.Platform;
-}): Promise<boolean>;
 /** Installs (or refreshes) the launchd agent and waits until the forwarder answers. macOS only. */
 export declare function installForwarderAgent(ctx: Ctx, apiUrl: string, deps?: LaunchdDeps): Promise<string>;
 /**

package/dist/cli-proxy.js

@@ -47,7 +47,8 @@ export const cliProxyTools = {
     kill: (pid) => { process.kill(pid, 'SIGTERM'); },
 };
 /** The launchd agent that keeps the forwarder on 127.0.0.1:8317 on a Mac. */
-export const FORWARD_LABEL = 'dev.shardflux.cli-proxy-forward';
+import { FORWARD_LABEL, forwarderPlistPath, recordForwarder } from "./forwarder-refresh.js";
+export { FORWARD_LABEL, forwarderPlistPath, refreshForwarderAgent } from "./forwarder-refresh.js";
 /** Where every VM finds the hub info (the machine template carries it). */
 // Outside ~/.config/shardflux, which machines and templates never capture (the platform's per-VM state).
 export const VM_HUB_INFO_PATH = '/home/user/.config/shardflux-cli-proxy.json';
@@ -470,9 +471,6 @@ ${Object.entries(env).map(([k, v]) => `    <key>${k}</key>\n    <string>${xml(v)
 </plist>
 `;
 }
-export function forwarderPlistPath(home) {
-    return join(home, 'Library', 'LaunchAgents', `${FORWARD_LABEL}.plist`);
-}
 /** Whether Shardflux's forwarder (this computer's, or a VM's sf-agent) answers on 127.0.0.1:port, and for which hub. */
 export async function forwarderIdentity(port = CLI_PROXY_PORT) {
     try {
@@ -492,29 +490,6 @@ export function inShardfluxVm() {
 }
 /** The forwarder that answers is this shard's (an update replaces the program, not the running process). */
 const current = (id) => id !== null && id.kind === 'mac' && id.version === CLI_VERSION;
-/** The shard version the launchd forwarder runs (refreshForwarderAgent compares it with this one). */
-function recordForwarder(dir) {
-    new AgentStateStore(dir).update((doc) => { doc.cli_proxy_forwarder = { version: CLI_VERSION }; });
-}
-/**
- * After `shard` is updated, the launchd forwarder still runs the program it started with. Called on every shard run
- * (one file read on macOS): an installed forwarder agent recorded for another shard version is started again, on this
- * one. Returns whether it was.
- */
-export async function refreshForwarderAgent(env, dir, deps = {}) {
-    if ((deps.platform ?? process.platform) !== 'darwin')
-        return false;
-    if (!existsSync(forwarderPlistPath(env.HOME || homedir())))
-        return false;
-    const store = new AgentStateStore(dir);
-    const record = store.read().cli_proxy_forwarder;
-    if (record?.version === CLI_VERSION)
-        return false;
-    // Recorded first: a failed restart is not retried on every command (the next import installs the agent again).
-    recordForwarder(dir);
-    await (deps.run ?? cliProxyTools.run)('launchctl', ['kickstart', '-k', `gui/${deps.uid ?? userInfo().uid}/${FORWARD_LABEL}`]);
-    return true;
-}
 /** Installs (or refreshes) the launchd agent and waits until the forwarder answers. macOS only. */
 export async function installForwarderAgent(ctx, apiUrl, deps = {}) {
     const runtime = ctx.runtime;

package/dist/client-settings.d.ts

@@ -21,7 +21,7 @@ export declare function parseTitlePrefix(spec: string): string | null;
 export declare function storedTitlePrefix(dir: string): string | undefined;
 export declare function saveTitlePrefix(dir: string, choice: string | null): void;
 /** `shard settings --json`. title_prefix: null is the default, "" none. open_in and terminal_app are the saved
- * choices (null: automatic). */
+ * choices (null: automatic). auto_land (0.27.0+): finished cloud work lands in your folders on its own (default on). */
 export declare function clientSettings(dir: string): {
     title_prefix: string | null;
     title_prefix_default: string;
@@ -34,6 +34,7 @@ export declare function clientSettings(dir: string): {
         id: import("./terminal-apps.js").TerminalId;
         mode: import("./terminal-apps.js").TerminalMode;
     } | null;
+    auto_land: boolean;
 };
 export declare function settingsText(s: ReturnType<typeof clientSettings>): string;
 export declare const SETTINGS_HANDLERS: Record<string, Handler>;

package/dist/client-settings.js

@@ -4,6 +4,7 @@ import { UsageError } from "./errors.js";
 import { objectValue } from "./acp-rpc.js";
 import { openInTargets } from "./t3-mode.js";
 import { storedTerminal, terminalName } from "./terminal-apps.js";
+import { TwinLedger } from "./worktree-twin.js";
 /** The platform's marker (the guest's "☁ " without its space). */
 export const DEFAULT_TITLE_PREFIX = '☁';
 /** At most this many characters on one line, as the API takes it (POST /v1/conversations title_prefix). */
@@ -43,7 +44,7 @@ export function saveTitlePrefix(dir, choice) {
         doc.title_prefix = choice; });
 }
 /** `shard settings --json`. title_prefix: null is the default, "" none. open_in and terminal_app are the saved
- * choices (null: automatic). */
+ * choices (null: automatic). auto_land (0.27.0+): finished cloud work lands in your folders on its own (default on). */
 export function clientSettings(dir) {
     const doc = new AgentStateStore(dir).read();
     const saved = objectValue(doc.open_in);
@@ -58,6 +59,7 @@ export function clientSettings(dir) {
         title_prefix_default: DEFAULT_TITLE_PREFIX,
         open_in: { claude: openIn('claude'), codex: openIn('codex') },
         terminal_app: terminal ? { ...terminal, name: terminalName(terminal.id) } : null,
+        auto_land: new TwinLedger(dir).autoLand(),
     };
 }
 const sampleTitle = (prefix) => `${prefix === null ? DEFAULT_TITLE_PREFIX + ' ' : prefix ? prefix + ' ' : ''}${SAMPLE}`;
@@ -68,11 +70,21 @@ export function settingsText(s) {
         `Title marker   ${markerLine(s.title_prefix)}   "${sampleTitle(s.title_prefix)}"`,
         `Open in        Claude: ${target(s.open_in.claude)} · Codex: ${target(s.open_in.codex)}`,
         `Terminal app   ${s.terminal_app ? `${s.terminal_app.name}, ${s.terminal_app.mode === 'tab' ? 'new tab' : 'new window'}` : 'automatic'}`,
+        `Auto land      ${s.auto_land ? 'on: finished cloud work lands in your folder' : 'off'}`,
         '',
-        'Change the marker with shard settings --title-prefix <text|none|default>; where conversations open with shard agents targets --open-in and --terminal.',
+        'Change the marker with shard settings --title-prefix <text|none|default>, auto land with --auto-land on|off; where conversations open with shard agents targets --open-in and --terminal.',
     ].join('\n') + '\n';
 }
 function settings(ctx, values) {
+    const land = values['auto-land'];
+    if (land !== undefined) {
+        if (land !== 'on' && land !== 'off')
+            throw new UsageError('--auto-land takes on or off.');
+        new TwinLedger(ctx.store.dir).setAutoLand(land === 'on');
+        const s = clientSettings(ctx.store.dir);
+        out(ctx, s.auto_land ? 'Finished cloud work lands in your folder automatically.\n' : 'Cloud work stays in the cloud until you land it (shard task land, shard conversations land).\n', s);
+        return 0;
+    }
     const spec = values['title-prefix'];
     if (spec !== undefined && typeof spec !== 'string')
         throw new UsageError('--title-prefix takes text, none or default.');

package/dist/codex-cloud.d.ts

@@ -8,6 +8,8 @@ import type { InitialImage } from './initial-prompt.js';
 /** Cloud threads open in the browser, preserving the durable provider destination on every OS. */
 export declare function openCodexThread(task: CodexCloudTask, env: Ctx['io']['env'], platform?: NodeJS.Platform): Promise<void>;
 export declare function submitCloudInitialPrompt(ctx: Ctx, c: Conversation, prompt: string, workspaceKey: string): Promise<void>;
+/** Admit the already seeded executor and hand its first prompt to the durable inbox. */
+export declare function startCloudTask(ctx: Ctx, c: Conversation, workspaceKey: string, prompt?: string): Promise<CodexCloudTask>;
 /** Prints the Cloud thread (and its link) and opens it in your browser; --json prints it instead. */
 export declare function printCloudThread(ctx: Ctx, c: Conversation, task: CodexCloudTask, submitted?: boolean, choice?: ModelChoice): Promise<void>;
 /**

package/dist/codex-cloud.js

@@ -1,11 +1,11 @@
 import { randomUUID } from 'node:crypto';
 import { spawn } from 'node:child_process';
-import { ShardfluxApiError, codexAccountMatches, localCodexLogin } from '@shardflux/sdk';
+import { CodexAdmissionStoppedError, ShardfluxApiError, codexAccountMatches, localCodexLogin } from '@shardflux/sdk';
 import { CodedError, UsageError } from "./errors.js";
 import { json } from "./format.js";
 import { syncAgentCredentials } from "./agent-credentials.js";
 import { createConversation, conversationWorkspace, getConversation, localConversations, recordedChoice, resumeConversation, seedConversation } from "./conversations.js";
-import { CHOICE_PENDING, choiceReport, hasChoice, modelChoice } from "./agent-models.js";
+import { CHOICE_PENDING, choiceReport, hasChoice, liveModels, modelChoice } from "./agent-models.js";
 import { AgentStateStore } from "./agent-state.js";
 import { installedTargets } from "./agent-targets.js";
 import { ensureProjectGit } from "./project-git.js";
@@ -39,6 +39,15 @@ export async function submitCloudInitialPrompt(ctx, c, prompt, workspaceKey) {
         throw new CodedError('initial_prompt_failed', `Created ${workspaceKey}, but the initial prompt could not be confirmed. Open that conversation before starting another.`, undefined, { workspace_key: workspaceKey, conversation_id: c.id, submitted: null });
     }
 }
+/** Admit the already seeded executor and hand its first prompt to the durable inbox. */
+export async function startCloudTask(ctx, c, workspaceKey, prompt) {
+    await ctx.cloud().codex.admit(c.id, { idempotencyKey: `codex-${c.id}`, signal: ctx.signal });
+    // The durable inbox holds this input until the executor is active. Setup
+    // continues while the prompt is queued; a lost send retains the stable key.
+    if (prompt !== undefined)
+        await submitCloudInitialPrompt(ctx, c, prompt, workspaceKey);
+    return ctx.cloud().codex.waitTask(c.id, { timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal });
+}
 /** Prints the Cloud thread (and its link) and opens it in your browser; --json prints it instead. */
 export async function printCloudThread(ctx, c, task, submitted = false, choice) { return output(ctx, c, task, submitted, choice); }
 /** Whether this computer has the Codex app, which opens a Cloud thread's codex:// link (on Linux 0.23.0+). */
@@ -215,7 +224,7 @@ export async function launchCodexCloud(ctx, values, path, images = []) {
         throw new UsageError('New Codex conversations open in Codex Cloud. Omit --in or use --in codex-app.');
     if (values.like !== undefined)
         throw new UsageError('Choose the project directory with --path; new Codex conversations use its latest machine template.');
-    const choice = modelChoice(values, 'codex');
+    const choice = modelChoice(values, 'codex', await liveModels(ctx, values, 'codex'));
     const project = projectIdentity(path);
     await ensureProjectGit(ctx, project.folder);
     await gitRunner(project.folder, { ...process.env, ...ctx.io.env }, ctx.signal)(['rev-parse', 'HEAD']);
@@ -247,12 +256,9 @@ export async function launchCodexCloud(ctx, values, path, images = []) {
         // --computer: the conversation VM's desktop is on before Codex starts, so the thread gets the computer tools.
         // The thread's tools run in this VM, so its first message can name the images by their VM paths.
         // Idempotency follows the durable conversation, including a lost response.
-        await ctx.cloud().codex.admit(c.id, { idempotencyKey: `codex-${c.id}`, signal: ctx.signal });
-        const task = await ctx.cloud().codex.waitTask(c.id, { timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal });
-        new AgentStateStore(ctx.store.dir).save(project.remote ?? project.folder, 'codex');
         const submitted = typeof values.initialPrompt === 'string';
-        if (submitted)
-            await submitCloudInitialPrompt(ctx, c, values.initialPrompt, created.workspace.key);
+        const task = await startCloudTask(ctx, c, created.workspace.key, submitted ? values.initialPrompt : undefined);
+        new AgentStateStore(ctx.store.dir).save(project.remote ?? project.folder, 'codex');
         patch(c.id, { state: 'active', submitted, prompt: undefined });
         await output(ctx, c, task, submitted, choice);
         return 0;
@@ -305,6 +311,8 @@ export async function openCodexConversation(ctx, c, history) {
         if (task.state !== 'canceled')
             task = await ctx.cloud().codex.waitTask(c.id, { timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal });
     }
+    if (task.state === 'attention' && task.next_attempt_at === null)
+        throw new CodexAdmissionStoppedError(task);
     if (task.state === 'canceled')
         throw new UsageError('This conversation’s Codex executor was removed. Start a new Cloud conversation; its saved branch and history remain available.');
     if (task.state !== 'active' || !task.thread_id)
@@ -325,10 +333,7 @@ export async function resumeCloudStartup(ctx, c) {
         const ws = await conversationWorkspace(ctx, c);
         // The same seed the start began: its own captured revision (never a newer checkout), or the copy seed.
         await seedConversation(ctx, c, ws, local.folder);
-        await ctx.cloud().codex.admit(c.id, { idempotencyKey: `codex-${c.id}`, signal: ctx.signal });
-        const task = await ctx.cloud().codex.waitTask(c.id, { timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal });
-        if (start.prompt !== undefined && !start.submitted)
-            await submitCloudInitialPrompt(ctx, c, start.prompt, ws.key);
+        const task = await startCloudTask(ctx, c, ws.key, start.submitted ? undefined : start.prompt);
         new AgentStateStore(ctx.store.dir).update(doc => {
             const records = doc.conversations;
             if (records[c.id]?.cloud_start)

package/dist/commands.js

@@ -1425,6 +1425,14 @@ export const KEY_HANDLERS = {
         out(ctx, `wrote ${r.bytes_written} bytes to ${r.path}${r.sha256 ? ` (sha256 ${r.sha256})` : ''}${tree !== null ? `, tree revision ${tree}` : ''}\n`, tree !== null ? { ...r, tree_revision: tree } : r);
         return 0;
     },
+    async 'files delete'(ctx, values, [ref, path]) {
+        const ws = await resolveWorkspace(ctx, ref);
+        const ifRev = ifRevision(values);
+        fileFirstOnly(ws, ifRev !== undefined ? ['--if-revision'] : []);
+        await cellOf(ctx, ws).files.remove(path, { recursive: values.recursive === true, ...(ifRev !== undefined ? { ifTreeRevision: ifRev } : {}) });
+        out(ctx, `deleted ${path}\n`, { path, removed: true });
+        return 0;
+    },
     async 'files ls'(ctx, values, [ref, path]) {
         const limitText = str(values.limit);
         const ws = await resolveWorkspace(ctx, ref);

package/dist/conversation-commands.d.ts

@@ -1,5 +1,5 @@
 import type { Ctx, Handler } from './commands.js';
-import type { CellClient, ConversationPermission, ListeningPort, MessageAttachment, PermissionDecision } from '@shardflux/sdk';
+import type { CellClient, ConversationPermission, ListeningPort, MessageAttachment, MessageDelivery, PermissionDecision } from '@shardflux/sdk';
 export declare function conversationClient(ctx: Ctx): import("@shardflux/sdk").Shardflux | import("@shardflux/sdk").ShardfluxAccount;
 /** Why a conversation needs you, as one line of at most `max` characters; undefined in other states (0.18.0+). */
 export declare function questionLine(c: {
@@ -17,6 +17,10 @@ export declare function displayTitle(c: {
  * keeps its file name in the conversation's computer.
  */
 export declare function readAttachments(paths: readonly string[]): Promise<MessageAttachment[]>;
+/** How long `conversations send --wait` waits for the agent to have the message (0.27.0+). */
+export declare const SEND_WAIT_MS = 60000;
+/** What happened to a sent message, as `conversations send --wait` prints it (0.27.0+). */
+export declare function deliveryLine(d: MessageDelivery): string;
 /** A permission request's command, path or URL as one line of at most `max` characters: its first line (0.25.0+). */
 export declare function detailLine(detail: string, max?: number): string;
 /** One permission request as a list row (0.25.0+): id, state, title, detail, and the decision once answered. */

package/dist/conversation-commands.js

@@ -2,10 +2,10 @@ import { randomUUID } from 'node:crypto';
 import { open } from 'node:fs/promises';
 import { basename } from 'node:path';
 import { out, str, strs } from "./commands.js";
-import { CodedError, UsageError } from "./errors.js";
-import { MAX_ATTACHMENT_BYTES, MAX_ATTACHMENTS, PtyConnection, planAttachments } from '@shardflux/sdk';
+import { CodedError, EXIT, UsageError } from "./errors.js";
+import { MAX_ATTACHMENT_BYTES, MAX_ATTACHMENTS, MAX_MARK_IDS, PtyConnection, planAttachments } from '@shardflux/sdk';
 import { FilesMirror, humanBytes, listMirrorConversations, workspaceHub } from "./files-mirror.js";
-import { modelChoice } from "./agent-models.js";
+import { liveModels, modelChoice } from "./agent-models.js";
 import { storedTitlePrefix } from "./client-settings.js";
 import { PtyOutputCursor, passiveUnavailable, sleepingAttach } from "./agent-terminal.js";
 import { progress } from "./progress.js";
@@ -83,6 +83,16 @@ function checkMessage(text, files) {
     }
 }
 const sentLines = (r) => `${r.restored ? 'Restored\n' : ''}${(r.files ?? []).map(f => `Attached ${f.path}\n`).join('')}Message sent (${r.seq}).\n`;
+/** How long `conversations send --wait` waits for the agent to have the message (0.27.0+). */
+export const SEND_WAIT_MS = 60_000;
+/** What happened to a sent message, as `conversations send --wait` prints it (0.27.0+). */
+export function deliveryLine(d) {
+    if (d.state === 'pending')
+        return 'Not delivered yet.';
+    if (d.state === 'uncertain')
+        return 'Delivery not confirmed yet: check the conversation before sending it again.';
+    return d.steered === true ? 'Steered into the running turn.' : d.steered === false ? 'Started the next turn.' : 'Delivered to the agent.';
+}
 /** A permission request's command, path or URL as one line of at most `max` characters: its first line (0.25.0+). */
 export function detailLine(detail, max = 80) {
     const line = detail.split('\n').find(l => l.trim())?.replace(/\s+/g, ' ').trim() ?? '';
@@ -191,6 +201,29 @@ export async function watchTerminal(ctx, cell, ptyId) {
             ctx.io.stdout.write('\x1b[0m\x1b[?25h\r\n');
     }
 }
+/** A conversation id as the marks commands take it: conv_ and 26 letters a-z and digits 2-7 (0.28.0+). */
+const CONVERSATION_ID = /^conv_[a-z2-7]{26}$/;
+/** What `conversations archive`, `unarchive` and `seen` print before each conversation they marked (0.28.0+). */
+const MARKED = { archive: 'Archived', unarchive: 'Unarchived', seen: 'Marked seen' };
+/**
+ * Your own marks (0.28.0+, SDK 0.30.0), the same on every device: every id in one request, each once, checked before
+ * it is sent. Prints one line per conversation marked and, on stderr, "Not found: <id>" for each one skipped; --json
+ * prints the API's answer, {data, skipped}. Exit 3 when none was marked and some were skipped (not found), else 0.
+ */
+async function markConversations(ctx, kind, ids) {
+    const unique = [...new Set(ids)], invalid = unique.filter(id => !CONVERSATION_ID.test(id));
+    if (invalid.length)
+        throw new UsageError(`Not a conversation id: ${invalid.join(', ')}`, 'conversation ids look like conv_k3m5q7s2u4w6y3b5d7f2h4j6ln (shard conversations list shows them)');
+    if (unique.length > MAX_MARK_IDS)
+        throw new UsageError(`${unique.length} conversations named: one command takes up to ${MAX_MARK_IDS}.`, `run it again for the rest, ${MAX_MARK_IDS} at a time`);
+    const client = conversationClient(ctx), o = { signal: ctx.signal };
+    const r = kind === 'archive' ? await client.conversations.archive(unique, o) : kind === 'unarchive' ? await client.conversations.unarchive(unique, o) : await client.conversations.markSeen(unique, o);
+    out(ctx, r.data.map(c => `${MARKED[kind]} ${c.id}\t${displayTitle(c)}\n`).join(''), r);
+    if (!ctx.json)
+        for (const id of r.skipped)
+            ctx.io.stderr.write(`Not found: ${id}\n`);
+    return !r.data.length && r.skipped.length ? EXIT.notFound : EXIT.ok;
+}
 export const CONVERSATION_HANDLERS = {
     async 'conversations resume'(ctx, _values, [id]) { const r = await conversationClient(ctx).conversations.resume(id, { signal: ctx.signal }); out(ctx, `${displayTitle(r.conversation)}: 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; },
@@ -311,8 +344,23 @@ export const CONVERSATION_HANDLERS = {
             throw new UsageError('missing <text> for "shard conversations send"');
         if (files.length)
             checkMessage(text ?? '', files);
-        const r = await conversationClient(ctx).conversations.send(id, text ?? '', { signal: ctx.signal, ...(files.length ? { files } : {}) });
-        out(ctx, sentLines(r), r);
+        const client = conversationClient(ctx), r = await client.conversations.send(id, text ?? '', { signal: ctx.signal, ...(files.length ? { files } : {}) });
+        if (values.wait !== true) {
+            out(ctx, sentLines(r), r);
+            return 0;
+        }
+        // --wait (0.27.0+): a working agent takes it into its running turn, an idle one starts its next turn with it. The
+        // message is sent either way, so a delivery that cannot be read is said on stderr and the command still succeeds.
+        let delivery = null;
+        try {
+            delivery = await client.conversations.waitForDelivery(id, r.seq, { timeoutMs: SEND_WAIT_MS, signal: ctx.signal });
+        }
+        catch (e) {
+            if (ctx.signal.aborted)
+                throw e;
+            progress(ctx, `Where the message stands could not be read: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        out(ctx, `${sentLines(r)}${delivery ? `${deliveryLine(delivery)}\n` : ''}`, { ...r, delivery });
         return 0;
     },
     /**
@@ -326,7 +374,7 @@ export const CONVERSATION_HANDLERS = {
         const app = str(values.app) ?? 'claude';
         if (app !== 'claude' && app !== 'codex')
             throw new UsageError('Choose --app claude or codex.');
-        const choice = modelChoice(values, app);
+        const choice = modelChoice(values, app, await liveModels(ctx, values, app));
         if (prompt !== undefined && !prompt.trim())
             throw new UsageError('--prompt needs text.');
         const files = await readAttachments(strs(values.file));
@@ -378,6 +426,10 @@ export const CONVERSATION_HANDLERS = {
         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; },
+    // Your inbox, the same on every device (0.28.0+): archive, unarchive and seen, all ids in one request.
+    async 'conversations archive'(ctx, _values, ids) { return markConversations(ctx, 'archive', ids); },
+    async 'conversations unarchive'(ctx, _values, ids) { return markConversations(ctx, 'unarchive', ids); },
+    async 'conversations seen'(ctx, _values, ids) { return markConversations(ctx, 'seen', ids); },
     // Everywhere at once, its computer included (0.25.0+); refused without --yes, as every deletion is. --json: the API's answer.
     async 'conversations delete'(ctx, values, [id]) {
         if (values.yes !== true)

package/dist/conversation-terminal.js

@@ -5,7 +5,7 @@ import { randomUUID } from 'node:crypto';
 import { AgentStateStore } from "./agent-state.js";
 import { projectIdentity, projectLabels } from "./project-identity.js";
 import { createConversation, conversationName, conversationWorkspace, conversationsUnavailable, listConversations, localConversations, recordedChoice, rememberConversation, resumeConversation, restoreConversationBinding } from "./conversations.js";
-import { modelChoice } from "./agent-models.js";
+import { liveModels, modelChoice } from "./agent-models.js";
 import { terminal } from "./agent-commands.js";
 import { cloudClaudeLogin, loginClaudeInWorkspace, requireClaudeTerminal } from "./claude-cloud-login.js";
 import { syncAgentCredentials } from "./agent-credentials.js";
@@ -138,7 +138,7 @@ async function startConversation(ctx, values, [path = './', explicit], openIn) {
     if (explicit && explicit !== app)
         throw new UsageError('Choose claude or codex.');
     // Checked before a VM is allocated; the new conversation's record carries it to its guest (0.17.0+).
-    const choice = modelChoice(values, app);
+    const choice = modelChoice(values, app, await liveModels(ctx, values, app));
     if (values.resume === true) {
         // The native pickers are VM-local. C-K6's project picker must select the binding first.
         const records = localConversations(ctx);

package/dist/desktop-linux.d.ts

@@ -10,6 +10,17 @@ export interface DesktopStatus {
 }
 export declare function linuxDesktopPackage(arch?: NodeJS.Architecture): string | null;
 export declare function graphicalSession(env: NodeJS.ProcessEnv): boolean;
+/**
+ * Whether `pid` runs the app installed at `app`: the GTK tray app (shardflux-desktop) or the one Shardflux app
+ * (shardflux-desktop-bin behind its launcher). By /proc/<pid>/exe, because Chromium rewrites an Electron process's
+ * cmdline into one space-joined title; a recycled PID runs something else, and a zombie has exited.
+ */
+export declare function isAppProcess(pid: number, app: string, proc?: string): boolean;
+/**
+ * The libraries ldd could not find, named as the loader names them: the app in the package decides which it needs (the
+ * GTK tray app's WebKit and app indicator, the one app's GTK, NSS and ALSA).
+ */
+export declare function missingLibrariesMessage(ldd: string): string;
 export declare class LinuxDesktopManager {
     #private;
     readonly home: string;
@@ -20,7 +31,7 @@ export declare class LinuxDesktopManager {
         env?: NodeJS.ProcessEnv;
         exec?: typeof exec;
         spawn?: typeof spawn;
-        isProcess?: (pid: number, executable: string) => boolean;
+        isProcess?: (pid: number, app: string) => boolean;
     });
     status(dir: string): Promise<DesktopStatus>;
     packagedVersion(): string | null;

package/dist/desktop-linux.js

@@ -1,7 +1,7 @@
 import { spawn, execFile } from 'node:child_process';
 import { createRequire } from 'node:module';
-import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync, chmodSync, mkdtempSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, realpathSync, renameSync, rmSync, writeFileSync, chmodSync, mkdtempSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
 import { homedir } from 'node:os';
 import { promisify } from 'node:util';
 import { UsageError } from "./errors.js";
@@ -18,6 +18,41 @@ export function linuxDesktopPackage(arch = process.arch) {
     }
 }
 export function graphicalSession(env) { return !!(env.DISPLAY || env.WAYLAND_DISPLAY); }
+/**
+ * Whether `pid` runs the app installed at `app`: the GTK tray app (shardflux-desktop) or the one Shardflux app
+ * (shardflux-desktop-bin behind its launcher). By /proc/<pid>/exe, because Chromium rewrites an Electron process's
+ * cmdline into one space-joined title; a recycled PID runs something else, and a zombie has exited.
+ */
+export function isAppProcess(pid, app, proc = '/proc') {
+    try {
+        const exe = readlinkSync(`${proc}/${pid}/exe`).replace(/ \(deleted\)$/, '');
+        let real = app;
+        try {
+            real = realpathSync(app);
+        }
+        catch { /* not installed */ }
+        if (![app, real].includes(dirname(exe)) || !/^shardflux-desktop(-bin)?$/.test(basename(exe)))
+            return false;
+        const stat = readFileSync(`${proc}/${pid}/stat`, 'utf8');
+        if (stat.slice(stat.lastIndexOf(')') + 2).startsWith('Z'))
+            return false;
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The libraries ldd could not find, named as the loader names them: the app in the package decides which it needs (the
+ * GTK tray app's WebKit and app indicator, the one app's GTK, NSS and ALSA).
+ */
+export function missingLibrariesMessage(ldd) {
+    const missing = [...new Set([...ldd.matchAll(/^\s*(\S+)\s+=>\s+not found/gm)].map(m => m[1]))];
+    return `Shardflux needs desktop libraries this computer does not have${missing.length ? ` (${missing.join(', ')})` : ''}. Install them with your package manager, then run shard.`;
+}
+/** The Electron executable of a one-app directory (behind its launcher), else the GTK app's executable. */
+const appBinary = (dir) => existsSync(join(dir, 'shardflux-desktop-bin')) ? join(dir, 'shardflux-desktop-bin') : join(dir, 'shardflux-desktop');
 const desktopString = (text) => `"${text.replace(/(["`$\\])/g, '\\$1')}"`;
 // fnm's multishell aliases belong to the launching shell; the desktop and its autostart entry outlive it.
 function stableDesktopRuntime(runtime) {
@@ -43,15 +78,7 @@ export class LinuxDesktopManager {
         this.#env = { ...process.env, ...options.env, HOME: this.home };
         this.#exec = options.exec ?? exec;
         this.#spawn = options.spawn ?? spawn;
-        this.#isProcess = options.isProcess ?? ((pid, executable) => { try {
-            if (readFileSync(`/proc/${pid}/cmdline`, 'utf8').split('\0')[0] !== executable)
-                return false;
-            process.kill(pid, 0);
-            return true;
-        }
-        catch {
-            return false;
-        } });
+        this.#isProcess = options.isProcess ?? ((pid, app) => isAppProcess(pid, app));
     }
     #version(path) {
         try {
@@ -67,7 +94,7 @@ export class LinuxDesktopManager {
         try {
             const pid = Number(readFileSync(join(dir, 'desktop-linux.pid'), 'utf8'));
             // Recycled PIDs must never make us stop an unrelated process.
-            if (Number.isInteger(pid) && pid > 0 && this.#isProcess(pid, join(this.app, 'shardflux-desktop')))
+            if (Number.isInteger(pid) && pid > 0 && this.#isProcess(pid, this.app))
                 pids.push(pid);
         }
         catch { /* no running app */ }
@@ -84,7 +111,8 @@ export class LinuxDesktopManager {
         const entry = join(this.home, '.local/share/applications/dev.shardflux.Desktop.desktop');
         if (!existsSync(entry))
             return Promise.reject(new UsageError('Run shard menubar start first.'));
-        cpSync(entry, file);
+        // A login start shows only the tray icon (the one app reads --background; 0.27.0+).
+        writeFileSync(file, readFileSync(entry, 'utf8').replace(/^Exec=(.*)$/m, (_m, cmd) => `Exec=${cmd.includes('--background') ? cmd : `${cmd} --background`}`), { mode: 0o644 });
         return Promise.resolve();
     }
     async stop(dir) {
@@ -109,7 +137,7 @@ export class LinuxDesktopManager {
             return { result: 'current', from: before.version, to: version };
         if (before.running) {
             try {
-                const { stdout } = await this.#exec(join(this.app, 'shardflux-desktop'), ['--control', 'idle'], { env: this.#env, timeout: 5000 });
+                const { stdout } = await this.#exec(join(this.app, 'shardflux-desktop'), ['--control', 'idle'], { env: { ...this.#env, SHARDFLUX_CONFIG_DIR: dir }, timeout: 5000 });
                 if (!JSON.parse(stdout).idle)
                     return { result: 'busy', from: before.version, to: version };
             }
@@ -132,14 +160,15 @@ export class LinuxDesktopManager {
             if (existsSync(this.app) && (lstatSync(this.app).isSymbolicLink() || !current.version))
                 throw new UsageError(`Refusing to replace an unrelated directory at ${this.app}.`);
             // The loader probes every shared library before any installed copy is stopped or replaced.
-            await this.#exec('/usr/bin/ldd', [join(source, 'shardflux-desktop')], { timeout: 5_000 }).then(({ stdout }) => { if (stdout.includes('not found'))
-                throw new UsageError('The Shardflux window needs libwebkit2gtk-4.1-0 and libayatana-appindicator3-1. Install those desktop libraries, then run shard.'); });
+            await this.#exec('/usr/bin/ldd', [appBinary(source)], { timeout: 5_000 }).then(({ stdout }) => { if (stdout.includes('not found'))
+                throw new UsageError(missingLibrariesMessage(stdout)); });
             mkdirSync(dirname(this.app), { recursive: true });
             const staging = mkdtempSync(join(dirname(this.app), '.desktop-'));
             const staged = join(staging, 'app'), backup = join(staging, 'previous');
             try {
-                cpSync(source, staged, { recursive: true });
+                cpSync(source, staged, { recursive: true, verbatimSymlinks: true });
                 chmodSync(join(staged, 'shardflux-desktop'), 0o755);
+                chmodSync(appBinary(staged), 0o755);
                 if (current.running)
                     await this.stop(dir);
                 if (existsSync(this.app))
@@ -165,7 +194,7 @@ export class LinuxDesktopManager {
         writeFileSync(desktop, `[Desktop Entry]\nType=Application\nName=Shardflux\nComment=Your agents, a shortcut away\nExec=${args.map(desktopString).join(' ')}\nIcon=${join(this.app, 'ui/assets/shardflux-icon.png')}\nTerminal=false\nCategories=Development;\nStartupWMClass=dev.shardflux.Desktop\n`, { mode: 0o644 });
         const autostart = join(this.home, '.config/autostart/shardflux.desktop');
         if (existsSync(autostart))
-            cpSync(desktop, autostart);
+            await this.login(true);
         if ((await this.status(dir)).running)
             await this.#exec(join(this.app, 'shardflux-desktop'), ['--control', view], { env, timeout: 5_000 });
         else {