@shardflux/cli 0.16.0 → 0.18.0-next.4

package/dist/codex-cloud.d.ts

@@ -1,13 +1,14 @@
 import type { CodexCloudTask } from '@shardflux/sdk';
 import type { Ctx, Handler } from './commands.js';
 import type { Values } from './args.js';
+import type { ModelChoice } from './agent-models.js';
 import type { Conversation } from './conversations.js';
 import type { InitialImage } from './initial-prompt.js';
 /** Only provider-returned task ids enter the registered Codex deep-link route. */
 export declare function openCodexThread(task: CodexCloudTask, env: Ctx['io']['env']): Promise<void>;
 export declare function submitCloudInitialPrompt(ctx: Ctx, c: Conversation, prompt: string, workspaceKey: string): Promise<void>;
 /** Prints the Cloud thread (and its link) and opens it in the Codex app; --json prints it instead. */
-export declare function printCloudThread(ctx: Ctx, c: Conversation, task: CodexCloudTask, submitted?: boolean): Promise<void>;
+export declare function printCloudThread(ctx: Ctx, c: Conversation, task: CodexCloudTask, submitted?: boolean, choice?: ModelChoice): Promise<void>;
 /** How long the account's Codex remote device may take to come up before it counts as stuck. */
 export declare const CODEX_STARTING_LIMIT_MS: number;
 export type CodexConnectorView = {

package/dist/codex-cloud.js

@@ -2,7 +2,8 @@ import { spawn } from 'node:child_process';
 import { CodedError, UsageError } from "./errors.js";
 import { json } from "./format.js";
 import { syncAgentCredentials } from "./agent-credentials.js";
-import { createConversation, resumeConversation } from "./conversations.js";
+import { createConversation, getConversation, recordedChoice, resumeConversation } from "./conversations.js";
+import { CHOICE_PENDING, choiceReport, hasChoice, modelChoice } from "./agent-models.js";
 import { AgentStateStore } from "./agent-state.js";
 import { ensureProjectGit } from "./project-git.js";
 import { gitRunner } from "./agent-git.js";
@@ -33,16 +34,24 @@ export async function submitCloudInitialPrompt(ctx, c, prompt, workspaceKey) {
     }
 }
 /** Prints the Cloud thread (and its link) and opens it in the Codex app; --json prints it instead. */
-export async function printCloudThread(ctx, c, task, submitted = false) { return output(ctx, c, task, submitted); }
-async function output(ctx, c, task, submitted = false) {
+export async function printCloudThread(ctx, c, task, submitted = false, choice) { return output(ctx, c, task, submitted, choice); }
+async function output(ctx, c, task, submitted = false, choice) {
     const url = threadLink(task);
+    // model_choice (0.17.0+): an admitted thread's record keeps the model and effort only when Cloud started it with them.
+    const applied = hasChoice(choice) ? await cloudChoiceApplied(ctx, c, choice) : true;
     if (ctx.json) {
-        ctx.io.stdout.write(json({ conversation: c, cloud: task, url, ...(submitted ? { initial_prompt: { submitted: true } } : {}) }));
+        ctx.io.stdout.write(json({ conversation: c, cloud: task, url, ...(submitted ? { initial_prompt: { submitted: true } } : {}), ...(hasChoice(choice) ? { model_choice: choiceReport(choice, applied) } : {}) }));
         return;
     }
+    if (!applied)
+        ctx.io.stderr.write(`${CHOICE_PENDING}\n`);
     ctx.io.stdout.write(`${c.key}\n${task.desktop_url}\n`);
     await openCodexThread(task, ctx.io.env);
 }
+async function cloudChoiceApplied(ctx, c, choice) {
+    const kept = recordedChoice(await getConversation(ctx, c.id));
+    return kept.model === choice.model && kept.effort === choice.effort;
+}
 /** How long the account's Codex remote device may take to come up before it counts as stuck. */
 export const CODEX_STARTING_LIMIT_MS = 5 * 60_000;
 /** When a connector generation started: its UUIDv7 time. */
@@ -114,11 +123,12 @@ export async function launchCodexCloud(ctx, values, path, images = []) {
         throw new UsageError('New Codex conversations open in Codex Cloud. Omit --in or use --in codex-app.');
     if (values.like !== undefined)
         throw new UsageError('Choose the project directory with --path; new Codex conversations use its latest machine template.');
+    const choice = modelChoice(values, 'codex');
     const project = projectIdentity(path);
     await ensureProjectGit(ctx, project.folder);
     await gitRunner(project.folder, { ...process.env, ...ctx.io.env }, ctx.signal)(['rev-parse', 'HEAD']);
     await ensureCodexCloud(ctx);
-    const created = await createConversation(ctx, path, 'codex', 'codex-cloud', typeof values.name === 'string' ? values.name : undefined);
+    const created = await createConversation(ctx, path, 'codex', 'codex-cloud', typeof values.name === 'string' ? values.name : undefined, choice);
     const c = created.conversation;
     // --computer: the conversation VM's desktop is on before Codex starts, so the thread gets the computer tools.
     if (values.computer === true)
@@ -132,7 +142,7 @@ export async function launchCodexCloud(ctx, values, path, images = []) {
     const submitted = typeof values.initialPrompt === 'string';
     if (submitted)
         await submitCloudInitialPrompt(ctx, c, values.initialPrompt, created.workspace.key);
-    await output(ctx, c, task, submitted);
+    await output(ctx, c, task, submitted, choice);
     return 0;
 }
 export async function openCodexConversation(ctx, c) {

package/dist/command-center-actions.js

@@ -11,8 +11,9 @@ import { agentName as gitAgentName } from "./agent-git.js";
 import { randomUUID } from 'node:crypto';
 import { prepareAgentMachine } from "./agent-machine.js";
 import { OperationFailedError } from '@shardflux/sdk';
-import { launchConversationProject } from "./conversation-terminal.js";
+import { launchConversationProject, launchProjectCommand } from "./conversation-terminal.js";
 import { startThreadOn } from "./thread-on-computer.js";
+import { launchT3 } from "./t3-launch.js";
 /** L9 can register target-specific handlers after detecting the installed applications. */
 export async function availableTargets(ctx) {
     const { HANDLERS } = await import("./handlers.js");
@@ -35,6 +36,20 @@ export async function agentAction(ctx, action, values, args) {
 }
 export const CENTER_HANDLERS = {
     async 'agents new'(ctx, values, [ref]) {
+        const fresh = !ref && values.name === undefined && values.like === undefined;
+        // T3 Code mode (0.17.0+): --in t3 starts the first message as a T3 thread (--on: on that computer's T3 server);
+        // --in auto opens where open_in says.
+        if (fresh && values.in === 't3')
+            return launchT3(ctx, values, str(values.path) ?? './', str(values.app));
+        if (fresh && values.in === 'auto') {
+            const next = { ...values };
+            delete next.in;
+            return launchProjectCommand(ctx, next, [str(values.path) ?? './', ...(str(values.app) ? [str(values.app)] : [])]);
+        }
+        if (values.in === 'auto') {
+            values = { ...values };
+            delete values.in;
+        }
         // A thread on an existing conversation's computer (0.16.0+).
         if (values.on !== undefined) {
             if (ref || values.like !== undefined)

package/dist/conversation-local.js

@@ -1,5 +1,5 @@
 import { setTimeout as delay } from 'node:timers/promises';
-import { getConversation, resolveConversation, conversationWorkspace, localConversations } from "./conversations.js";
+import { conversationEnded, getConversation, resolveConversation, conversationWorkspace, localConversations } from "./conversations.js";
 import { ensureConversationWorktree, devicePort } from "./device-bridge.js";
 import { startProjectSync } from "./project-sync.js";
 import { projectIdentity } from "./project-identity.js";
@@ -48,7 +48,7 @@ export const CONVERSATION_HANDLERS = {
         try {
             while (!ctx.signal.aborted) {
                 const next = await getConversation(ctx, c.id);
-                if (next.state === 'done' || next.state === 'archived' || next.workspace_id !== c.workspace_id)
+                if (conversationEnded(next) || next.workspace_id !== c.workspace_id)
                     break;
                 await delay(1000, undefined, { signal: ctx.signal }).catch(() => undefined);
             }

package/dist/conversation-stash.js

@@ -182,7 +182,7 @@ export async function mirrorProjectConversations(ctx, state = new ConversationMi
         const c = all.find(c => c.id === record.conversation.id);
         if (!c || record.handed_off || !c.harness_session_id)
             continue;
-        const revision = JSON.stringify([c.workspace_id, c.harness_session_id, c.state, c.durable, c.last_activity_at, c.summary]);
+        const revision = JSON.stringify([c.workspace_id, c.harness_session_id, c.state, c.durable, c.last_activity_at, c.summary, c.ended_at]);
         if (state.mirrored.get(c.id) === revision)
             continue;
         let retry = state.retries.get(c.id);
@@ -220,8 +220,9 @@ export async function mirrorProjectConversations(ctx, state = new ConversationMi
             await mirrorConversation(ctx, { ...record, conversation: c }, source, skipped);
             retry.failures = 0;
             retry.retryAt = 0;
-            // An ended record may precede its VM tombstone; retry until the handoff receipt is written.
-            if (c.state !== 'done' && c.state !== 'archived')
+            // An ended record may precede its VM tombstone; retry until the handoff receipt is written. A finished turn is
+            // `done` while its VM lives: mirrored once per revision, and again when it ends.
+            if (c.state !== 'archived' && !(c.state === 'done' && c.ended_at))
                 state.mirrored.set(c.id, revision);
         }
         catch (e) {

package/dist/conversation-terminal.d.ts

@@ -4,5 +4,10 @@ import type { Values } from './args.js';
 import type { Conversation } from './conversations.js';
 /** Every terminal entry point uses the durable conversation's native harness, worktree and session. */
 export declare function conversationTerminal(ctx: Ctx, ws: Workspace, c: Conversation, project: string, values: Values): Promise<number>;
+/**
+ * `shard ./` (and `agents new --in auto`): new conversations open where `agents targets` says (open_in, 0.17.0+): T3
+ * Code mode, Claude Desktop or claude.ai for Claude (the conversation's Remote Control session), else this terminal.
+ */
+export declare const launchProjectCommand: Handler;
 /** Select a durable conversation, then use the harness's native terminal for all interaction. */
 export declare const launchConversationProject: Handler;

package/dist/conversation-terminal.js

@@ -1,7 +1,9 @@
+import { linuxTerminalSession } from "./linux-terminal.js";
 import { randomUUID } from 'node:crypto';
 import { AgentStateStore } from "./agent-state.js";
 import { projectIdentity, projectLabels } from "./project-identity.js";
-import { createConversation, conversationName, conversationWorkspace, conversationsUnavailable, listConversations, localConversations, rememberConversation, resumeConversation, restoreConversationBinding } from "./conversations.js";
+import { createConversation, conversationName, conversationWorkspace, conversationsUnavailable, listConversations, localConversations, recordedChoice, rememberConversation, resumeConversation, restoreConversationBinding } from "./conversations.js";
+import { modelChoice } from "./agent-models.js";
 import { terminal } from "./agent-commands.js";
 import { cloudClaudeLogin, loginClaudeInWorkspace, requireClaudeTerminal } from "./claude-cloud-login.js";
 import { syncAgentCredentials } from "./agent-credentials.js";
@@ -16,6 +18,11 @@ import { agentReachability } from "./agent-reachability.js";
 import { promptWithImages, readInitialImages, readInitialPrompt, uploadInitialImages } from "./initial-prompt.js";
 import { launchCodexCloud, openCodexConversation } from "./codex-cloud.js";
 import { startThreadOn } from "./thread-on-computer.js";
+import { openInChoices } from "./t3-mode.js";
+import { launchT3 } from "./t3-launch.js";
+import { openClaudeDesktopSession, remoteControlUrl } from "./agent-target-commands.js";
+import { openUrl } from "./browser.js";
+import { out } from "./commands.js";
 /** Every terminal entry point uses the durable conversation's native harness, worktree and session. */
 export async function conversationTerminal(ctx, ws, c, project, values) {
     if (c.route === 'codex-cloud')
@@ -23,10 +30,28 @@ export async function conversationTerminal(ctx, ws, c, project, values) {
     await restoreConversationBinding(ctx, c, ws);
     // A thread on another conversation's computer has its own PTY there, never the VM's own (0.16.0+).
     const pty = ws.labels.shard_conversation && ws.labels.shard_conversation !== c.id ? conversationName(c) : undefined;
-    return terminal(ctx, ws, c.harness, conversationName(c), project, values, undefined, c.worktree_path, { id: c.id, session: c.harness_session_id, title: c.title, ...(pty ? { pty } : {}) });
+    return terminal(ctx, ws, c.harness, conversationName(c), project, values, undefined, c.worktree_path, { id: c.id, session: c.harness_session_id, title: c.title, ...(pty ? { pty } : {}), choice: recordedChoice(c) });
 }
+/**
+ * `shard ./` (and `agents new --in auto`): new conversations open where `agents targets` says (open_in, 0.17.0+): T3
+ * Code mode, Claude Desktop or claude.ai for Claude (the conversation's Remote Control session), else this terminal.
+ */
+export const launchProjectCommand = async (ctx, values, [path = './', explicit]) => {
+    const named = explicit ?? (values.claude === true ? 'claude' : values.codex === true ? 'codex' : undefined);
+    if (values.resume !== true && values.review !== true) {
+        const project = projectIdentity(path);
+        const app = named === 'claude' || named === 'codex' ? named : new AgentStateStore(ctx.store.dir).app(project.remote ?? project.folder);
+        const where = process.platform === 'linux' && ctx.io.stdin.isTTY ? 'terminal' : openInChoices(ctx, project.slug)[app];
+        if (where === 't3')
+            return launchT3(ctx, values, path, app);
+        if (values.on === undefined && app === 'claude' && (where === 'claude-desktop' || where === 'web'))
+            return startConversation(ctx, values, [path, ...(explicit ? [explicit] : [])], where);
+    }
+    return launchConversationProject(ctx, values, [path, ...(explicit ? [explicit] : [])]);
+};
 /** Select a durable conversation, then use the harness's native terminal for all interaction. */
-export const launchConversationProject = async (ctx, values, [path = './', explicit]) => {
+export const launchConversationProject = (ctx, values, args) => startConversation(ctx, values, args);
+async function startConversation(ctx, values, [path = './', explicit], openIn) {
     if (values.on !== undefined) {
         const app = explicit ?? (values.claude === true ? 'claude' : values.codex === true ? 'codex' : undefined);
         return startThreadOn(ctx, values, path, app);
@@ -42,6 +67,8 @@ export const launchConversationProject = async (ctx, values, [path = './', expli
     const app = explicit === 'claude' || explicit === 'codex' ? explicit : store.app(project.remote ?? project.folder);
     if (explicit && explicit !== app)
         throw new UsageError('Choose claude or codex.');
+    // Checked before a VM is allocated; the new conversation's record carries it to its guest (0.17.0+).
+    const choice = modelChoice(values, app);
     if (values.resume === true) {
         // The native pickers are VM-local. C-K6's project picker must select the binding first.
         const records = localConversations(ctx);
@@ -62,7 +89,7 @@ export const launchConversationProject = async (ctx, values, [path = './', expli
         const ws = await conversationWorkspace(ctx, next);
         return conversationTerminal(ctx, ws, next, project.remote ?? project.folder, values);
     }
-    if (app === 'codex')
+    if (app === 'codex' && !linuxTerminalSession(ctx, values))
         return launchCodexCloud(ctx, values, path, images);
     await syncAgentCredentials(ctx.cloud(), { home: ctx.io.env.HOME, redact: value => ctx.addSecret(value) });
     const signedIn = app === 'claude' ? await cloudClaudeLogin(ctx) : true;
@@ -70,7 +97,7 @@ export const launchConversationProject = async (ctx, values, [path = './', expli
         requireClaudeTerminal(ctx);
     let created;
     try {
-        created = await createConversation(ctx, project.folder, app, 'terminal');
+        created = await createConversation(ctx, project.folder, app, 'terminal', undefined, choice);
     }
     catch (e) {
         if (!conversationsUnavailable(e))
@@ -102,5 +129,17 @@ export const launchConversationProject = async (ctx, values, [path = './', expli
     if (!(await savedMachine(ctx))?.template)
         await syncAgentConfig(ctx, ws);
     await ensureMenubar(ctx.store.dir, ctx.apiUrl, new MenubarManager({ home: ctx.io.env.HOME, signal: ctx.signal }));
+    if (openIn) {
+        // The agent starts detached in its VM; the conversation then opens in Claude Desktop or claude.ai (Remote Control).
+        const quiet = { ...ctx, io: { ...ctx.io, stdout: { write: () => true } } };
+        await conversationTerminal(quiet, ws, c, project.remote ?? project.folder, { ...values, detach: true });
+        if (openIn === 'claude-desktop')
+            return openClaudeDesktopSession(ctx, ws, c);
+        const url = await remoteControlUrl(ctx, ws, c);
+        if (!ctx.json && !openUrl(url, ctx.io.env))
+            throw new Error(`could not open ${url}`);
+        out(ctx, `${url}\n`, { target: 'web', workspace: ws.data, conversation_id: c.id, url });
+        return 0;
+    }
     return conversationTerminal(ctx, ws, c, project.remote ?? project.folder, values);
-};
+}

package/dist/conversations.d.ts

@@ -1,5 +1,6 @@
 import type { Workspace, WorkspaceView } from '@shardflux/sdk';
 import type { Ctx } from './commands.js';
+import type { ModelChoice } from './agent-models.js';
 export type Harness = 'claude' | 'codex';
 export interface Conversation {
     id: string;
@@ -17,6 +18,11 @@ export interface Conversation {
     state: 'working' | 'needs_you' | 'unresolved' | 'done' | 'archived';
     created_at: string;
     ended_at: string | null;
+    landed?: {
+        how: string;
+        at: string;
+        ref: string;
+    } | null;
     last_activity_at?: string;
     durable?: {
         branch_sha: string;
@@ -31,6 +37,9 @@ export interface Conversation {
     base_branch?: string | null;
     role?: string;
     join_mode?: string | null;
+    /** The model and effort its harness starts with; null is the agent's own default (0.17.0+, APIs that keep them). */
+    model?: string | null;
+    effort?: string | null;
 }
 export interface LocalConversation {
     api_url: string;
@@ -41,6 +50,11 @@ export interface LocalConversation {
     /** The branch the conversation started from (0.16.0+), for APIs that do not return base_branch yet. */
     base_branch?: string;
 }
+/**
+ * Whether the conversation has ended: its VM was reclaimed, or it was archived or discarded. A finished turn is `done`
+ * while its VM still takes the next turn; on Codex Cloud, `done` ends the conversation.
+ */
+export declare const conversationEnded: (c: Pick<Conversation, "state" | "ended_at" | "route" | "landed">) => boolean;
 export declare const conversationName: (c: Conversation) => string;
 export declare function validateConversation(c: Conversation): Conversation;
 export declare function localConversations(ctx: Pick<Ctx, 'store' | 'apiUrl'>): Record<string, LocalConversation>;
@@ -57,9 +71,11 @@ export declare function conversationWorkspace(ctx: Ctx, c: Conversation): Promis
  */
 export declare function waitThreadReady(ctx: Ctx, c: Conversation, pollMs?: number): Promise<Conversation>;
 export declare function restoreConversationBinding(ctx: Ctx, c: Conversation, ws: Workspace): Promise<void>;
-export declare function createConversationRecord(ctx: Ctx, folder: string, harness: Harness, route: Conversation['route'], name?: string, allocated?: (workspace: WorkspaceView) => void, idempotencyKey?: string): Promise<Conversation>;
-export declare function createConversation(ctx: Ctx, folder: string, harness: Harness, route: Conversation['route'], name?: string): Promise<{
+export declare function createConversationRecord(ctx: Ctx, folder: string, harness: Harness, route: Conversation['route'], name?: string, allocated?: (workspace: WorkspaceView) => void, idempotencyKey?: string, choice?: ModelChoice): Promise<Conversation>;
+export declare function createConversation(ctx: Ctx, folder: string, harness: Harness, route: Conversation['route'], name?: string, choice?: ModelChoice): Promise<{
     conversation: Conversation;
     workspace: Workspace;
 }>;
 export declare function resumeConversation(ctx: Ctx, c: Conversation): Promise<Conversation>;
+/** The model and effort a conversation's harness starts with, as its record keeps them. */
+export declare const recordedChoice: (c: Pick<Conversation, "model" | "effort">) => ModelChoice;

package/dist/conversations.js

@@ -9,6 +9,11 @@ import { UsageError } from "./errors.js";
 import { conversationClient } from "./conversation-commands.js";
 import { recordSeedSnapshot } from "./files-mirror.js";
 import { rememberTwinSeed, sendTwinSeed, twinCheckoutArgv, twinSeed } from "./worktree-twin.js";
+/**
+ * Whether the conversation has ended: its VM was reclaimed, or it was archived or discarded. A finished turn is `done`
+ * while its VM still takes the next turn; on Codex Cloud, `done` ends the conversation.
+ */
+export const conversationEnded = (c) => !!c.ended_at || c.state === 'archived' || c.landed?.how === 'discarded' || (c.route === 'codex-cloud' && c.state === 'done');
 export const conversationName = (c) => {
     const name = c.key.split('/').at(-1);
     if (!/^[a-z0-9][a-z0-9-]{0,47}$/.test(name) || c.branch !== `shard/${name}`)
@@ -116,7 +121,7 @@ export async function restoreConversationBinding(ctx, c, ws) {
     if (result.exitCode !== 0)
         throw new Error(`Conversation restore failed: ${result.stderr.trim()}`);
 }
-export async function createConversationRecord(ctx, folder, harness, route, name, allocated, idempotencyKey = randomUUID()) {
+export async function createConversationRecord(ctx, folder, harness, route, name, allocated, idempotencyKey = randomUUID(), choice = {}) {
     const project = projectIdentity(folder);
     await ensureProjectGit(ctx, project.folder);
     // Both the conversation API and its legacy workspace fallback need a usable local HEAD.
@@ -128,16 +133,16 @@ export async function createConversationRecord(ctx, folder, harness, route, name
     const seed = await twinSeed(ctx.store.dir, project.folder, head, ctx.store.profile(ctx.apiUrl).project_id).catch(() => ({ commit: head, snapshot: false }));
     const commit = seed.commit;
     const response = await conversationClient(ctx).conversations.create({ repoRemote: project.remote ?? `file://${project.folder}`, harness, route, mode: 'new',
-        base: { commit, ...(branch ? { branch } : {}) }, ...(name ? { name } : {}), projectId: ctx.store.profile(ctx.apiUrl).project_id }, { idempotencyKey, signal: ctx.signal });
+        base: { commit, ...(branch ? { branch } : {}) }, ...(name ? { name } : {}), ...choice, projectId: ctx.store.profile(ctx.apiUrl).project_id }, { idempotencyKey, signal: ctx.signal });
     const c = validateConversation({ ...response.conversation, restore: response.restore });
     allocated?.(response.workspace);
     rememberTwinSeed(ctx.store.dir, c.id, project.folder, seed, branch);
     rememberConversation(ctx, c, project.folder, false, branch);
     return c;
 }
-export async function createConversation(ctx, folder, harness, route, name) {
+export async function createConversation(ctx, folder, harness, route, name, choice = {}) {
     const project = projectIdentity(folder);
-    const c = await createConversationRecord(ctx, project.folder, harness, route, name);
+    const c = await createConversationRecord(ctx, project.folder, harness, route, name, undefined, undefined, choice);
     try {
         const ws = await conversationWorkspace(ctx, c);
         // This is a one-time seed. A conversation never watches or writes the owner's checkout.
@@ -163,8 +168,10 @@ export async function createConversation(ctx, folder, harness, route, name) {
     }
 }
 export async function resumeConversation(ctx, c) {
-    if (c.state !== 'done' && c.state !== 'archived')
+    if (!conversationEnded(c))
         return getConversation(ctx, c.id);
     const response = await conversationClient(ctx).conversations.resume(c.id, { idempotencyKey: randomUUID(), signal: ctx.signal });
     return validateConversation({ ...response.conversation, restore: response.restore });
 }
+/** The model and effort a conversation's harness starts with, as its record keeps them. */
+export const recordedChoice = (c) => ({ ...(c.model ? { model: c.model } : {}), ...(c.effort ? { effort: c.effort } : {}) });

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

@@ -0,0 +1,12 @@
+import type { DeviceApproval, DeviceChoice } from './device-bridge.js';
+import type { Ctx, Handler } from './commands.js';
+type Pending = DeviceApproval & {
+    nonce: string;
+    pid: number;
+};
+export declare function pendingDeviceApprovals(dir: string): Pending[];
+export declare function answerDeviceApproval(dir: string, id: string, choice: DeviceChoice): void;
+/** Local user-owned files carry approvals; cloud data can never answer its own request. */
+export declare function askLocalDeviceApproval(ctx: Ctx, approval: DeviceApproval): Promise<DeviceChoice>;
+export declare const DEVICE_HANDLERS: Record<string, Handler>;
+export {};