@shardflux/cli 0.25.0 → 0.28.0

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,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 {

package/dist/device-approvals.js

@@ -6,6 +6,8 @@ import { setTimeout as delay } from 'node:timers/promises';
 import { writePrivateFile } from "./credentials.js";
 import { UsageError } from "./errors.js";
 import { json } from "./format.js";
+import { thisComputer } from "./this-computer.js";
+import { chooseLine, MODE_LABELS, deviceActivity, readDeviceSettings, setDeviceApprovalMode } from "./device-mode.js";
 const paths = (dir, id) => {
     if (!/^[a-zA-Z0-9_-]{1,96}$/.test(id))
         throw new UsageError('Invalid device request id.');
@@ -39,12 +41,19 @@ export function answerDeviceApproval(dir, id, choice) {
         throw new UsageError('Access outside the conversation folder must be approved once.');
     writePrivateFile(join(dir, 'device-answers'), paths(dir, id).answer, JSON.stringify({ nonce: pending.nonce, choice }));
 }
+/** Config dirs whose helper printed the choose line (once per helper, not per request). */
+const toldChoice = new Set();
 /** Local user-owned files carry approvals; cloud data can never answer its own request. */
 export async function askLocalDeviceApproval(ctx, approval) {
     const file = paths(ctx.store.dir, approval.request_id), nonce = randomUUID();
     rmSync(file.answer, { force: true });
     writePrivateFile(join(ctx.store.dir, 'device-approvals'), file.pending, JSON.stringify({ ...approval, nonce, pid: process.pid }));
-    spawnSync('notify-send', ['--', 'Shardflux approval', `${approval.summary}\nReview: shard device requests`], { env: ctx.io.env, stdio: 'ignore', timeout: 2000 });
+    // Not chosen yet (device-mode.ts): one line with the exact commands; choosing one answers this request too.
+    if (approval.choose_mode && !toldChoice.has(ctx.store.dir)) {
+        toldChoice.add(ctx.store.dir);
+        ctx.io.stderr.write(`Device bridge: ${chooseLine()}\n`);
+    }
+    spawnSync('notify-send', ['--', 'Shardflux approval', `${approval.summary}\n${approval.choose_mode ? chooseLine() : 'Review: shard device requests'}`], { env: ctx.io.env, stdio: 'ignore', timeout: 2000 });
     try {
         while (!ctx.signal.aborted) {
             try {
@@ -62,10 +71,23 @@ export async function askLocalDeviceApproval(ctx, approval) {
         rmSync(file.answer, { force: true });
     }
 }
+const activityLine = (a) => `${a.at.slice(0, 16).replace('T', ' ')}  ${a.state}${a.exit_code !== undefined ? ` (exit ${a.exit_code})` : ''}  ${a.summary}${a.conversation_title ? `  · ${a.conversation_title}` : ''}\n`;
 export const DEVICE_HANDLERS = {
+    /** `shard device approvals [auto|read|ask]` (0.27.0+): how this computer answers your agents, and what ran without asking. */
+    'device approvals'(ctx, _values, [mode]) {
+        const settings = mode ? setDeviceApprovalMode(ctx.store.dir, mode, ctx.store.profile(ctx.apiUrl).session?.user?.id) : readDeviceSettings(ctx.store.dir);
+        const recent = deviceActivity(ctx.store.dir, 10);
+        if (ctx.json) {
+            ctx.io.stdout.write(json({ approvals: settings.approvals ?? null, chosen_at: settings.chosen_at ?? null, recent }));
+            return Promise.resolve(0);
+        }
+        const now = settings.approvals ? `Your agents on ${thisComputer()}: ${MODE_LABELS[settings.approvals]}.\n` : `Your agents on ${thisComputer()}: not chosen yet; each request asks.\n${chooseLine()}\n`;
+        ctx.io.stdout.write(now + (recent.length ? `Ran without asking:\n${recent.map(activityLine).join('')}` : ''));
+        return Promise.resolve(0);
+    },
     'device requests'(ctx) {
         const requests = pendingDeviceApprovals(ctx.store.dir);
-        ctx.io.stdout.write(ctx.json ? json({ requests }) : requests.length ? requests.map(r => `${r.request_id}: ${r.summary}\n  Project: ${r.project_name ?? r.project_id}; conversation: ${r.conversation_title ?? r.conversation_id}\n  Local: ${r.local_path ?? '(none)'}; remote: ${r.remote_path ?? '(none)'}${r.argv ? `\n  Command: ${JSON.stringify(r.argv)}` : ''}${r.local_port ? `\n  Ports: ${r.local_port} → ${r.remote_port}` : ''}${r.repo_remote ? `\n  Repository: ${r.repo_remote}` : ''}${r.brief ? `\n  First message: ${r.brief.split('\n')[0].slice(0, 200)}` : ''}\n  shard device approve ${r.request_id}${r.scope === 'folder' ? ` [--always: for ${r.folder}]` : ''} | shard device deny ${r.request_id}\n`).join('') : 'No device requests waiting for approval.\n');
+        ctx.io.stdout.write(ctx.json ? json({ requests }) : requests.length ? requests.map(r => `${r.request_id}: ${r.summary}\n  Project: ${r.project_name ?? r.project_id}; conversation: ${r.conversation_title ?? r.conversation_id}\n  Local: ${r.local_path ?? '(none)'}; remote: ${r.remote_path ?? '(none)'}${r.argv ? `\n  Command: ${JSON.stringify(r.argv)}` : ''}${r.local_port ? `\n  Ports: ${r.local_port} → ${r.remote_port}` : ''}${r.repo_remote ? `\n  Repository: ${r.repo_remote}` : ''}${r.brief ? `\n  First message: ${r.brief.split('\n')[0].slice(0, 200)}` : ''}\n  shard device approve ${r.request_id}${r.scope === 'folder' ? ` [--always: for ${r.folder}]` : ''} | shard device deny ${r.request_id}\n`).join('') + (requests.some(r => r.choose_mode) ? `${chooseLine()}\n` : '') : 'No device requests waiting for approval.\n');
         return Promise.resolve(0);
     },
     ...Object.fromEntries(['approve', 'deny'].map(action => [`device ${action}`, (ctx, values, [id]) => {

package/dist/device-bridge.d.ts

@@ -62,8 +62,15 @@ export interface DeviceApproval {
     brief?: string;
     /** dir_list: how many levels below the folder are listed. */
     depth?: number;
+    /**
+     * 0.27.0+: this person has not chosen how this computer answers their agents (device-mode.ts). A surface that knows
+     * it asks that first ("Allow everything" / "Ask each time", saved with `shard device approvals auto|ask`): once the
+     * mode lets this request run, the helper takes it by itself and this approval goes away; with "Ask each time" the
+     * request is then answered as usual. A surface that predates it shows the approval as before.
+     */
+    choose_mode?: true;
 }
-type Result = {
+export type Result = {
     state: 'approved' | 'denied' | 'running' | 'done' | 'failed';
     exit_code?: number;
     stdout_b64?: string;
@@ -72,6 +79,12 @@ type Result = {
     dir?: DirListing;
     project?: LinkedProject;
 };
+/**
+ * Posts a request's answer. An API before a linked folder's start point (train 47) refuses a link's commit and branch
+ * (422 validation_failed): the link is done, so it is posted again without them (staging 2026-10-17: the answer was
+ * refused and the request read as failed).
+ */
+export declare function postResult(post: (answer: Result, again: boolean) => Promise<void>, result: Result): Promise<void>;
 /** Resolve existing ancestors even before the conversation worktree is created. */
 export declare function devicePath(root: string, requested?: string): {
     path: string;
@@ -105,10 +118,15 @@ export declare function folderApproval(r: DeviceRequest, c: Conversation, target
 export declare function tryLocallyAction(r: DeviceRequest): 'start' | 'stop' | null;
 export declare function ensureConversationWorktree(ctx: Ctx, c: Conversation, folder: string, ws?: Workspace): Promise<string>;
 export declare function deviceExec(argv: string[], cwd: string, timeoutSeconds?: number, signal?: AbortSignal): Promise<Result>;
+export type DeviceAsk = (approval: DeviceApproval, signal?: AbortSignal) => Promise<DeviceChoice>;
 export declare class DeviceExecutor {
     #private;
-    constructor(ctx: Ctx, ask: (approval: DeviceApproval) => Promise<DeviceChoice>, deviceId: string);
-    result(r: DeviceRequest, result: Result): Promise<void>;
+    constructor(ctx: Ctx, ask: DeviceAsk, deviceId: string);
+    /** A new device id for a new sign-in (device-helper.ts): requests for the old one are no longer this device's. */
+    set deviceId(id: string);
+    get deviceId(): string;
+    /** `again`: a second answer of the same state with another body (its own idempotency key). */
+    result(r: DeviceRequest, result: Result, again?: string): Promise<void>;
     execute(r: DeviceRequest): Promise<void>;
     reap(): Promise<void>;
     close(): Promise<void>;
@@ -131,4 +149,3 @@ export declare function askConnectedAcp(dir: string, approval: DeviceApproval, s
  */
 export declare function approverSocket(dir: string): string;
 export declare function askDeviceApprover(dir: string, approval: DeviceApproval, signal: AbortSignal): Promise<DeviceChoice | null>;
-export {};