@shardflux/cli 0.24.1 → 0.28.0

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 {};

package/dist/device-bridge.js

@@ -16,6 +16,29 @@ import { withTargetLock } from "./target-lock.js";
 import { checkConversationWorktree, rememberConversationWorktree } from "./conversation-worktree.js";
 import { yourComputer } from "./this-computer.js";
 import { canonicalDevicePath, deviceHome, displayPath, expandDevicePath, FOLDER_KINDS, isDevicePath, linkLocalProject, listDeviceDir } from "./device-folders.js";
+import { ownConversation } from "./agent-config-return.js";
+import { deviceApprovalMode, recordDeviceActivity, runsWithoutAsking } from "./device-mode.js";
+import { setTimeout as delay } from 'node:timers/promises';
+/**
+ * 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 async function postResult(post, result) {
+    try {
+        await post(result, false);
+    }
+    catch (e) {
+        const project = result.project, status = e.status, code = e.code;
+        if (!project?.commit || !(status === 400 || status === 422 || code === 'validation_failed'))
+            throw e;
+        const older = { ...project };
+        delete older.commit;
+        delete older.branch;
+        // Another body, so its own idempotency key.
+        await post({ ...result, project: older }, true);
+    }
+}
 const LIMIT = 256 << 20, OUTPUT = (192 << 10) - 128;
 const inside = (root, target) => target === root || target.startsWith(root + sep);
 /**
@@ -203,9 +226,82 @@ export class DeviceExecutor {
     #ask;
     #deviceId;
     #handles = new Map();
+    /** Requests that run without asking (device-mode.ts), until their outcome is recorded. */
+    #auto = new Map();
+    #identity = { at: 0 };
     constructor(ctx, ask, deviceId) { this.#ctx = ctx; this.#ask = ask; this.#deviceId = deviceId; }
-    async result(r, result) {
-        await conversationClient(this.#ctx).deviceRequests.result(safeId(r.id), result, { idempotencyKey: `${this.#deviceId}:${r.id}:${result.state}`, signal: this.#ctx.signal });
+    /** 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) { this.#deviceId = id; this.#identity = { at: 0 }; }
+    get deviceId() { return this.#deviceId; }
+    /** `again`: a second answer of the same state with another body (its own idempotency key). */
+    async result(r, result, again = '') {
+        // How a request that ran without asking ended is kept here first: it ran on this computer whether or not the
+        // answer reaches the API (a stopped helper, a network error).
+        const auto = this.#auto.get(r.id);
+        if (auto && result.state !== 'approved' && result.state !== 'running') {
+            this.#auto.delete(r.id);
+            recordDeviceActivity(this.#ctx.store.dir, { ...auto, at: new Date().toISOString(), state: result.state, ...(result.exit_code !== undefined ? { exit_code: result.exit_code } : {}) });
+        }
+        await conversationClient(this.#ctx).deviceRequests.result(safeId(r.id), result, { idempotencyKey: `${this.#deviceId}:${r.id}:${result.state}${again}`, signal: this.#ctx.signal });
+    }
+    /** This computer's person (the signed-in user, or who created its API key), checked every 10 minutes. */
+    async #me() {
+        if (Date.now() - this.#identity.at < 10 * 60_000)
+            return this.#identity.userId;
+        let userId = this.#ctx.store.profile(this.#ctx.apiUrl).session?.user?.id;
+        if (!userId) {
+            try {
+                const me = await conversationClient(this.#ctx).me();
+                userId = me.user?.id ?? me.api_key?.created_by_user_id ?? undefined;
+            }
+            catch { /* unknown: only conversations started here are this person's */ }
+        }
+        this.#identity = { at: Date.now(), ...(userId ? { userId } : {}) };
+        return userId;
+    }
+    /**
+     * Allow once by a grant, by this person's approval mode (device-mode.ts), or by asking. Only this person's own
+     * agents run without asking. Until they choose a mode, their first request asks for it (`choose_mode`), and a mode
+     * chosen while a request waits (the prompt, Settings, `shard device approvals`) takes the request by itself.
+     */
+    async #decide(r, c, approval, granted) {
+        if (granted)
+            return 'once';
+        const dir = this.#ctx.store.dir, me = await this.#me();
+        const mine = ownConversation(c, localConversations(this.#ctx), me);
+        const mode = deviceApprovalMode(dir, me);
+        const auto = (m) => {
+            this.#auto.set(r.id, { at: new Date().toISOString(), request_id: r.id, conversation_id: c.id, kind: r.kind, summary: approval.summary, mode: m, state: 'running',
+                ...(approval.conversation_title ? { conversation_title: approval.conversation_title } : {}), ...(approval.project_name ? { project_name: approval.project_name } : {}),
+                ...(approval.argv ? { argv: approval.argv } : {}), ...(approval.local_path ? { local_path: approval.local_path } : {}) });
+            recordDeviceActivity(dir, this.#auto.get(r.id));
+            return 'once';
+        };
+        if (mine && mode && runsWithoutAsking(mode, r.kind))
+            return auto(mode);
+        if (!mine)
+            return this.#ask(approval);
+        const stop = new AbortController();
+        let chosen;
+        const watch = (async () => {
+            while (!stop.signal.aborted) {
+                await delay(400, undefined, { signal: stop.signal }).catch(() => undefined);
+                const now = deviceApprovalMode(dir, me);
+                if (!stop.signal.aborted && now && runsWithoutAsking(now, r.kind)) {
+                    chosen = now;
+                    stop.abort();
+                }
+            }
+        })();
+        try {
+            const choice = await this.#ask(mode ? approval : { ...approval, choose_mode: true }, stop.signal).catch((e) => { if (chosen)
+                return 'once'; throw e; });
+            return chosen ? auto(chosen) : choice;
+        }
+        finally {
+            stop.abort();
+            await watch;
+        }
     }
     async execute(r) {
         const ctx = this.#ctx;
@@ -218,8 +314,10 @@ export class DeviceExecutor {
         const matching = Object.values(records).filter(record => record.project_id === r.project_id);
         const folders = new Set(matching.map(record => record.folder));
         const record = records[r.conversation_id] ?? (folders.size === 1 ? matching[0] : undefined);
+        // No folder of this conversation on this computer: a home conversation's command (an orchestrator thread asking the
+        // person's computer) runs in their home folder once they allow it; anything else is answered, never left waiting.
         if (!record || record.project_id !== r.project_id)
-            return; // No inferred local path for unknown projects.
+            return this.#unplaced(r);
         let c = await getConversation(ctx, r.conversation_id);
         if (c.project_id !== r.project_id)
             throw new Error('Device request project changed.');
@@ -227,7 +325,7 @@ export class DeviceExecutor {
         const requested = r.exec?.cwd_relative ?? r.files?.local_path_relative ?? '.';
         const target = devicePath(planned.path, requested), grants = new DeviceGrants(ctx.store.dir);
         target.outside ||= planned.outside;
-        const choice = grants.allows(ctx.apiUrl, r.project_id, record.folder, r.kind, target.outside) ? 'once' : await this.#ask(deviceApproval(r, c, target, record.folder));
+        const choice = await this.#decide(r, c, deviceApproval(r, c, target, record.folder), grants.allows(ctx.apiUrl, r.project_id, record.folder, r.kind, target.outside));
         if (choice === 'deny') {
             await this.result(r, { state: 'denied' });
             return;
@@ -331,6 +429,74 @@ export class DeviceExecutor {
                 ws?.cell().close();
         }
     }
+    /**
+     * A request whose conversation has no folder on this device (0.27.0+). A home conversation's exec runs in the home
+     * folder, or the ~/ or absolute directory it names, after the person allows this one request (never Always: commands
+     * never run under a grant). Everything else is refused with the reason, so its agent hears it instead of waiting forever.
+     */
+    async #unplaced(r) {
+        const ctx = this.#ctx, home = deviceHome(ctx), say = (state, message) => this.result(r, { state, stderr_b64: Buffer.from(message).toString('base64') });
+        let c;
+        try {
+            c = await getConversation(ctx, r.conversation_id);
+            if (c.project_id !== r.project_id)
+                throw new Error('Device request project changed.');
+        }
+        catch (e) {
+            if (ctx.signal.aborted)
+                return;
+            await say('denied', e instanceof Error ? e.message : String(e));
+            return;
+        }
+        if (archived(c)) {
+            await say('denied', 'The conversation has ended.');
+            return;
+        }
+        if (r.kind !== 'exec' || !r.exec || c.home !== true) {
+            await say('denied', `This conversation has no folder on ${yourComputer()}: commands and file moves need its folder here (open the conversation on this computer), or a ~/ path for a file.`);
+            return;
+        }
+        let target;
+        try {
+            const requested = r.exec.cwd_relative && r.exec.cwd_relative !== '.' ? r.exec.cwd_relative : '~';
+            target = canonicalDevicePath(expandDevicePath(isDevicePath(requested) ? requested : `~/${requested}`, home));
+        }
+        catch (e) {
+            await say('denied', e instanceof Error ? e.message : String(e));
+            return;
+        }
+        const approval = { ...deviceApproval(r, c, { path: target, outside: true }, home),
+            summary: `Run on ${yourComputer()}: ${r.exec.argv.join(' ')} · in ${displayPath(target, home)}` };
+        let choice;
+        try {
+            choice = await this.#decide(r, c, approval, false);
+        }
+        catch (e) {
+            if (ctx.signal.aborted)
+                return;
+            await say('denied', e instanceof Error ? e.message : String(e));
+            return;
+        }
+        if (ctx.signal.aborted)
+            return;
+        if (choice !== 'once') {
+            await this.result(r, { state: 'denied' });
+            return;
+        }
+        const current = await getConversation(ctx, r.conversation_id).catch(() => undefined);
+        if (!current || current.project_id !== c.project_id || archived(current)) {
+            await say('denied', 'The conversation changed or ended during device approval.');
+            return;
+        }
+        await this.result(r, { state: 'approved' });
+        await this.result(r, { state: 'running' });
+        try {
+            await this.result(r, await deviceExec(r.exec.argv, target, r.exec.timeout_seconds, ctx.signal));
+        }
+        catch (e) {
+            await say('failed', e instanceof Error ? e.message : String(e));
+        }
+    }
     /**
      * A folder anywhere on this device (device-folders.ts). Every outcome is answered, so a request is never asked twice:
      * denied before it was approved, failed after.
@@ -371,7 +537,7 @@ export class DeviceExecutor {
         const grants = new DeviceGrants(ctx.store.dir);
         let choice;
         try {
-            choice = grants.allowsFolder(ctx.apiUrl, target, r.kind) ? 'once' : await this.#ask(folderApproval(r, c, target, folder, home, remote));
+            choice = await this.#decide(r, c, folderApproval(r, c, target, folder, home, remote), grants.allowsFolder(ctx.apiUrl, target, r.kind));
         }
         catch (e) {
             if (ctx.signal.aborted)
@@ -412,7 +578,7 @@ export class DeviceExecutor {
             if (r.kind === 'dir_list')
                 result = { state: 'done', dir: await listDeviceDir(target, r.dir ?? {}, ctx.signal) };
             else if (r.kind === 'project_link')
-                result = { state: 'done', project: await linkLocalProject(ctx, target, { ...(r.link?.brief ? { brief: r.link.brief } : {}), harness: r.link?.harness ?? current.harness, projectId: current.project_id }) };
+                result = { state: 'done', project: await linkLocalProject(ctx, target, { ...(r.link?.brief ? { brief: r.link.brief } : {}), harness: r.link?.harness ?? current.harness, projectId: current.project_id, seed: true }) };
             else {
                 const f = r.files;
                 if (!f.remote_path.startsWith('/') || /[\0\r\n]/.test(f.remote_path))
@@ -445,7 +611,7 @@ export class DeviceExecutor {
                 }
                 result = { state: 'done', files_artifact: r.kind === 'files_pull' ? f.remote_path : target };
             }
-            await this.result(r, result);
+            await postResult((answer, again) => this.result(r, answer, again ? ':older-api' : ''), result);
         }
         catch (e) {
             await this.result(r, { state: 'failed', stderr_b64: Buffer.from(e instanceof Error ? e.message : String(e)).toString('base64') });

package/dist/device-folders.d.ts

@@ -1,4 +1,5 @@
 import type { Ctx, Handler } from './commands.js';
+import type { HubSeed } from './project-hub-seed.js';
 export declare const FOLDER_KINDS: Set<string>;
 /** An absolute or `~/…` path: one the device resolves on its own, outside any conversation's folder. */
 export declare function isDevicePath(path: string): boolean;
@@ -25,12 +26,15 @@ export declare function listDeviceDir(root: string, options?: {
     max_entries?: number;
     include_hidden?: boolean;
 }, signal?: AbortSignal): Promise<DirListing>;
+/** `commit` and `branch`: where work on it starts, in the project hub (an agent's link, 0.28.0+). */
 export interface LinkedProject {
     project_id: string;
     repo_remote: string;
     folder: string;
     name: string;
     conversation_id?: string;
+    commit?: string;
+    branch?: string;
 }
 type Starter = (ctx: Ctx, folder: string, harness: 'claude' | 'codex', brief: string) => Promise<{
     id: string;
@@ -42,6 +46,14 @@ type Starter = (ctx: Ctx, folder: string, harness: 'claude' | 'codex', brief: st
  * prompt. The brief goes in on standard input, never in a command line another user can read.
  */
 export declare const startFromFolder: Starter;
+/**
+ * The conversation `shard agents new --json` started, from its whole output: one pretty-printed JSON document
+ * (format.ts json), never its last line (staging 2026-10-16: the last line is `}`).
+ */
+export declare function startedConversation(stdout: string): {
+    id: string;
+    project_id: string;
+};
 /**
  * `folder` becomes one of your projects: the repository its Git origin names (else the folder itself), in your
  * project on this API. It is selected for background preparation, so its files are in the cloud before the next chat,
@@ -52,7 +64,8 @@ export declare function linkLocalProject(ctx: Ctx, path: string, options?: {
     brief?: string;
     harness?: 'claude' | 'codex';
     projectId?: string;
-}, start?: Starter): Promise<LinkedProject>;
+    seed?: boolean;
+}, start?: Starter, seedHub?: (ctx: Ctx, folder: string, projectId: string) => Promise<HubSeed>): Promise<LinkedProject>;
 /** `shard projects link <path>` (0.25.0+): what the desktop app's "Add a folder…" runs, the same as a device's project_link. */
 export declare const PROJECT_LINK_HANDLERS: Record<string, Handler>;
 export {};

package/dist/device-folders.js

@@ -18,6 +18,7 @@ import { UsageError } from "./errors.js";
 import { ensureProjectGit } from "./project-git.js";
 import { normalizeRemote, projectIdentity } from "./project-identity.js";
 import { selectProject } from "./project-preparation.js";
+import { seedProjectHub } from "./project-hub-seed.js";
 export const FOLDER_KINDS = new Set(['dir_list', 'project_link']);
 /** An absolute or `~/…` path: one the device resolves on its own, outside any conversation's folder. */
 export function isDevicePath(path) { return isAbsolute(path) || path === '~' || path.startsWith('~/'); }
@@ -148,10 +149,11 @@ export const startFromFolder = (ctx, folder, harness, brief) => {
             env: { ...process.env, ...ctx.io.env, SHARDFLUX_CONFIG_DIR: ctx.store.dir, SHARDFLUX_API_URL: ctx.apiUrl, CI: '1' },
         });
         const out = [], err = [];
+        let outBytes = 0;
         const stop = () => child.kill('SIGTERM');
         const timer = setTimeout(stop, 300_000);
         ctx.signal.addEventListener('abort', stop, { once: true });
-        child.stdout.on('data', (b) => { if (out.length < 256)
+        child.stdout.on('data', (b) => { if ((outBytes += b.length) <= 8 << 20)
             out.push(b); });
         child.stderr.on('data', (b) => { if (err.length < 64)
             err.push(b); });
@@ -163,11 +165,7 @@ export const startFromFolder = (ctx, folder, harness, brief) => {
             try {
                 if (code !== 0)
                     throw new Error(lastLine(Buffer.concat(err).toString('utf8')) || `The conversation did not start (exit ${code}).`);
-                const started = JSON.parse(text.trim().split('\n').at(-1));
-                const id = started.conversation?.id ?? started.workspace?.labels?.shard_conversation;
-                if (!id)
-                    throw new Error('The conversation did not start.');
-                resolveStart({ id, project_id: started.conversation?.project_id ?? started.workspace?.project_id ?? '' });
+                resolveStart(startedConversation(text));
             }
             catch (error) {
                 reject(error instanceof Error ? error : new Error(String(error)));
@@ -176,6 +174,17 @@ export const startFromFolder = (ctx, folder, harness, brief) => {
         child.stdin.end(brief);
     });
 };
+/**
+ * The conversation `shard agents new --json` started, from its whole output: one pretty-printed JSON document
+ * (format.ts json), never its last line (staging 2026-10-16: the last line is `}`).
+ */
+export function startedConversation(stdout) {
+    const started = JSON.parse(stdout);
+    const id = started.conversation?.id ?? started.workspace?.labels?.shard_conversation;
+    if (!id)
+        throw new Error('The conversation did not start.');
+    return { id, project_id: started.conversation?.project_id ?? started.workspace?.project_id ?? '' };
+}
 function lastLine(stderr) {
     const text = stderr.trim();
     try {
@@ -192,7 +201,7 @@ function lastLine(stderr) {
  * and kept as this device's live copy: what conversations started from it finish lands back in it. With `brief`, a
  * conversation starts there at once. A folder without Git gets a repository, as a new chat from it does.
  */
-export async function linkLocalProject(ctx, path, options = {}, start = startFromFolder) {
+export async function linkLocalProject(ctx, path, options = {}, start = startFromFolder, seedHub = seedProjectHub) {
     const { folder } = projectIdentity(path);
     await ensureProjectGit(ctx, folder);
     const identity = projectIdentity(folder);
@@ -210,7 +219,10 @@ export async function linkLocalProject(ctx, path, options = {}, start = startFro
     if (!projectId)
         throw new UsageError('Choose your default project first: shard projects use <id|slug>.');
     const name = [...(identity.remote ? identity.slug : basename(folder))].slice(0, 200).join('') || identity.slug;
-    return { project_id: projectId, repo_remote: identity.remote ?? `file://${folder}`, folder, name, ...(conversationId ? { conversation_id: conversationId } : {}) };
+    // An agent's link: the folder as it is now goes to the project hub, so its work can start in the cloud at once.
+    const seed = options.seed ? await seedHub(ctx, folder, projectId) : null;
+    return { project_id: projectId, repo_remote: identity.remote ?? `file://${folder}`, folder, name, ...(conversationId ? { conversation_id: conversationId } : {}),
+        ...(seed ? { commit: seed.commit, ...(seed.branch ? { branch: seed.branch } : {}) } : {}) };
 }
 /** `shard projects link <path>` (0.25.0+): what the desktop app's "Add a folder…" runs, the same as a device's project_link. */
 export const PROJECT_LINK_HANDLERS = {

package/dist/device-helper.d.ts

@@ -9,3 +9,11 @@ export declare function runDeviceHelper(ctx: Ctx, options?: {
  * A home conversation, an Orchestrator master or a chat the desktop app started asks from these.
  */
 export declare function deviceProjects(ctx: Ctx): Promise<string[]>;
+/** 409 `device_id_taken`: this device id is registered in a project by another identity (POST /v1/device-requests/heartbeat). */
+export declare function deviceIdTaken(e: unknown): boolean;
+/**
+ * A new device id for this computer, replacing `old` (0.27.0+). Local state stays: grants are kept by API and folder
+ * or project (device-bridge.ts DeviceGrants), the approval mode by person (device-mode.ts), and the twin's refs by the
+ * id that made them. The old id is kept in `device-id-history.json` (the last 20) for support.
+ */
+export declare function renewDeviceId(dir: string, old: string, projectId: string): string;