@shardflux/cli 0.17.0 → 0.18.0-next.4

package/CHANGELOG.md

@@ -2,10 +2,15 @@
 
 ## 0.17.0 (not yet published)
 
-- Linux (Ubuntu 24.04, x64 and arm64): bare `shard` signs in and connects Claude/Codex in the terminal. The
-  systemd user helper keeps the live twin, files and conversation mirrors running; `shard device requests`,
-  `shard device approve <id>` and `shard device deny <id>` handle local approvals. Desktop launches open a terminal;
-  macOS keeps its extra menu bar app.
+- Linux (Ubuntu 24.04, x64 and arm64): bare `shard` opens the Shardflux app in a graphical session. The optional CPU package installs without npm install scripts, adds Shardflux to the app grid, and starts at login. Headless sessions keep terminal onboarding. The systemd user helper keeps the live twin, files and conversation mirrors running; `shard device requests`, `shard device approve <id>` and `shard device deny <id>` handle local approvals.
+- The Ubuntu desktop app includes the custom tray panel, launcher capture and project/model menus, all Settings panes, local device and credential approval panels, notifications with actions, file downloads and packaged-app updates. `shard device approve --always` remembers matching in-project requests; outside-folder requests remain one-time approvals.
+- T3 Code on Linux: `shard` finds T3 Code installed from its .deb or AppImage (and AppImageLauncher, Gear Lever,
+  flatpak and snap entries), registers the Shardflux provider in it, shows it in onboarding, and opens it from its
+  desktop entry. `shard agents new --in t3`, `shard agents open t3` and `shard agents targets --open-in` work as on
+  macOS: a T3 build with ACP providers starts each thread on its Shardflux provider in a cloud VM of its own, and T3
+  Code 0.0.45 opens the project VM as an SSH environment. `shard agents targets --json` reports it under `t3`
+  (`last_used_at`: when T3 last started). The Shardflux provider is also recognized in the latest T3 nightlies on
+  macOS.
 
 - A Codex project opens in T3 Code without a Claude sign-in (T3 shows Claude as signed out, and says how to sign in), and `--json` names the T3 Connect sign-in `shard` started for the phone (`t3_link.sign_in`, or `t3_link.needs_login` when this computer has no session).
 - A conversation settles when its turn ends (`done` or `unresolved` right away) and its VM takes the next message.

package/README.md

@@ -87,9 +87,10 @@ time `shard` runs, with launch at login enabled; `shard menubar stop` turns it o
 
 T3 Code uses one **Shardflux** provider; choose a Claude Code or Codex model to start that agent in the cloud.
 Model choices come from your cloud agent's session and use the same coding tools and settings as its terminal.
-The provider is registered automatically when T3 Code is installed. Choose **Sign in** on its card in T3's provider
-settings: T3 runs `shard acp --login` in its own terminal, which creates or signs in to your account (with this Mac's
-Codex login, or your email) and connects Claude Code and Codex, skipping every step that is already done (0.15.0+).
+The provider is registered automatically when T3 Code is installed, on macOS and on Linux from its .deb or AppImage
+(0.17.0+). Choose **Sign in** on its card in T3's provider settings: T3 runs `shard acp --login` in its own terminal,
+which creates or signs in to your account (with this computer's Codex login, or your email) and connects Claude Code
+and Codex, skipping every step that is already done (0.15.0+).
 With T3 Code 0.0.45, `shard agents new --in t3` adds the project as an SSH environment instead.
 
 Start another thread on a computer that is already set up (0.16.0+): it shares that conversation's installed

package/dist/agent-target-commands.js

@@ -78,12 +78,8 @@ export async function prepareSsh(ws, ctx, targets, host) {
     return cell;
 }
 async function openApp(target, env) {
-    if (target === 't3') {
-        const install = t3Install(env);
-        if (!install)
-            throw t3NotInstalled();
-        return openT3(env, install.path);
-    }
+    if (target === 't3')
+        return openT3(env, t3Install(env));
     const child = spawn('open', ['-b', { 'claude-desktop': 'com.anthropic.claudefordesktop', 'codex-app': 'com.openai.codex', t3: 'com.t3tools.t3code' }[target]], { env, stdio: 'ignore' });
     await new Promise((resolve, reject) => {
         const timer = setTimeout(() => { child.kill('SIGKILL'); reject(new Error('app launcher timed out')); }, 10_000);
@@ -283,7 +279,7 @@ export async function openDesktopWorkspace(ctx, ws, target, t3Version, prewarmed
     if (target === 't3') {
         // The thread exists once startSshThread returns: a failure to show T3 names it rather than inviting a retry.
         try {
-            await openT3(ctx.io.env, (install ?? t3Install(ctx.io.env))?.path ?? '');
+            await openT3(ctx.io.env, install ?? t3Install(ctx.io.env));
         }
         catch (error) {
             throw started ? t3OpenFailed(error, { t3_thread_id: started.t3_thread_id, conversation_id: conversation ?? (ws.labels.shard_conversation || null), workspace_key: ws.key }) : error;

package/dist/agent-targets.d.ts

@@ -1,3 +1,4 @@
+import type { T3LinuxApp } from './t3-linux.js';
 export type DesktopTarget = 'claude-desktop' | 'codex-app' | 't3';
 export interface TargetEntry {
     host: string;
@@ -13,13 +14,22 @@ export declare const targetLabel: (e: Pick<TargetEntry, "agent" | "project">) =>
 export declare function targetIdentity(key: string): Pick<TargetEntry, 'host' | 'workspace' | 'project' | 'agent'>;
 /** Replace only a marked block, retaining every byte outside it. Put Includes before user Host blocks. */
 export declare function managedBlock(text: string, body: string): string;
-/** The installed T3 Code apps (any channel), with their path and version, in the given app folders. */
-export declare function t3Apps(dirs: string[], platform?: NodeJS.Platform): Array<{
+/**
+ * An installed T3 Code: on macOS `path` is the .app bundle; on Linux it is the program its desktop entry runs (the
+ * executable, or the AppImage), and `linux` says how it was installed and how it starts (t3-linux.ts).
+ */
+export interface T3App {
     path: string;
     version: string | null;
-}>;
-/** The app folders scanned for desktop apps: SHARDFLUX_APPLICATIONS_DIRS, else /Applications and ~/Applications. */
-export declare function applicationDirs(env: Record<string, string | undefined>): string[];
+    linux?: T3LinuxApp;
+}
+/** The installed T3 Code apps (any channel), with their path and version, in the given app folders (applicationDirs). */
+export declare function t3Apps(dirs: string[], platform?: NodeJS.Platform, env?: Record<string, string | undefined>): T3App[];
+/**
+ * The folders scanned for desktop apps: SHARDFLUX_APPLICATIONS_DIRS (colon-separated) when set; else /Applications and
+ * ~/Applications on macOS, and on Linux the XDG application folders and the usual AppImage folders (linuxApplicationDirs).
+ */
+export declare function applicationDirs(env: Record<string, string | undefined>, platform?: NodeJS.Platform): string[];
 /** The first `name` app bundle with this bundle id in the app folders (macOS only). */
 export declare function desktopAppPath(dirs: string[], name: string, bundle: string, platform?: NodeJS.Platform): string | undefined;
 export declare function installedTargets(env: Record<string, string | undefined>, platform?: NodeJS.Platform, appDirs?: string[]): {

package/dist/agent-targets.js

@@ -7,6 +7,7 @@ import { writePrivateFile } from "./credentials.js";
 import { UsageError } from "./errors.js";
 import { projectWorkspacePath } from "./agent-repository.js";
 import { withTargetLock } from "./target-lock.js";
+import { linuxApplicationDirs, linuxT3Apps } from "./t3-linux.js";
 const PERSISTED_TARGETS = ['claude-desktop', 'codex-app'];
 const BEGIN = '# BEGIN Shardflux managed targets';
 const END = '# END Shardflux managed targets';
@@ -36,8 +37,10 @@ export function managedBlock(text, body) {
     const stop = end + END.length + (text[end + END.length] === '\n' ? 1 : 0);
     return text.slice(0, start) + block + text.slice(stop);
 }
-/** The installed T3 Code apps (any channel), with their path and version, in the given app folders. */
-export function t3Apps(dirs, platform = process.platform) {
+/** The installed T3 Code apps (any channel), with their path and version, in the given app folders (applicationDirs). */
+export function t3Apps(dirs, platform = process.platform, env = process.env) {
+    if (platform === 'linux')
+        return linuxT3Apps(dirs, env);
     const found = [];
     if (platform !== 'darwin')
         return found;
@@ -69,10 +72,15 @@ export function t3Apps(dirs, platform = process.platform) {
     }
     return found;
 }
-/** The app folders scanned for desktop apps: SHARDFLUX_APPLICATIONS_DIRS, else /Applications and ~/Applications. */
-export function applicationDirs(env) {
+/**
+ * The folders scanned for desktop apps: SHARDFLUX_APPLICATIONS_DIRS (colon-separated) when set; else /Applications and
+ * ~/Applications on macOS, and on Linux the XDG application folders and the usual AppImage folders (linuxApplicationDirs).
+ */
+export function applicationDirs(env, platform = process.platform) {
     const home = env.HOME || homedir();
-    return env.SHARDFLUX_APPLICATIONS_DIRS !== undefined ? env.SHARDFLUX_APPLICATIONS_DIRS.split(':').filter(Boolean) : ['/Applications', join(home, 'Applications')];
+    if (env.SHARDFLUX_APPLICATIONS_DIRS !== undefined)
+        return env.SHARDFLUX_APPLICATIONS_DIRS.split(':').filter(Boolean);
+    return platform === 'linux' ? linuxApplicationDirs(env) : ['/Applications', join(home, 'Applications')];
 }
 /** The first `name` app bundle with this bundle id in the app folders (macOS only). */
 export function desktopAppPath(dirs, name, bundle, platform = process.platform) {
@@ -88,10 +96,10 @@ export function desktopAppPath(dirs, name, bundle, platform = process.platform)
 }
 export function installedTargets(env, platform = process.platform, appDirs) {
     // SHARDFLUX_APPLICATIONS_DIRS (colon-separated) replaces the scanned app folders, like SHARDFLUX_CONFIG_DIR does for config.
-    const dirs = appDirs ?? applicationDirs(env);
+    const dirs = appDirs ?? applicationDirs(env, platform);
     const hasApp = (name, bundle) => desktopAppPath(dirs, name, bundle, platform) !== undefined;
     const versions = {};
-    const t3Bundles = t3Apps(dirs, platform);
+    const t3Bundles = t3Apps(dirs, platform, env);
     const t3 = t3Bundles.length > 0;
     for (const app of t3Bundles)
         if (app.version)
@@ -106,7 +114,9 @@ export function installedTargets(env, platform = process.platform, appDirs) {
     const clients = [hasApp('Claude.app', 'com.anthropic.claudefordesktop') && 'claude-desktop', (hasApp('Codex.app', 'com.openai.codex') || hasApp('ChatGPT.app', 'com.openai.codex')) && 'codex-app', executable('claude') && 'claude', executable('codex') && 'codex'].filter((v) => !!v);
     if (t3)
         clients.push('t3');
-    return { targets: [...(platform === 'darwin' ? clients.filter(c => c.endsWith('-app') || c === 'claude-desktop' || c === 't3') : []), 'web'], clients, versions };
+    // Linux has T3 Code (0.17.0+); Claude Desktop and the Codex app are macOS apps.
+    const desktop = platform === 'darwin' ? clients.filter(c => c.endsWith('-app') || c === 'claude-desktop' || c === 't3') : platform === 'linux' && t3 ? ['t3'] : [];
+    return { targets: [...desktop, 'web'], clients, versions };
 }
 /** All paths are supplied by the invocation; tests use a temporary HOME, never the owner's app stores. */
 export class AgentTargets {

package/dist/args.js

@@ -13,7 +13,7 @@ import { parseArgs } from 'node:util';
 import { ACCOUNT_COMMANDS } from "./account-args.js";
 import { UsageError } from "./errors.js";
 import { DEFAULT_CHOICE, MODEL_CHOICES } from "./agent-models.js";
-export const CLI_VERSION = '0.17.0';
+export const CLI_VERSION = '0.18.0-next.4';
 export const GLOBAL_OPTIONS = {
     'api-url': { type: 'string', value: '<url>', description: 'API base URL (default $SHARDFLUX_API_URL, else https://api.shardflux.dev).' },
     json: { type: 'boolean', description: 'Print machine-readable JSON on stdout (errors as JSON on stderr).' },
@@ -1229,7 +1229,7 @@ export const ONBOARDING_COMMAND = { path: ['<onboarding>'], summary: 'Set up Sha
 export const CENTER_COMMAND = { path: ['<center>'], summary: 'Open the cloud agent command center', positionals: [], options: {} };
 const AGENT_COMMANDS = [
     { path: ['device', 'requests'], summary: 'Review local device requests waiting for approval', positionals: [], options: {} },
-    ...['approve', 'deny'].map(action => ({ path: ['device', action], summary: `${action} a local device request`, positionals: [{ name: 'id', required: true }], options: {} })),
+    ...['approve', 'deny'].map((action) => ({ path: ['device', action], summary: `${action} a local device request`, positionals: [{ name: 'id', required: true }], options: action === 'approve' ? { always: { type: 'boolean', description: 'Allow matching requests for this project; never for outside-folder access.' } } : {} })),
     { path: ['conversations', 'try'], summary: 'Try a conversation in a synced local worktree', positionals: [{ name: 'conversation', required: true }], options: { path: { type: 'string', value: '<path>', description: 'Local project checkout.' }, stop: { type: 'boolean', description: 'Stop the device helper’s local sync and ports.' } } },
     { path: ['agents', 'targets'], summary: 'Detect apps or configure managed desktop connections', positionals: [{ name: 'agent' }], options: {
             remove: { type: 'boolean', description: 'Remove this agent’s managed entries, or all entries for this API URL.' },

package/dist/desktop-linux.d.ts

@@ -0,0 +1,40 @@
+import { spawn, execFile } from 'node:child_process';
+import type { Ctx } from './commands.js';
+declare const exec: typeof execFile.__promisify__;
+export interface DesktopStatus {
+    installed: boolean;
+    version: string | null;
+    running: boolean;
+    pids: number[];
+    login: 'on' | 'off';
+}
+export declare function linuxDesktopPackage(arch?: NodeJS.Architecture): string | null;
+export declare function graphicalSession(env: NodeJS.ProcessEnv): boolean;
+export declare class LinuxDesktopManager {
+    #private;
+    readonly home: string;
+    readonly app: string;
+    constructor(options?: {
+        home?: string;
+        source?: () => string | null;
+        env?: NodeJS.ProcessEnv;
+        exec?: typeof exec;
+        spawn?: typeof spawn;
+        isProcess?: (pid: number, executable: string) => boolean;
+    });
+    status(dir: string): Promise<DesktopStatus>;
+    packagedVersion(): string | null;
+    login(on: boolean): Promise<void>;
+    stop(dir: string): Promise<DesktopStatus>;
+    refresh(dir: string, api: string): Promise<{
+        result: string;
+        from?: string | null;
+        to?: string | null;
+    }>;
+    start(dir: string, api: string, view?: string, runtime?: {
+        node: string;
+        script: string;
+    }): Promise<DesktopStatus>;
+}
+export declare function tryLinuxDesktop(ctx: Ctx): Promise<boolean>;
+export {};

package/dist/desktop-linux.js

@@ -0,0 +1,186 @@
+import { spawn, execFile } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, chmodSync, mkdtempSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { promisify } from 'node:util';
+import { UsageError } from "./errors.js";
+import { compareVersions } from '@shardflux/sdk';
+const exec = promisify(execFile);
+export function linuxDesktopPackage(arch = process.arch) {
+    if (!['x64', 'arm64'].includes(arch))
+        return null;
+    try {
+        return join(dirname(createRequire(import.meta.url).resolve(`@shardflux/desktop-linux-${arch}/package.json`)), 'app');
+    }
+    catch {
+        return null;
+    }
+}
+export function graphicalSession(env) { return !!(env.DISPLAY || env.WAYLAND_DISPLAY); }
+const desktopString = (text) => `"${text.replace(/(["`$\\])/g, '\\$1')}"`;
+export class LinuxDesktopManager {
+    home;
+    app;
+    #source;
+    #env;
+    #exec;
+    #spawn;
+    #isProcess;
+    constructor(options = {}) {
+        this.home = options.home ?? homedir();
+        this.app = join(this.home, '.local', 'share', 'shardflux', 'desktop');
+        this.#source = options.source ?? linuxDesktopPackage;
+        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;
+        } });
+    }
+    #version(path) {
+        try {
+            const manifest = JSON.parse(readFileSync(join(path, 'manifest.json'), 'utf8'));
+            return manifest.id === 'dev.shardflux.Desktop' && typeof manifest.version === 'string' ? manifest.version : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async status(dir) {
+        const version = this.#version(this.app), pids = [];
+        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')))
+                pids.push(pid);
+        }
+        catch { /* no running app */ }
+        return { installed: version !== null, version, running: pids.length > 0, pids, login: existsSync(join(this.home, '.config/autostart/shardflux.desktop')) ? 'on' : 'off' };
+    }
+    packagedVersion() { const path = this.#source(); return path ? this.#version(path) : null; }
+    async login(on) {
+        const file = join(this.home, '.config/autostart/shardflux.desktop');
+        if (!on) {
+            rmSync(file, { force: true });
+            return;
+        }
+        mkdirSync(dirname(file), { recursive: true });
+        const entry = join(this.home, '.local/share/applications/dev.shardflux.Desktop.desktop');
+        if (!existsSync(entry))
+            throw new UsageError('Run shard menubar start first.');
+        cpSync(entry, file);
+    }
+    async stop(dir) {
+        const status = await this.status(dir);
+        if (status.running) {
+            await this.#exec(join(this.app, 'shardflux-desktop'), ['--control', 'stop'], { env: { ...this.#env, SHARDFLUX_CONFIG_DIR: dir }, timeout: 5_000 });
+            for (let i = 0; i < 30; i++) {
+                await new Promise(r => setTimeout(r, 100));
+                if (!(await this.status(dir)).running)
+                    break;
+            }
+            if ((await this.status(dir)).running)
+                throw new UsageError('Shardflux is still stopping. Try shard menubar status.');
+        }
+        return this.status(dir);
+    }
+    async refresh(dir, api) {
+        const before = await this.status(dir), version = this.packagedVersion();
+        if (!before.installed || !version)
+            return { result: 'off' };
+        if ((compareVersions(before.version, version) ?? 0) >= 0)
+            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 });
+                if (!JSON.parse(stdout).idle)
+                    return { result: 'busy', from: before.version, to: version };
+            }
+            catch {
+                return { result: 'busy', from: before.version, to: version };
+            }
+        }
+        const after = await this.start(dir, api);
+        return { result: 'updated', from: before.version, to: after.version };
+    }
+    async start(dir, api, view = 'onboarding', runtime = { node: process.execPath, script: process.argv[1] }) {
+        const source = this.#source(), version = source && this.#version(source);
+        if (!source || !version)
+            throw new UsageError('Install the window with npm i -g shardflux --include=optional, then run shard.');
+        if (!graphicalSession(this.#env))
+            throw new UsageError('Open shard from your desktop session to show the window.');
+        const current = await this.status(dir);
+        if (!current.version || (compareVersions(current.version, version) ?? -1) < 0) {
+            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.'); });
+            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 });
+                chmodSync(join(staged, 'shardflux-desktop'), 0o755);
+                if (current.running)
+                    await this.stop(dir);
+                if (existsSync(this.app))
+                    renameSync(this.app, backup);
+                try {
+                    renameSync(staged, this.app);
+                }
+                catch (error) {
+                    if (existsSync(backup))
+                        renameSync(backup, this.app);
+                    throw error;
+                }
+            }
+            finally {
+                rmSync(staging, { recursive: true, force: true });
+            }
+        }
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const env = { ...this.#env, SHARDFLUX_CONFIG_DIR: dir, SHARDFLUX_API_URL: api, SHARDFLUX_NODE: runtime.node, SHARDFLUX_CLI: runtime.script };
+        const desktop = join(this.home, '.local/share/applications/dev.shardflux.Desktop.desktop');
+        mkdirSync(dirname(desktop), { recursive: true });
+        const args = ['/usr/bin/env', `SHARDFLUX_CONFIG_DIR=${dir}`, `SHARDFLUX_API_URL=${api}`, `SHARDFLUX_NODE=${runtime.node}`, `SHARDFLUX_CLI=${runtime.script}`, join(this.app, 'shardflux-desktop')];
+        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 });
+        if ((await this.status(dir)).running)
+            await this.#exec(join(this.app, 'shardflux-desktop'), ['--control', view], { env, timeout: 5_000 });
+        else {
+            const child = this.#spawn(join(this.app, 'shardflux-desktop'), [view], { env, detached: true, stdio: 'ignore' });
+            await new Promise((resolve, reject) => { child.once('error', reject); child.once('spawn', resolve); });
+            child.unref();
+            for (let i = 0; i < 40; i++) {
+                if ((await this.status(dir)).running)
+                    break;
+                await new Promise(r => setTimeout(r, 100));
+            }
+        }
+        const result = await this.status(dir);
+        if (!result.running)
+            throw new UsageError('The Shardflux window did not open. Run shard menubar start from your desktop session.');
+        return result;
+    }
+}
+export async function tryLinuxDesktop(ctx) {
+    if (process.platform !== 'linux' || ctx.json || ctx.io.env.SHARDFLUX_DESKTOP_CHILD === '1' || !graphicalSession(ctx.io.env))
+        return false;
+    try {
+        const manager = new LinuxDesktopManager({ home: ctx.io.env.HOME, env: ctx.io.env });
+        await manager.start(ctx.store.dir, ctx.apiUrl);
+        await manager.login(true);
+        return true;
+    }
+    catch (err) {
+        ctx.io.stderr.write(`${err instanceof Error ? err.message : 'The Shardflux window could not open.'}\n`);
+        return false;
+    }
+}

package/dist/device-approvals.js

@@ -34,6 +34,8 @@ export function answerDeviceApproval(dir, id, choice) {
     const pending = pendingDeviceApprovals(dir).find(p => p.request_id === id);
     if (!pending)
         throw new UsageError('That request is no longer waiting for approval. Run shard device requests.');
+    if (choice === 'always' && pending.outside)
+        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 }));
 }
 /** Local user-owned files carry approvals; cloud data can never answer its own request. */
@@ -65,9 +67,9 @@ export const DEVICE_HANDLERS = {
         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}` : ''}\n  shard device approve ${r.request_id} | shard device deny ${r.request_id}\n`).join('') : 'No device requests waiting for approval.\n');
         return Promise.resolve(0);
     },
-    ...Object.fromEntries(['approve', 'deny'].map(action => [`device ${action}`, (ctx, _values, [id]) => {
-            answerDeviceApproval(ctx.store.dir, id, action === 'approve' ? 'once' : 'deny');
-            ctx.io.stdout.write(ctx.json ? json({ request_id: id, choice: action }) : `Device request ${id}: ${action === 'approve' ? 'approved once' : 'denied'}.\n`);
+    ...Object.fromEntries(['approve', 'deny'].map(action => [`device ${action}`, (ctx, values, [id]) => {
+            answerDeviceApproval(ctx.store.dir, id, action === 'approve' ? values.always === true ? 'always' : 'once' : 'deny');
+            ctx.io.stdout.write(ctx.json ? json({ request_id: id, choice: action === 'approve' && values.always ? 'always' : action }) : `Device request ${id}: ${action === 'approve' ? values.always ? 'allowed for project' : 'approved once' : 'denied'}.\n`);
             return Promise.resolve(0);
         }])),
 };

package/dist/main.js

@@ -21,6 +21,7 @@ import { registerInstalledT3 } from "./t3-provider.js";
 import { refreshForwarderAgent } from "./cli-proxy.js";
 import { runAcpLogin } from "./acp-login.js";
 import { terminalOnboarding } from "./terminal-onboarding.js";
+import { tryLinuxDesktop } from "./desktop-linux.js";
 import { startLinuxHelper } from "./linux-helper.js";
 import { runDeviceHelper } from "./device-helper.js";
 import { housekeeping, startupHousekeeping } from "./agent-git-commands.js";
@@ -688,7 +689,7 @@ export async function run(argv, io, opts = {}) {
         }
         stopHelper = startLinuxHelper(ctx);
     };
-    const handler = parsed.command.path[0] === 'acp' ? (ctx) => parsed.values.login === true ? runAcpLogin(ctx) : runAcp(ctx) : parsed.command.path[0] === 'device-helper' ? (ctx) => runDeviceHelper(ctx, { service: parsed.values.service === true }) : command === 'menubar refresh' ? runMenubarRefresh : parsed.command === PROJECT_COMMAND ? launchProjectCommand : parsed.command === ONBOARDING_COMMAND ? (ctx, values) => terminalOnboarding(ctx, values, { startHelper }) : parsed.command === CENTER_COMMAND ? commandCenter : HANDLERS[parsed.command.path.join(' ')];
+    const handler = parsed.command.path[0] === 'acp' ? (ctx) => parsed.values.login === true ? runAcpLogin(ctx) : runAcp(ctx) : parsed.command.path[0] === 'device-helper' ? (ctx) => runDeviceHelper(ctx, { service: parsed.values.service === true }) : command === 'menubar refresh' ? runMenubarRefresh : parsed.command === PROJECT_COMMAND ? launchProjectCommand : parsed.command === ONBOARDING_COMMAND ? async (ctx, values) => await tryLinuxDesktop(ctx) ? 0 : terminalOnboarding(ctx, values, { startHelper }) : parsed.command === CENTER_COMMAND ? commandCenter : HANDLERS[parsed.command.path.join(' ')];
     if (!handler)
         return report(new UsageError(`unknown command "${parsed.command.path.join(' ')}"`));
     // Long-running helpers other programs start (an editor, launchd, the menu bar) skip the per-command housekeeping.

package/dist/menubar.js

@@ -8,6 +8,7 @@ import { compareVersions } from '@shardflux/sdk';
 import { AgentStateStore } from "./agent-state.js";
 import { UsageError } from "./errors.js";
 import { json } from "./format.js";
+import { LinuxDesktopManager, linuxDesktopPackage } from "./desktop-linux.js";
 const execute = promisify(execFile);
 /**
  * Every native tool a default MenubarManager runs (plutil, codesign, xattr, open, the app's --control) goes through
@@ -336,11 +337,19 @@ export function packagedAppPath() {
  */
 export function refreshMenubarInBackground(o) {
     try {
-        if ((o.platform ?? process.platform) !== 'darwin')
+        const platform = o.platform ?? process.platform;
+        if (!['darwin', 'linux'].includes(platform))
             return false;
-        const installed = plistVersion(join(o.home, 'Applications', 'Shardflux.app'));
-        const source = (o.packageApp ?? packagedAppPath)();
-        const packaged = source ? plistVersion(source) : null;
+        const manifest = (dir) => { try {
+            const m = JSON.parse(readFileSync(join(dir, 'manifest.json'), 'utf8'));
+            return m.id === 'dev.shardflux.Desktop' ? m.version : null;
+        }
+        catch {
+            return null;
+        } };
+        const installed = platform === 'linux' ? manifest(join(o.home, '.local/share/shardflux/desktop')) : plistVersion(join(o.home, 'Applications', 'Shardflux.app'));
+        const source = (o.packageApp ?? (platform === 'linux' ? linuxDesktopPackage : packagedAppPath))();
+        const packaged = source ? platform === 'linux' ? manifest(source) : plistVersion(source) : null;
         if (!installed || !packaged || compareAppVersions(installed, packaged) >= 0)
             return false;
         if (new AgentStateStore(o.dir).read().menubar_stopped === true)
@@ -404,6 +413,19 @@ function refreshLock(dir) {
 }
 /** `shard menubar refresh` (not listed in help, so not in HANDLERS): what refreshMenubarInBackground starts. */
 export const runMenubarRefresh = async (ctx) => {
+    if (process.platform === 'linux') {
+        const manager = new LinuxDesktopManager({ home: ctx.io.env.HOME, env: ctx.io.env });
+        const stopped = new AgentStateStore(ctx.store.dir).read().menubar_stopped === true;
+        const unlock = refreshLock(ctx.store.dir);
+        try {
+            const result = stopped ? { result: 'off' } : !unlock ? { result: 'locked' } : await manager.refresh(ctx.store.dir, ctx.apiUrl);
+            ctx.io.stdout.write(ctx.json ? json(result) : `Desktop: ${result.result}\n`);
+        }
+        finally {
+            unlock?.();
+        }
+        return 0;
+    }
     const manager = new MenubarManager({ home: ctx.io.env.HOME || homedir(), signal: ctx.signal });
     let outcome;
     if (new AgentStateStore(ctx.store.dir).read().menubar_stopped === true)
@@ -425,6 +447,24 @@ export const runMenubarRefresh = async (ctx) => {
 };
 export const MENUBAR_HANDLERS = Object.fromEntries(['start', 'stop', 'status'].map((action) => {
     const handler = async (ctx, values) => {
+        if (process.platform === 'linux') {
+            const { LinuxDesktopManager } = await import("./desktop-linux.js");
+            const manager = new LinuxDesktopManager({ home: ctx.io.env.HOME, env: ctx.io.env });
+            let status = action === 'start' ? await manager.start(ctx.store.dir, ctx.apiUrl) : action === 'stop' ? await manager.stop(ctx.store.dir) : await manager.status(ctx.store.dir);
+            if (values.login !== undefined) {
+                if (values.login !== 'on' && values.login !== 'off')
+                    throw new UsageError('--login must be on or off.');
+                await manager.login(values.login === 'on');
+                status = await manager.status(ctx.store.dir);
+            }
+            if (action !== 'status')
+                new AgentStateStore(ctx.store.dir).update(doc => { if (action === 'stop')
+                    doc.menubar_stopped = true;
+                else
+                    delete doc.menubar_stopped; });
+            ctx.io.stdout.write(ctx.json ? json({ ...status, packaged_version: manager.packagedVersion() }) : `Shardflux: ${status.running ? 'running' : 'stopped'} · login ${status.login}\n`);
+            return 0;
+        }
         if (values.login !== undefined && !['on', 'off'].includes(String(values.login)))
             throw new UsageError('--login must be on or off.');
         const manager = new MenubarManager({ home: ctx.io.env.HOME || homedir(), signal: ctx.signal });

package/dist/onboarding.js

@@ -9,8 +9,9 @@ import { t3PhoneLink } from "./t3-phone.js";
 import { readAgentCredentials, syncAgentCredentials } from "./agent-credentials.js";
 import { getConversation } from "./conversations.js";
 import { codexHealth, readCodexConnector, restartCodexConnector } from "./codex-cloud.js";
-import { applicationDirs, t3Apps } from "./agent-targets.js";
-import { configureT3Provider, t3BundleSupportsAcp } from "./t3-provider.js";
+import { applicationDirs } from "./agent-targets.js";
+import { configureT3Provider } from "./t3-provider.js";
+import { t3Install } from "./t3-mode.js";
 /**
  * The first-run demo's task: it shows the agent's own computer at work. The user copies it and pastes it into the
  * launcher themselves; Daylight's own CLAUDE.md and AGENTS.md say how to run it and test it in the desktop browser.
@@ -67,11 +68,12 @@ export function parseApps(value) {
  * over SSH (`shard agents new --in t3`), and says which environment to add. Null when T3 Code is not installed.
  */
 export async function t3Connection(ctx, signedIn, appDirs = applicationDirs(ctx.io.env), platform = process.platform) {
-    const app = t3Apps(appDirs, platform)[0];
+    // The same install every T3 command uses (macOS and Linux): a build with ACP providers first.
+    const app = t3Install(ctx.io.env, platform, appDirs);
     if (!app)
         return null;
     const base = { id: 't3', optional: true, found: true, app_path: app.path };
-    if (t3BundleSupportsAcp(app.path)) {
+    if (app.mode === 'acp') {
         try {
             await configureT3Provider(ctx.io.env, ctx.store.dir, false, ctx.signal);
             // The provider works once there is an API key; without an account its own Sign in (shard acp --login) makes one.
@@ -123,7 +125,7 @@ async function t3Phone(ctx, key) {
                 action: { title: 'Connect phone', url: signIn.verification_uri } };
         }
         if (needsLogin)
-            return { state: 'info', fact: 'Sign in to Shardflux on this Mac to use it from the T3 app.' };
+            return { state: 'info', fact: 'Sign in to Shardflux on this computer to use it from the T3 app.' };
         return { state: 'pending', fact: `Adding ${link.label} to the T3 app on your phone…` };
     }
     catch (error) {

package/dist/t3-asar.d.ts

@@ -0,0 +1,10 @@
+/** The server CLI inside the archive: what Electron runs as Node to issue T3 sessions. */
+export declare const T3_SERVER_ENTRY = "apps/server/dist/bin.mjs";
+/** The app's release version (package.json `version`, e.g. `0.0.46-nightly.20261010.2908`), or null. */
+export declare function asarVersion(archive: string): string | null;
+/**
+ * Whether the server registers the ACP Registry driver. A version number alone is insufficient (0.0.45 lacks it while
+ * upstream main had it). Builds put the driver in `bin.mjs` itself, or (nightlies since October 2026) in a chunk the
+ * thin `bin.mjs` entry imports (`binCli-<hash>.mjs`): the entry and the chunks it names are searched.
+ */
+export declare function t3ArchiveSupportsAcp(archive: string): boolean;