@shardflux/cli 0.16.0 → 0.18.0-next.4

package/dist/device-approvals.js

@@ -0,0 +1,75 @@
+import { spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { readdirSync, readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { writePrivateFile } from "./credentials.js";
+import { UsageError } from "./errors.js";
+import { json } from "./format.js";
+const paths = (dir, id) => {
+    if (!/^[a-zA-Z0-9_-]{1,96}$/.test(id))
+        throw new UsageError('Invalid device request id.');
+    return { pending: join(dir, 'device-approvals', `${id}.json`), answer: join(dir, 'device-answers', `${id}.json`) };
+};
+export function pendingDeviceApprovals(dir) {
+    let names;
+    try {
+        names = readdirSync(join(dir, 'device-approvals'));
+    }
+    catch {
+        return [];
+    }
+    return names.filter(n => n.endsWith('.json')).flatMap(n => {
+        try {
+            const p = JSON.parse(readFileSync(paths(dir, n.slice(0, -5)).pending, 'utf8'));
+            process.kill(p.pid, 0);
+            return [p];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+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. */
+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 });
+    try {
+        while (!ctx.signal.aborted) {
+            try {
+                const answer = JSON.parse(readFileSync(file.answer, 'utf8'));
+                if (answer.nonce === nonce && ['once', 'always', 'deny'].includes(answer.choice))
+                    return answer.choice;
+            }
+            catch { /* wait for the local CLI */ }
+            await delay(200, undefined, { signal: ctx.signal }).catch(() => undefined);
+        }
+        return 'deny';
+    }
+    finally {
+        rmSync(file.pending, { force: true });
+        rmSync(file.answer, { force: true });
+    }
+}
+export const DEVICE_HANDLERS = {
+    '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}` : ''}\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' ? 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/device-helper.d.ts

@@ -1,3 +1,5 @@
 import type { Ctx } from './commands.js';
 /** The menu bar owns this helper and its stdin; VM data can request actions but cannot answer approvals. */
-export declare function runDeviceHelper(ctx: Ctx): Promise<number>;
+export declare function runDeviceHelper(ctx: Ctx, options?: {
+    service?: boolean;
+}): Promise<number>;

package/dist/device-helper.js

@@ -12,13 +12,14 @@ import { writePrivateFile } from "./credentials.js";
 import { conversationClient } from "./conversation-commands.js";
 import { Readable } from 'node:stream';
 import { runWorktreeTwin } from "./worktree-twin-engine.js";
+import { askLocalDeviceApproval } from "./device-approvals.js";
 /** The menu bar owns this helper and its stdin; VM data can request actions but cannot answer approvals. */
-export async function runDeviceHelper(ctx) {
+export async function runDeviceHelper(ctx, options = {}) {
     const abort = new AbortController(), signal = AbortSignal.any([ctx.signal, abort.signal]);
     ctx = { ...ctx, signal };
     const pending = new Map();
     const inputSource = Readable.from(ctx.io.stdin, { objectMode: false, signal });
-    const input = (async () => {
+    const input = options.service ? Promise.resolve() : (async () => {
         let tail = '';
         for await (const bytes of inputSource) {
             tail += Buffer.from(bytes).toString();
@@ -41,6 +42,8 @@ export async function runDeviceHelper(ctx) {
         const acp = await askConnectedAcp(ctx.store.dir, approval, signal);
         if (acp)
             return acp;
+        if (options.service)
+            return askLocalDeviceApproval(ctx, approval);
         return new Promise(resolve => {
             const denied = () => { pending.delete(approval.request_id); resolve('deny'); };
             signal.addEventListener('abort', denied, { once: true });

package/dist/errors.d.ts

@@ -114,6 +114,8 @@ export declare class ExecSessionRunningError extends HintedError {
 export interface ErrorInfo {
     code: string;
     message: string;
+    /** A refusal `shard` detects itself (CodedError, 0.17.0+): the next step, as plain text (the `hint:` line). */
+    fix?: string;
     status?: number;
     request_id?: string;
     retryable?: boolean;

package/dist/errors.js

@@ -241,7 +241,7 @@ export function describeError(err) {
     if (err instanceof GitError)
         return { code: 'git_error', message: err.message, retryable: false };
     if (err instanceof CodedError)
-        return { code: err.code, message: err.message, retryable: false, ...(err.details ? { details: err.details } : {}) };
+        return { code: err.code, message: err.message, retryable: false, ...(err.hint ? { fix: err.hint } : {}), ...(err.details ? { details: err.details } : {}) };
     if (err instanceof CheckoutTimeoutError) {
         return { code: 'timeout', message: `${err.message}; the checkout stays open (pay at its URL, then check with: shard billing status)`, last_state: err.checkout.status, details: { checkout_id: err.checkout.id, status: err.checkout.status, url: err.checkout.url } };
     }

package/dist/handlers.js

@@ -1,3 +1,4 @@
+import { DEVICE_HANDLERS } from "./device-approvals.js";
 import { CREDENTIAL_HANDLERS } from "./credential-prompts.js";
 import { CONVERSATION_HANDLERS } from "./conversation-commands.js";
 /**
@@ -18,4 +19,5 @@ import { CONVERSATION_HANDLERS as LOCAL_CONVERSATION_HANDLERS } from "./conversa
 import { TWIN_HANDLERS } from "./worktree-twin-engine.js";
 import { CODEX_CLOUD_HANDLERS } from "./codex-cloud.js";
 import { THREAD_HANDLERS } from "./thread-on-computer.js";
-export const HANDLERS = { ...CODEX_CLOUD_HANDLERS, ...THREAD_HANDLERS, ...CONVERSATION_HANDLERS, ...LOCAL_CONVERSATION_HANDLERS, ...TWIN_HANDLERS, ...CREDENTIAL_HANDLERS, ...AGENT_CREDENTIAL_HANDLERS, ...KEY_HANDLERS, ...ACCOUNT_HANDLERS, ...AGENT_HANDLERS, ...CENTER_HANDLERS, ...TARGET_HANDLERS, ...AGENT_GIT_HANDLERS, ...MENUBAR_HANDLERS, ...FILESYSTEM_HANDLERS, ...UPDATE_HANDLERS };
+import { CLI_PROXY_HANDLERS } from "./cli-proxy.js";
+export const HANDLERS = { ...DEVICE_HANDLERS, ...CODEX_CLOUD_HANDLERS, ...CLI_PROXY_HANDLERS, ...THREAD_HANDLERS, ...CONVERSATION_HANDLERS, ...LOCAL_CONVERSATION_HANDLERS, ...TWIN_HANDLERS, ...CREDENTIAL_HANDLERS, ...AGENT_CREDENTIAL_HANDLERS, ...KEY_HANDLERS, ...ACCOUNT_HANDLERS, ...AGENT_HANDLERS, ...CENTER_HANDLERS, ...TARGET_HANDLERS, ...AGENT_GIT_HANDLERS, ...MENUBAR_HANDLERS, ...FILESYSTEM_HANDLERS, ...UPDATE_HANDLERS };

package/dist/index.d.ts

@@ -24,4 +24,8 @@ export type { ErrorInfo } from './errors.js';
 export { changedText, errorText, executionJson, executionSummary, feedbackCommand, json, suspendRequestText, suspendWhenIdleText, table, time, usageText, workspaceDetail, workspaceTable } from './format.js';
 export { TimingRecorder, coldBootNotice, hostLostNotice, lostSuspendNotice, notices, timingJson, timingText } from './timing.js';
 export { readAgentCredentials, syncAgentCredentials } from './agent-credentials.js';
+export { detectLocalCliProxy, importCliProxy } from './cli-proxy.js';
+export type { ImportOptions, ImportResult, LocalCliProxy, LocalLogin } from './cli-proxy.js';
+export { ensureCliProxyHub, readHubInfo } from './cli-proxy-hub.js';
+export type { EnsureOptions, EnsureResult, HubInfo } from './cli-proxy-hub.js';
 export type { CredentialSources } from './agent-credentials.js';

package/dist/index.js

@@ -16,3 +16,6 @@ export { EXIT, AuthConfigError, CheckoutEndedError, ExecutionFailedError, Execut
 export { changedText, errorText, executionJson, executionSummary, feedbackCommand, json, suspendRequestText, suspendWhenIdleText, table, time, usageText, workspaceDetail, workspaceTable } from "./format.js";
 export { TimingRecorder, coldBootNotice, hostLostNotice, lostSuspendNotice, notices, timingJson, timingText } from "./timing.js";
 export { readAgentCredentials, syncAgentCredentials } from "./agent-credentials.js";
+// Hosted CLIProxyAPI (onboarding offers the import when detectLocalCliProxy() finds logins).
+export { detectLocalCliProxy, importCliProxy } from "./cli-proxy.js";
+export { ensureCliProxyHub, readHubInfo } from "./cli-proxy-hub.js";

package/dist/linux-helper.d.ts

@@ -0,0 +1,12 @@
+import type { Ctx } from './commands.js';
+export declare const HELPER_UNIT = "shardflux-helper.service";
+export declare const helperUnitPath: (home: string) => string;
+/** No credentials in the unit: the helper reads the same private store as shard. */
+export declare function helperUnit(ctx: Pick<Ctx, 'runtime' | 'store' | 'apiUrl' | 'io'>): string;
+export type Systemctl = (args: string[]) => boolean;
+export declare function installLinuxHelper(ctx: Ctx, deps?: {
+    platform?: NodeJS.Platform;
+    run?: Systemctl;
+}): boolean;
+/** The caller owns fallback lifetime; never leave an unmanaged background process behind. */
+export declare function startLinuxHelper(ctx: Ctx): () => Promise<void>;

package/dist/linux-helper.js

@@ -0,0 +1,88 @@
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { readFileSync, realpathSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { CLI_VERSION } from "./args.js";
+import { writePrivateFile } from "./credentials.js";
+import { runDeviceHelper } from "./device-helper.js";
+export const HELPER_UNIT = 'shardflux-helper.service';
+export const helperUnitPath = (home) => join(home, '.config/systemd/user', HELPER_UNIT);
+const quote = (s) => '"' + s.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('%', '%%').replaceAll('\n', '\\n').replaceAll('\r', '\\r') + '"';
+/** No credentials in the unit: the helper reads the same private store as shard. */
+export function helperUnit(ctx) {
+    if (!ctx.runtime)
+        throw new Error('An installed shard is required.');
+    let script = ctx.runtime.script;
+    try {
+        script = realpathSync(script);
+    }
+    catch { /* preserve the supplied installed path */ }
+    const env = { HOME: ctx.io.env.HOME, PATH: ctx.io.env.PATH ?? '/usr/local/bin:/usr/bin:/bin', SHARDFLUX_CONFIG_DIR: ctx.store.dir,
+        SHARDFLUX_API_URL: ctx.apiUrl, SHARDFLUX_NO_UPDATE_CHECK: '1',
+        ...Object.fromEntries(['DISPLAY', 'WAYLAND_DISPLAY', 'DBUS_SESSION_BUS_ADDRESS', 'XDG_RUNTIME_DIR', 'CODEX_HOME', 'CLAUDE_CONFIG_DIR'].flatMap(k => ctx.io.env[k] ? [[k, ctx.io.env[k]]] : [])) };
+    return `# Shardflux CLI ${CLI_VERSION}\n[Unit]\nDescription=Shardflux background helper\nAfter=network-online.target\n\n[Service]\nType=simple\nExecStart=${[ctx.runtime.node, script, 'device-helper', '--service'].map(s => quote(s.replaceAll('$', '$$'))).join(' ')}\n${Object.entries(env).map(([k, v]) => `Environment=${quote(`${k}=${v}`)}`).join('\n')}\nRestart=on-failure\nRestartSec=5\nTimeoutStopSec=10\nUMask=0077\n\n[Install]\nWantedBy=default.target\n`;
+}
+export function installLinuxHelper(ctx, deps = {}) {
+    if ((deps.platform ?? process.platform) !== 'linux' || !ctx.runtime || !ctx.io.env.HOME)
+        return false;
+    const run = deps.run ?? (args => spawnSync('systemctl', ['--user', ...args], { env: ctx.io.env, stdio: 'ignore', timeout: 5000 }).status === 0);
+    // Probe before writing: containers without a user manager use the command-lifetime helper.
+    if (!run(['show-environment']))
+        return false;
+    const file = helperUnitPath(ctx.io.env.HOME), text = helperUnit(ctx);
+    const receipt = join(ctx.store.dir, 'linux-helper-started'), digest = createHash('sha256').update(text).digest('hex');
+    let before = '', started = '';
+    try {
+        before = readFileSync(file, 'utf8');
+    }
+    catch { /* first sign-in */ }
+    try {
+        started = readFileSync(receipt, 'utf8');
+    }
+    catch { /* no successful start yet */ }
+    if (before !== text) {
+        writePrivateFile(dirname(file), file, text);
+        if (!run(['daemon-reload']) || !run(['enable', '--now', HELPER_UNIT]))
+            return false;
+        if (before && !run(['restart', HELPER_UNIT]))
+            return false;
+    }
+    else if (!run(['is-active', '--quiet', HELPER_UNIT])) {
+        if (!run(['enable', '--now', HELPER_UNIT]))
+            return false;
+    }
+    else if (started !== digest && !run(['restart', HELPER_UNIT]))
+        return false;
+    // A failed restart must be retried by the next command even though the new unit was already written.
+    if (started !== digest)
+        writePrivateFile(ctx.store.dir, receipt, digest);
+    return true;
+}
+/** The caller owns fallback lifetime; never leave an unmanaged background process behind. */
+export function startLinuxHelper(ctx) {
+    const noop = () => Promise.resolve();
+    if (process.platform !== 'linux' || !ctx.runtime)
+        return noop;
+    try {
+        ctx.apiKey();
+    }
+    catch {
+        return noop;
+    }
+    try {
+        if (installLinuxHelper(ctx))
+            return noop;
+    }
+    catch { /* use the command-lifetime helper */ }
+    const notice = join(ctx.store.dir, 'linux-helper-notice');
+    try {
+        readFileSync(notice);
+    }
+    catch {
+        ctx.io.stderr.write('Shardflux helper runs while shard commands are open on this computer.\n');
+        writePrivateFile(ctx.store.dir, notice, '1\n');
+    }
+    const abort = new AbortController();
+    const work = runDeviceHelper({ ...ctx, signal: AbortSignal.any([ctx.signal, abort.signal]) }, { service: true }).catch(() => undefined);
+    return async () => { abort.abort(); await work; };
+}

package/dist/linux-terminal.d.ts

@@ -0,0 +1,11 @@
+import type { Ctx } from './commands.js';
+import type { Values } from './args.js';
+/** Linux terminals use the existing native Codex harness; explicit app routes keep Cloud. */
+export declare function linuxTerminalSession(ctx: Pick<Ctx, 'io' | 'json'>, values: Values, platform?: NodeJS.Platform): boolean;
+export declare const shellWord: (s: string) => string;
+export declare function linuxTerminalCommand(argv: string[], env: Record<string, string | undefined>): {
+    command: string;
+    args: string[];
+} | null;
+/** Invoked before cloud work: the new terminal owns the attach, credentials and any prompts. */
+export declare function openLinuxTerminal(ctx: Ctx, ref: string, app?: string): Promise<number>;

package/dist/linux-terminal.js

@@ -0,0 +1,42 @@
+import { accessSync, constants } from 'node:fs';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+/** Linux terminals use the existing native Codex harness; explicit app routes keep Cloud. */
+export function linuxTerminalSession(ctx, values, platform = process.platform) {
+    return platform === 'linux' && (values.in === 'terminal' || (values.in === undefined && !!ctx.io.stdin.isTTY && !ctx.json));
+}
+export const shellWord = (s) => `'${s.replaceAll("'", "'\\''")}'`;
+export function linuxTerminalCommand(argv, env) {
+    const executable = (name) => name.includes('/') ? [name] : (env.PATH ?? '').split(':').filter(Boolean).map(p => join(p, name));
+    const exists = (name) => executable(name).some(p => { try {
+        accessSync(p, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    } });
+    // The shell keeps the window open on an attach error so the user can read and retry it.
+    const attach = ['sh', '-c', `${argv.map(shellWord).join(' ')}; status=$?; if [ "$status" -ne 0 ]; then printf '\nPress Enter to close.'; read answer; fi; exit "$status"`];
+    for (const command of [...new Set([env.TERMINAL?.trim(), 'x-terminal-emulator', 'gnome-terminal'].filter((s) => !!s))]) {
+        if (exists(command))
+            return { command, args: [command === 'gnome-terminal' ? '--' : '-e', ...attach] };
+    }
+    return null;
+}
+/** Invoked before cloud work: the new terminal owns the attach, credentials and any prompts. */
+export async function openLinuxTerminal(ctx, ref, app) {
+    const words = ['agents', 'open', ref, '--in', 'terminal', ...(app ? ['--app', app] : [])];
+    const argv = ctx.runtime ? [ctx.runtime.node, ctx.runtime.script, '--api-url', ctx.apiUrl, ...words] : ['shard', ...words];
+    const choice = linuxTerminalCommand(argv, ctx.io.env);
+    if (choice) {
+        const child = spawn(choice.command, choice.args, { env: ctx.io.env, cwd: process.cwd(), detached: true, stdio: 'ignore' });
+        try {
+            await new Promise((resolve, reject) => { child.once('spawn', resolve); child.once('error', reject); });
+            child.unref();
+            return 0;
+        }
+        catch { /* print a runnable command if the terminal could not start */ }
+    }
+    ctx.io.stdout.write(`${['shard', '--api-url', ctx.apiUrl, ...words].map(shellWord).join(' ')}\n`);
+    return 0;
+}

package/dist/main.js

@@ -13,12 +13,16 @@
 import { homedir, hostname } from 'node:os';
 import { statSync } from 'node:fs';
 import { SDK_VERSION, Shardflux, ShardfluxAccount, isSessionToken } from '@shardflux/sdk';
-import { CLI_VERSION, CENTER_COMMAND, PROJECT_COMMAND, commandHelp, parseCommandLine, resolveApiUrl, resolveWake, resolveWakeTimeout } from "./args.js";
+import { CLI_VERSION, CENTER_COMMAND, ONBOARDING_COMMAND, PROJECT_COMMAND, commandHelp, parseCommandLine, resolveApiUrl, resolveWake, resolveWakeTimeout } from "./args.js";
 import { commandCenter } from "./command-center.js";
-import { launchConversationProject } from "./conversation-terminal.js";
+import { launchProjectCommand } from "./conversation-terminal.js";
 import { runAcp } from "./acp.js";
 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";
 import { CredentialStore, configDir } from "./credentials.js";
@@ -660,7 +664,7 @@ export async function run(argv, io, opts = {}) {
             refreshMenubarInBackground({ dir: store.dir, home: io.env.HOME || homedir(), runtime: opts.runtime, env: { ...process.env, ...io.env } });
         }
         // The update check runs next to the command (not for `version`, which reports it itself).
-        if (!updateCheckDisabled(io.env) && !['version', 'update', 'ssh-proxy', 'acp', 'device-helper'].includes(parsed.command.path[0]) && command !== 'menubar refresh') {
+        if (!updateCheckDisabled(io.env) && !['version', 'update', 'ssh-proxy', 'acp', 'device-helper'].includes(parsed.command.path[0]) && command !== 'menubar refresh' && command !== 'cli-proxy forward') {
             try {
                 updates = new UpdateCheck({ dir: store.dir, apiUrl, distribution, fetch: base, userAgent, registry: npmRegistry(io.env) });
                 updates.start();
@@ -673,11 +677,28 @@ export async function run(argv, io, opts = {}) {
     catch (err) {
         return report(err);
     }
-    const handler = parsed.command.path[0] === 'acp' ? (ctx) => parsed.values.login === true ? runAcpLogin(ctx) : runAcp(ctx) : parsed.command.path[0] === 'device-helper' ? runDeviceHelper : command === 'menubar refresh' ? runMenubarRefresh : parsed.command === PROJECT_COMMAND ? launchConversationProject : parsed.command === CENTER_COMMAND ? commandCenter : HANDLERS[parsed.command.path.join(' ')];
+    let stopHelper;
+    const startHelper = () => {
+        if (stopHelper)
+            return;
+        try {
+            ctx.apiKey();
+        }
+        catch {
+            return;
+        }
+        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 ? 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(' ')}"`));
-    if (!['acp', 'device-helper'].includes(parsed.command.path[0]) && command !== 'menubar refresh')
+    // Long-running helpers other programs start (an editor, launchd, the menu bar) skip the per-command housekeeping.
+    if (!['acp', 'device-helper'].includes(parsed.command.path[0]) && command !== 'menubar refresh' && command !== 'cli-proxy forward') {
+        // An updated shard restarts this computer's CLIProxyAPI forwarder on itself (a no-op unless the version changed).
+        await refreshForwarderAgent(io.env, ctx.store.dir).catch(() => false);
         await housekeeping(ctx);
+        startHelper();
+    }
     const running = handler(ctx, parsed.values, parsed.positionals).then((code) => ({ code }), (err) => ({ err }));
     // On Ctrl-C give the command a moment to clean up (exec sends a cancel), then stop regardless.
     const interrupted = new Promise((resolve) => {
@@ -712,6 +733,9 @@ export async function run(argv, io, opts = {}) {
         if (notice)
             io.stderr.write(notice);
     }
+    if (!['acp', 'device-helper'].includes(parsed.command.path[0]) && command !== 'menubar refresh' && command !== 'cli-proxy forward')
+        startHelper();
+    await stopHelper?.();
     return code;
 }
 /**
@@ -738,7 +762,7 @@ export async function main(opts = {}) {
     const runtime = { node: process.execPath, script: process.argv[1] ?? '' };
     // The menu bar's update button runs this shard; it finds it here (macOS only, written when it changes).
     if (process.platform === 'darwin' && runtime.script)
-        recordInstall(configDir(process.env), runtime, opts.distribution ?? CLI_DISTRIBUTION);
+        recordInstall(configDir(process.env), runtime, opts.distribution ?? CLI_DISTRIBUTION, process.env);
     const code = await run(process.argv.slice(2), { stdout: process.stdout, stderr: process.stderr, stdin: process.stdin, env: process.env }, { signal: controller.signal, runtime, ...(opts.distribution ? { distribution: opts.distribution } : {}) });
     await Promise.all([flush(process.stdout), flush(process.stderr)]);
     process.exit(code);

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

@@ -26,10 +26,12 @@ type CredentialRow = {
         checked_at: string;
     };
 };
+/** `url`: a page the person opens (the T3 Connect sign-in), instead of a command. */
 type Action = {
     title: string;
     command?: string[];
     retry?: boolean;
+    url?: string;
 };
 export interface Connection {
     id: 'account' | AgentApp | 't3';

package/dist/onboarding.js

@@ -1,12 +1,17 @@
 import { readFile, stat } from 'node:fs/promises';
 import { delimiter, join, resolve, basename } from 'node:path';
 import { homedir } from 'node:os';
+import { ShardfluxApiError } from '@shardflux/sdk';
 import { resolveWorkspace } from "./commands.js";
+import { AgentStateStore } from "./agent-state.js";
+import { describeError } from "./errors.js";
+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.
@@ -63,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.
@@ -79,15 +85,59 @@ export async function t3Connection(ctx, signedIn, appDirs = applicationDirs(ctx.
             return { ...base, mode: 'provider', state: 'action', fact: error instanceof Error ? error.message : 'T3 Code’s settings could not be updated.', action: { title: 'Check again' } };
         }
     }
-    // Stable T3: an SSH environment per project; the newest one this API set up is the one to add.
+    // Stable T3: an SSH environment per project; the newest one this API set up is the one to add. They are recorded in
+    // agents.json (targets.json keeps T3 out of its manifest); a manifest entry from an older CLI still counts.
+    const recorded = new AgentStateStore(ctx.store.dir).t3Environments(ctx.apiUrl).at(-1);
     const manifest = await jsonFile(join(ctx.store.dir, 'targets.json'));
     const entries = Array.isArray(manifest?.entries) ? manifest.entries : [];
-    const host = entries.filter(e => e.api_url === ctx.apiUrl && Array.isArray(e.targets) && e.targets.includes('t3') && typeof e.host === 'string').map(e => e.host).at(-1);
-    if (host)
-        return { ...base, mode: 'ssh', state: 'verified', fact: `In T3 Code: Add environment → SSH → ${host}` };
+    const legacy = entries.filter(e => e.api_url === ctx.apiUrl && Array.isArray(e.targets) && e.targets.includes('t3') && typeof e.host === 'string').at(-1);
+    const host = recorded?.host ?? legacy?.host;
+    const workspaceKey = recorded?.workspace ?? (typeof legacy?.workspace === 'string' ? legacy.workspace : undefined);
+    if (host) {
+        const desktop = `In T3 Code: Add environment → SSH → ${host}`;
+        const phone = await t3Phone(ctx, workspaceKey);
+        if (!phone)
+            return { ...base, mode: 'ssh', state: 'verified', fact: desktop };
+        return { ...base, mode: 'ssh', ...phone, fact: phone.state === 'verified' ? `${desktop}. On your phone: ${phone.fact}` : phone.fact };
+    }
     // An SSH environment is per project (shardflux-<project>-main): it is set up once a project is picked.
     return { ...base, mode: 'ssh', state: 'info', fact: 'Available after you pick a project.', next: shard(['agents', 'new', '--in', 't3', '--path', '<project>']) };
 }
+/**
+ * The T3 app on the phone (T3 Connect, 0.17.0+): the workspace is linked with the person's one T3 Connect sign-in. The
+ * sign-in is a page to open once; afterwards every project appears in the T3 app by itself. Undefined when the API has
+ * no T3 Connect: the desktop route is the whole card then.
+ */
+async function t3Phone(ctx, key) {
+    if (!key)
+        return undefined;
+    try {
+        const ws = await resolveWorkspace(ctx, key);
+        const cloud = ctx.cloud();
+        const known = (await cloud.t3.status()).links.find(l => l.workspace_id === ws.id);
+        // A workspace connected to T3 before T3 Connect, or one whose link failed, is linked now: it is the person's choice.
+        const { link, signIn, needsLogin } = !known || known.status === 'error' || known.status === 'needs_sign_in'
+            ? await t3PhoneLink(ctx, ws.id) : { link: known, signIn: undefined, needsLogin: false };
+        if (link.status === 'linked')
+            return { state: 'verified', fact: `${link.label} in the T3 app.` };
+        if (signIn) {
+            return { state: 'action', fact: `To use it from the T3 app on your phone, confirm ${signIn.user_code} once.`,
+                action: { title: 'Connect phone', url: signIn.verification_uri } };
+        }
+        if (needsLogin)
+            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) {
+        // No T3 Connect on this API, or nothing to ask it: the desktop route stands on its own.
+        if (!(error instanceof ShardfluxApiError) || describeError(error).code === 'not_found')
+            return undefined;
+        // Another member's T3 Connect sign-in links this project: it is in their T3 app, not something to fix here.
+        if (error.details?.reason === 't3_linked_by_other_member')
+            return { state: 'info', fact: 'In the T3 app of the member who linked it.' };
+        return { state: 'unknown', fact: 'The T3 app link could not be checked just now.', action: { title: 'Retry', retry: true } };
+    }
+}
 const shard = (words) => ['shard', ...words];
 /** Claude: the account login is ready and Claude itself accepts it right now. */
 export function claudeConnection(row) {
@@ -105,7 +155,7 @@ export function codexConnection(local, synced, connector, health) {
     const enable = { title: 'Connect Codex', command: shard(['agents', 'codex', 'enable']) };
     if (!synced) {
         return local ? { state: 'action', fact: 'Available on web and phone once connected.', action: enable }
-            : { state: 'action', fact: 'Sign in to Codex on this Mac first.', action: { title: 'Sign in to Codex', command: ['codex', 'login'] } };
+            : { state: 'action', fact: 'Sign in to Codex on this computer first.', action: { title: 'Sign in to Codex', command: ['codex', 'login'] } };
     }
     const retry = { title: 'Retry', retry: true, command: shard(['setup', '--inspect', '--apps', 'codex', '--connect', '--retry-codex']) };
     switch (health) {

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;