@shardflux/cli 0.24.1 → 0.28.0

package/dist/board-commands.js

@@ -3,6 +3,7 @@ import { detailLine, pickAnswers } from "./conversation-commands.js";
 import { NotFoundError, UsageError } from "./errors.js";
 import { time } from "./format.js";
 import { progress } from "./progress.js";
+import { landDeps, landTask, landedText } from "./land.js";
 const BUCKETS = ['now', 'next', 'later'];
 const BUCKET_TITLES = { now: 'Now', next: 'Next', later: 'Later' };
 const MODES = ['ask', 'routine', 'trusted'];
@@ -16,18 +17,26 @@ const oneLine = (s, max) => {
 export function taskLabel(t, max = 80) {
     return oneLine(t.title?.trim() || t.text, max);
 }
+/** Why a task waits to start, or what a working one does now: "Getting its computer ready", "Fixing the login cookie". */
+function stateNote(t, max) {
+    const note = t.waiting?.message.trim() || (t.state === 'working' ? t.activity?.trim() : '') || '';
+    return note ? ` (${oneLine(note, max)})` : '';
+}
 /**
- * One task as `shard board` lists it: id, state (with why it waits to start: "queued (Claude usage resets 15:00)"),
- * title or words (a follow-up ↳, a suggestion marked), project.
+ * One task as `shard board` lists it: id, state (with why it waits to start, "queued (Getting its computer ready)", or
+ * what it does now, "working (Fixing the login cookie)"), title or words (a follow-up ↳, a suggestion marked), project.
  */
 export function taskLine(t) {
-    const state = `${t.state}${t.waiting?.message.trim() ? ` (${oneLine(t.waiting.message, 60)})` : ''}`;
+    const state = `${t.state}${stateNote(t, 60)}`;
     const label = `${t.parent_task_id ? '↳ ' : ''}${taskLabel(t)}${t.suggested ? ' (suggested)' : ''}`;
     return `${t.id}\t${state}\t${label}\t${t.project_id}${t.home ? ' (home)' : ''}`;
 }
-/** One item that waits on you: its id, what is asked, then the command, the suggested answers or the branch behind it. */
+/**
+ * One item that waits on you: its id, what is asked, then the command, the suggested answers or the branch behind it. A
+ * request your orchestrator made to your computer while it was offline reads "Waiting for your computer: list ~/code".
+ */
 export function needsLine(n) {
-    const detail = n.permission ? detailLine(n.permission.detail) : n.options?.length ? n.options.join(' / ') : n.land ? n.land.branch : '';
+    const detail = n.permission ? detailLine(n.permission.detail) : n.options?.length ? n.options.join(' / ') : n.land ? n.land.branch : n.device ? 'cancel drops it' : '';
     return `${n.id}\t${oneLine(n.ask, 100)}${detail ? `\t${detail}` : ''}`;
 }
 /** A sealed report as --follow prints it: id, milestone, title, then its evidence labels. */
@@ -106,28 +115,30 @@ const evidenceText = (e) => {
     const behind = e.detail ?? e.path;
     return behind ? `${e.label} (${detailLine(behind, 60)})` : e.label;
 };
-/** `shard task show`: the task, its plan and conversations, then every report oldest first with its evidence. */
+/** `shard task show`: the task, its plan and conversations, then every report oldest first with its evidence. Every
+ *  title, step and outcome prints whole (0.27.0+), however long the agent wrote it; the terminal wraps it. */
 export function taskDetailText(d) {
     const t = d.task;
+    const whole = (s) => oneLine(s, Infinity);
     const titled = Boolean(t.title?.trim());
-    const lines = [titled ? oneLine(t.title, 200) : oneLine(t.text.split('\n').find((l) => l.trim()) ?? t.text, 200)];
-    lines.push([`${t.state}${t.waiting?.message.trim() ? ` (${oneLine(t.waiting.message, 120)})` : ''}`, t.bucket, `${t.project_id}${t.home ? ' (home)' : ''}`, ...(t.suggested ? ['suggested'] : []), ...(t.deleted_at ? ['deleted'] : t.cleared_at ? ['cleared'] : [])].join('\t'));
+    const lines = [titled ? whole(t.title) : whole(t.text.split('\n').find((l) => l.trim()) ?? t.text)];
+    lines.push([`${t.state}${stateNote(t, 120)}`, t.bucket, `${t.project_id}${t.home ? ' (home)' : ''}`, ...(t.suggested ? ['suggested'] : []), ...(t.deleted_at ? ['deleted'] : t.cleared_at ? ['cleared'] : [])].join('\t'));
     // Your words exactly, when the first line does not already show them whole.
     if (titled || t.text.trim() !== lines[0])
         lines.push('', t.text);
     if (t.plan) {
         lines.push('', `Plan: ${t.plan.summary}`);
         for (const s of t.plan.steps)
-            lines.push(`  ${s.id}\t${s.state}\t${oneLine(s.text, 100)}${s.evidence.length ? `\t${s.evidence.join(', ')}` : ''}`);
+            lines.push(`  ${s.id}\t${s.state}\t${whole(s.text)}${s.now?.trim() ? `\t(${oneLine(s.now, 80)})` : ''}${s.evidence.length ? `\t${s.evidence.join(', ')}` : ''}`);
     }
     if (t.conversations.length)
         lines.push('', `Conversations: ${t.conversations.map((c) => `${c.id} (${c.role}${c.step_id ? ` ${c.step_id}` : ''})`).join(', ')}`);
     if (d.reports.length) {
         lines.push('', 'Reports');
         for (const r of d.reports) {
-            lines.push(`${r.id}\t${r.milestone}\t${time(r.sealed_at)}\t${oneLine(r.title, 120)}`);
+            lines.push(`${r.id}\t${r.milestone}\t${time(r.sealed_at)}\t${whole(r.title)}`);
             if (r.outcome.trim())
-                lines.push(`  ${oneLine(r.outcome, 200)}`);
+                lines.push(`  ${whole(r.outcome)}`);
             if (r.options?.length)
                 lines.push(`  Options: ${r.options.join(' / ')}`);
             if (r.evidence.length)
@@ -155,13 +166,13 @@ function orderOf(values) {
     return first ? null : after;
 }
 // ---- needs you -------------------------------------------------------------------------------
-const KINDS = { perm: 'permission', cq: 'question', ask: 'question', cred: 'credential', land: 'land', prune: 'prune' };
-/** An item's kind from its id (perm_, cq_, ask_, cred_, land_, prune_); undefined for another id. */
+const KINDS = { perm: 'permission', cq: 'question', ask: 'question', oq: 'question', cred: 'credential', land: 'land', prune: 'prune', dev: 'device' };
+/** An item's kind from its id (perm_, cq_, ask_, oq_, cred_, land_, prune_, dev_); undefined for another id. */
 export function itemKind(id) {
     return KINDS[id.slice(0, Math.max(0, id.indexOf('_')))];
 }
-/** The answer words: allow, always and deny (or the API's names), land, keep and discard. */
-const WORDS = { allow: 'allow_once', allow_once: 'allow_once', always: 'allow_always', allow_always: 'allow_always', deny: 'deny', land: 'land', keep: 'keep', discard: 'discard' };
+/** The answer words: allow, always and deny (or the API's names), land, keep, discard and cancel. */
+const WORDS = { allow: 'allow_once', allow_once: 'allow_once', always: 'allow_always', allow_always: 'allow_always', deny: 'deny', land: 'land', keep: 'keep', discard: 'discard', cancel: 'cancel' };
 /** Whether the answer needs the item itself: the questions of a permission request, every task of a prune prompt. */
 export const answerNeedsItem = (id, a) => a.picks.length > 0 || (itemKind(id) === 'prune' && a.word?.toLowerCase() === 'keep');
 /**
@@ -208,6 +219,11 @@ export function needsAnswer(id, a, item) {
             if (decision !== 'deny')
                 throw new UsageError('Provide the value through the credential request, sealed for its computer; deny declines it here.');
             return { decision };
+        case 'device':
+            only([], 'It runs when your computer is back (the Shardflux app open); cancel drops it.');
+            if (decision !== 'cancel')
+                throw new UsageError('It runs when your computer is back (the Shardflux app open); cancel drops it.');
+            return { decision };
         case 'land':
             only([], 'Choose land, keep or discard.');
             if (decision !== 'land' && decision !== 'keep' && decision !== 'discard')
@@ -242,7 +258,7 @@ export function needsAnswer(id, a, item) {
         }
     }
 }
-const ANSWERED = { allow_once: 'Allowed once', allow_always: 'Always allowed', deny: 'Denied', land: 'Landing', keep: 'Kept', discard: 'Discarded' };
+const ANSWERED = { allow_once: 'Allowed once', allow_always: 'Always allowed', deny: 'Denied', land: 'Landing', keep: 'Kept', discard: 'Discarded', cancel: 'Canceled' };
 /** What an answer did, in one line. */
 export function answeredText(r, a) {
     const item = r.item;
@@ -332,6 +348,11 @@ export const BOARD_HANDLERS = {
         out(ctx, `Steered: ${taskLabel(task)}\n`, { task });
         return 0;
     },
+    async 'task land'(ctx, values, [id]) {
+        const o = await landTask(landDeps(ctx), id, { path: str(values.path) });
+        out(ctx, landedText(o), o);
+        return 0;
+    },
     async 'task clear-done'(ctx, values) {
         const cleared = await boardClient(ctx).tasks.clearDone(projectScope(values), { signal: ctx.signal });
         out(ctx, cleared.length ? `Cleared ${cleared.length} finished task${cleared.length === 1 ? '' : 's'}.\n` : 'No finished tasks to clear.\n', { cleared });
@@ -345,6 +366,12 @@ export const BOARD_HANDLERS = {
     async 'needs-you answer'(ctx, values, [id, word]) {
         const input = { word, text: str(values.text), picks: strs(values.pick), keep: strs(values.keep), everywhere: values.everywhere === true };
         const cloud = boardClient(ctx);
+        // Land merges here (shard task land) and records itself after; the board only takes keep and discard.
+        if (itemKind(id) === 'land' && word?.toLowerCase() === 'land') {
+            const o = await landTask(landDeps(ctx), id.replace(/^land_/, ''), {});
+            out(ctx, landedText(o), o);
+            return 0;
+        }
         // Checked first, so a wrong combination is a usage error before any request.
         let answer = needsAnswer(id, input);
         if (answerNeedsItem(id, input)) {

package/dist/brain-commands.d.ts

@@ -0,0 +1,2 @@
+import type { Handler } from './commands.js';
+export declare const BRAIN_HANDLERS: Record<string, Handler>;

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/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

@@ -5,7 +5,7 @@ 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;
@@ -325,10 +331,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,13 +2,14 @@ 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";
+import { landConversation, landDeps, landedText } from "./land.js";
 import { UUID } from "./args.js";
 import { findOrg } from "./account-scope.js";
 export function conversationClient(ctx) {
@@ -82,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() ?? '';
@@ -190,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; },
@@ -224,8 +258,9 @@ export const CONVERSATION_HANDLERS = {
         const { client, organizationId } = await listScope(ctx, values);
         let cursor = str(values.cursor);
         for await (const c of client.conversations.watch({ projectId: str(values.project), organizationId, cursor, signal: ctx.signal, onCursor: next => { cursor = next; } })) {
-            const q = questionLine(c);
-            ctx.io.stdout.write(ctx.json ? JSON.stringify({ conversation: c, cursor }) + '\n' : `${c.id}\t${displayTitle(c)}\t${c.state}${q ? `\t${q}` : ''}\n`);
+            // A deleted conversation comes once, its content cleared: its line says deleted (0.25.0+).
+            const q = questionLine(c), line = c.deleted_at ? `${c.id}\tDeleted conversation\tdeleted` : `${c.id}\t${displayTitle(c)}\t${c.state}${q ? `\t${q}` : ''}`;
+            ctx.io.stdout.write(ctx.json ? JSON.stringify({ conversation: c, cursor }) + '\n' : `${line}\n`);
         }
         return 0;
     },
@@ -309,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;
     },
     /**
@@ -324,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));
@@ -360,6 +410,12 @@ export const CONVERSATION_HANDLERS = {
     async 'conversations land'(ctx, values, [id, action]) {
         if (!['merge', 'pr', 'keep', 'discard'].includes(action))
             throw new UsageError('Choose merge, pr, keep or discard.');
+        // merge lands for real (land.ts) and records only after the commit is in the branch; the others record a decision.
+        if (action === 'merge') {
+            const o = await landConversation(landDeps(ctx), id, { path: str(values.path) });
+            out(ctx, landedText(o), o);
+            return 0;
+        }
         const r = await conversationClient(ctx).conversations.land(id, action, { into: str(values.into), signal: ctx.signal });
         out(ctx, `${displayTitle(r)}: ${r.landed.how}\n`, r);
         return 0;
@@ -370,4 +426,16 @@ 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)
+            throw new UsageError('refusing to delete without --yes (the conversation, its computer, messages, transcript and branch are deleted everywhere)');
+        const r = await conversationClient(ctx).conversations.delete(id, { signal: ctx.signal });
+        out(ctx, `Deleted: ${r.id}\n`, r);
+        return 0;
+    },
 };

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/conversations.d.ts

@@ -17,7 +17,8 @@ export interface Conversation {
     worktree_path: string;
     branch: string;
     base_commit: string;
-    state: 'working' | 'needs_you' | 'unresolved' | 'done' | 'archived';
+    /** `deleted`: the one feed delivery of a deleted conversation (0.25.0+). */
+    state: 'working' | 'needs_you' | 'unresolved' | 'done' | 'archived' | 'deleted';
     created_at: string;
     ended_at: string | null;
     landed?: {

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;