@shardflux/cli 0.17.0 → 0.18.0-next.4

package/dist/t3-asar.js

@@ -0,0 +1,91 @@
+/**
+ * T3 Code's app.asar, read in place (nothing is extracted or run): the app's release version (its package.json) and
+ * whether its server has the ACP Registry provider driver. The same archive ships in the macOS bundle
+ * (Contents/Resources/app.asar) and in the Linux packages (`/opt/T3 Code (Alpha)/resources/app.asar` from the .deb).
+ * Answers are kept for the process per archive, keyed by its size and modification time.
+ */
+import { closeSync, openSync, readFileSync, readSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+/** The server CLI inside the archive: what Electron runs as Node to issue T3 sessions. */
+export const T3_SERVER_ENTRY = 'apps/server/dist/bin.mjs';
+const RELEASE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+const DRIVER = ['ProviderDriverKind.make("acpRegistry")', "ProviderDriverKind.make('acpRegistry')"].map(s => Buffer.from(s));
+const MAX_FILE = 64 << 20;
+const known = new Map();
+/** One fact about an archive, computed from its header once per size and modification time; `fallback` when unreadable. */
+function fact(archive, key, compute, fallback) {
+    let fd;
+    try {
+        const stat = statSync(archive), stamp = `${stat.size}:${stat.mtimeMs}`;
+        const seen = known.get(archive)?.stamp === stamp ? known.get(archive) : { stamp };
+        if (seen[key] !== undefined)
+            return seen[key];
+        fd = openSync(archive, 'r');
+        const sizes = Buffer.alloc(16);
+        if (readSync(fd, sizes, 0, 16, 0) !== 16)
+            return fallback;
+        const headerSize = sizes.readUInt32LE(12);
+        if (headerSize < 1 || headerSize > 16 << 20)
+            return fallback;
+        const header = Buffer.alloc(headerSize);
+        if (readSync(fd, header, 0, headerSize, 16) !== headerSize)
+            return fallback;
+        const value = compute({ path: archive, fd, size: stat.size, base: 8 + sizes.readUInt32LE(4), header: JSON.parse(header.toString()) });
+        known.set(archive, { ...seen, [key]: value });
+        return value;
+    }
+    catch {
+        return fallback;
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+function entry(a, path) {
+    let e = a.header;
+    for (const part of path.split('/'))
+        e = e?.files?.[part];
+    return e && !e.files ? e : undefined;
+}
+/** One file's bytes, from the archive or its `.unpacked` folder; undefined when it is missing or out of bounds. */
+function read(a, path) {
+    const e = entry(a, path), size = e?.size;
+    if (!e || !Number.isSafeInteger(size) || !size || size < 1 || size > MAX_FILE)
+        return undefined;
+    if (e.unpacked)
+        return readFileSync(join(`${a.path}.unpacked`, path));
+    const offset = Number(e.offset) + a.base;
+    if (!Number.isSafeInteger(offset) || offset < 16 || offset + size > a.size)
+        return undefined;
+    const bytes = Buffer.alloc(size);
+    return readSync(a.fd, bytes, 0, size, offset) === size ? bytes : undefined;
+}
+/** The app's release version (package.json `version`, e.g. `0.0.46-nightly.20261010.2908`), or null. */
+export function asarVersion(archive) {
+    return fact(archive, 'version', a => {
+        const version = JSON.parse(read(a, 'package.json')?.toString() ?? '{}').version;
+        return typeof version === 'string' && RELEASE.test(version) ? version : null;
+    }, null) ?? 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 function t3ArchiveSupportsAcp(archive) {
+    return fact(archive, 'acp', a => {
+        const has = (bytes) => !!bytes && DRIVER.some(marker => bytes.includes(marker));
+        const bin = read(a, T3_SERVER_ENTRY);
+        if (!bin)
+            return false;
+        if (has(bin))
+            return true;
+        // A whole server in bin.mjs (0.0.45: 9 MB) without the driver has none; only a thin entry defers to chunks.
+        if (bin.length > 256 << 10)
+            return false;
+        const dir = T3_SERVER_ENTRY.slice(0, T3_SERVER_ENTRY.lastIndexOf('/') + 1);
+        const chunks = [...bin.toString().matchAll(/(?:\bimport\s*\(\s*|\bfrom\s*)["']\.\/([\w.-]+\.m?js)["']/g)].map(m => m[1]);
+        return [...new Set(chunks)].slice(0, 16).some(chunk => has(read(a, dir + chunk)));
+    }, false) === true;
+}

package/dist/t3-launch.js

@@ -115,7 +115,7 @@ export async function openT3Conversation(ctx, conversationId, values = {}) {
             throw withT3Context(error, { conversation_id: conversationId });
         }
         try {
-            await openT3(ctx.io.env, install.path);
+            await openT3(ctx.io.env, install);
         }
         catch (error) {
             throw threadId ? t3OpenFailed(error, { t3_thread_id: threadId, conversation_id: conversationId }) : error;

package/dist/t3-linux.d.ts

@@ -0,0 +1,68 @@
+type Env = Record<string, string | undefined>;
+export type T3LinuxFormat = 'deb' | 'directory' | 'appimage' | 'flatpak' | 'snap';
+export interface T3LinuxApp {
+    format: T3LinuxFormat;
+    /** The desktop entry's file name (the id `gtk-launch` takes); null for an AppImage found by its file name. */
+    desktop_id: string | null;
+    /** What starts it: the entry's Exec without field codes, or the AppImage. */
+    exec: string[];
+    /** The app's resources/app.asar on this computer (deb, other unpacked installs, flatpak); null for an AppImage or snap. */
+    asar: string | null;
+    /** Flatpak: the app id and the app's files folder on this computer (mounted at /app in its sandbox). */
+    flatpak?: {
+        id: string;
+        files: string;
+    };
+}
+/** A Linux T3 Code: `path` is the program it runs (the executable, or the AppImage). */
+export interface T3LinuxInstall {
+    path: string;
+    version: string | null;
+    linux: T3LinuxApp;
+}
+/** The launcher T3 (nightlies since October 2026) writes to `<T3 home>/bin/t3` for its bundled CLI; for an AppImage it mounts the image itself. */
+export declare const T3_LAUNCHER_MARKER = "Written by T3 Code: runs the desktop app's bundled t3 CLI.";
+/**
+ * The folders scanned on Linux, in XDG precedence: the data home's and each data dir's `applications`, snapd's and
+ * flatpak's exported entries, then the usual AppImage folders. SHARDFLUX_APPLICATIONS_DIRS replaces all of them.
+ */
+export declare function linuxApplicationDirs(env: Env): string[];
+/** The `[Desktop Entry]` group's unlocalized keys (string escapes undone), first value of each key. */
+export declare function desktopEntry(text: string): Record<string, string>;
+/** An entry's Exec as argv (the Desktop Entry quoting rules), field codes and flatpak's @@ markers removed; undefined when malformed. */
+export declare function desktopExec(value: string): string[] | undefined;
+/** The installed T3 Code apps on Linux, from the desktop entries and AppImages in `dirs` (linuxApplicationDirs). */
+export declare function linuxT3Apps(dirs: string[], env: Env): T3LinuxInstall[];
+/**
+ * Whether this install runs the Shardflux provider (ACP mode): the server in its app.asar has the ACP Registry driver
+ * (deb, unpacked installs, flatpak). An AppImage is never mounted to look: its version decides (0.0.46+ have the
+ * driver), and T3's own launcher issues its sessions. A snap starts threads over SSH.
+ */
+export declare function linuxSupportsAcp(app: T3LinuxInstall): boolean;
+/**
+ * The bundled T3 server CLI (Electron as Node, ELECTRON_RUN_AS_NODE=1 set by the caller): the app's executable with
+ * the entry inside its app.asar; a flatpak's through `flatpak run`; an AppImage's through T3's own launcher
+ * (`<T3 home>/bin/t3`, which mounts the image). Undefined when there is none yet.
+ */
+export declare function linuxServerCli(app: T3LinuxInstall, t3Home: string): {
+    command: string;
+    args: string[];
+} | undefined;
+/**
+ * How T3 is opened (or brought to the front, as a second launch of T3 hands over to the running one): `gtk-launch`
+ * with its desktop entry when there is one, else its own program, started detached.
+ */
+export declare function linuxOpenCommands(app: T3LinuxInstall, env: Env): Array<{
+    command: string;
+    args: string[];
+    detached: boolean;
+}>;
+/** Opens T3 Code on Linux. Nothing here ever stops a T3 process: a launcher that hangs is left alone. */
+export declare function openLinuxT3(env: Env, app: T3LinuxInstall): Promise<void>;
+/**
+ * When T3 last started, as the filesystem records it: the program's access time once it is later than its modification
+ * time (dpkg installs both at the build time; relatime updates the access time on the first start, then daily). Null
+ * before the first start and on noatime mounts.
+ */
+export declare function linuxLastUsed(path: string): string | null;
+export {};

package/dist/t3-linux.js

@@ -0,0 +1,343 @@
+/**
+ * T3 Code on Linux (0.17.0+): finding the installed desktop app, its version and route, and opening it.
+ *
+ * T3 ships a .deb and an AppImage (electron-builder, 0.0.45 and the nightlies, verified from the release assets):
+ * - .deb (package `t3code`): the app in `/opt/T3 Code (Alpha)/` (`/opt/T3 Code (Nightly)/` for nightlies) with the
+ *   executable `t3code`, `resources/app.asar` and `resources/package-type` ("deb"); the entry
+ *   `/usr/share/applications/t3code.desktop` (`Name=T3 Code (Alpha)`, `Exec="/opt/T3 Code (Alpha)/t3code" %U`,
+ *   `StartupWMClass=t3code`, `MimeType=x-scheme-handler/t3code;…`); `/usr/bin/t3code` is an update-alternatives link
+ *   made by its postinst. dpkg records nightlies as `0.0.46~nightly.<date>.<run>`.
+ * - AppImage: `T3-Code-<version>-<x86_64|arm64>.AppImage`, a squashfs image that is never mounted here; AppImageLauncher
+ *   and Gear Lever integrate it with a copy of the same entry (`X-AppImage-Version`, `Exec=<the AppImage> %U`).
+ *
+ * Entries are found in the XDG application folders (also snapd's and flatpak's exports) and keyed on what the entry
+ * says (its Name, and StartupWMClass, the t3code URL scheme or a T3 flatpak id), never on its file name; only files
+ * whose name could be one are read, so a computer without T3 costs a few directory listings and no subprocess.
+ */
+import { spawn, spawnSync } from 'node:child_process';
+import { accessSync, constants, openSync, readFileSync, readSync, closeSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, delimiter, dirname, isAbsolute, join, relative } from 'node:path';
+import { T3_SERVER_ENTRY, asarVersion, t3ArchiveSupportsAcp } from "./t3-asar.js";
+const RELEASE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+const MAYBE_ENTRY = /t3|^appimagekit_|^gearlever_/i;
+const APPIMAGE = /^t3[-_ ]?code.*\.appimage$/i;
+/** `T3-Code-<version>-<arch>.AppImage`, also as AppImageLauncher renames it (`…-x86_64_<hash>.AppImage`). */
+const APPIMAGE_VERSION = /^T3[-_ ]?Code-(\d+\.\d+\.\d+(?:-[0-9A-Za-z.]+)?)-(?:x86_64|x64|amd64|arm64|aarch64|armv7l)(?![0-9A-Za-z])/i;
+const FLATPAK_ID = 'com.t3tools.t3code';
+/** The launcher T3 (nightlies since October 2026) writes to `<T3 home>/bin/t3` for its bundled CLI; for an AppImage it mounts the image itself. */
+export const T3_LAUNCHER_MARKER = "Written by T3 Code: runs the desktop app's bundled t3 CLI.";
+/**
+ * The folders scanned on Linux, in XDG precedence: the data home's and each data dir's `applications`, snapd's and
+ * flatpak's exported entries, then the usual AppImage folders. SHARDFLUX_APPLICATIONS_DIRS replaces all of them.
+ */
+export function linuxApplicationDirs(env) {
+    const home = env.HOME || homedir();
+    const dataHome = env.XDG_DATA_HOME && isAbsolute(env.XDG_DATA_HOME) ? env.XDG_DATA_HOME : join(home, '.local', 'share');
+    const dataDirs = (env.XDG_DATA_DIRS || '/usr/local/share:/usr/share').split(':').filter(d => isAbsolute(d));
+    return [...new Set([dataHome, ...dataDirs, '/usr/local/share', '/usr/share'].map(d => join(d, 'applications')).concat('/var/lib/snapd/desktop/applications', '/var/lib/flatpak/exports/share/applications', join(dataHome, 'flatpak', 'exports', 'share', 'applications'), join(home, 'Applications'), join(home, 'AppImages'), join(home, '.local', 'bin'), join(home, 'Downloads')))];
+}
+/** The `[Desktop Entry]` group's unlocalized keys (string escapes undone), first value of each key. */
+export function desktopEntry(text) {
+    const keys = {};
+    let main = false;
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (!line || line.startsWith('#'))
+            continue;
+        if (line.startsWith('[')) {
+            main = line === '[Desktop Entry]';
+            continue;
+        }
+        const eq = line.indexOf('=');
+        if (!main || eq < 1)
+            continue;
+        const key = line.slice(0, eq).trim();
+        if (!key.includes('[') && !(key in keys))
+            keys[key] = line.slice(eq + 1).trim().replace(/\\([sntr\\])/g, (_, c) => ({ s: ' ', n: '\n', t: '\t', r: '\r', '\\': '\\' })[c]);
+    }
+    return keys;
+}
+/** An entry's Exec as argv (the Desktop Entry quoting rules), field codes and flatpak's @@ markers removed; undefined when malformed. */
+export function desktopExec(value) {
+    const args = [];
+    let current = '', started = false, quoted = false;
+    for (let i = 0; i < value.length; i++) {
+        const c = value[i];
+        if (quoted) {
+            if (c === '\\' && i + 1 < value.length && '"`$\\'.includes(value[i + 1]))
+                current += value[++i];
+            else if (c === '"')
+                quoted = false;
+            else
+                current += c;
+        }
+        else if (c === '"') {
+            quoted = true;
+            started = true;
+        }
+        else if (c === ' ' || c === '\t') {
+            if (started)
+                args.push(current);
+            current = '';
+            started = false;
+        }
+        else {
+            current += c;
+            started = true;
+        }
+    }
+    if (quoted)
+        return undefined;
+    if (started)
+        args.push(current);
+    return args.filter(a => !/^%[fFuUdDnNickvm]$/.test(a) && !/^@@[uf]?$/.test(a)).map(a => a.replace(/%(%|[a-zA-Z])/g, (_, c) => c === '%' ? '%' : ''));
+}
+/** Whether an entry is T3 Code's: its Name, and its window class, URL scheme or flatpak id. */
+function isT3Entry(e) {
+    if ((e.Type ?? 'Application') !== 'Application' || !/^T3 Code(?: \(.+\))?$/.test(e.Name ?? ''))
+        return false;
+    return e.StartupWMClass === 't3code' || (e.MimeType ?? '').split(';').includes('x-scheme-handler/t3code') || e['X-Flatpak'] === FLATPAK_ID;
+}
+const executable = (path) => { try {
+    accessSync(path, constants.X_OK);
+    return statSync(path).isFile();
+}
+catch {
+    return false;
+} };
+const real = (path) => { try {
+    return realpathSync(path);
+}
+catch {
+    return path;
+} };
+const onPath = (name, env) => isAbsolute(name) ? (executable(name) ? name : undefined) : (env.PATH ?? '').split(delimiter).filter(Boolean).map(dir => join(dir, name)).find(executable);
+const release = (value) => value && RELEASE.test(value) ? value : null;
+/** A type 2 AppImage: an ELF file with `AI\x02` at byte 8. */
+function isAppImage(path) {
+    if (/\.appimage$/i.test(path))
+        return true;
+    let fd;
+    try {
+        fd = openSync(path, 'r');
+        const b = Buffer.alloc(11);
+        return readSync(fd, b, 0, 11, 0) === 11 && b.subarray(0, 4).equals(Buffer.from('\x7fELF', 'latin1')) && b.subarray(8, 11).equals(Buffer.from('AI\x02', 'latin1'));
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+/** dpkg's version of the `t3code` package, in T3's own form (dpkg writes `0.0.46~nightly…` for `0.0.46-nightly…`). */
+function dpkgVersion(env) {
+    const r = spawnSync('dpkg-query', ['-W', '-f=${Version}', 't3code'], { env, encoding: 'utf8', input: '', timeout: 2000 });
+    return r.status === 0 ? release(r.stdout.trim().replace(/^\d+:/, '').replaceAll('~', '-')) : null;
+}
+/** The resources/app.asar of an unpacked Electron app, one or two folders below `root` (a flatpak's files). */
+function findAsar(root) {
+    const at = (dir) => { const asar = join(dir, 'resources', 'app.asar'); try {
+        return statSync(asar).isFile() ? asar : undefined;
+    }
+    catch {
+        return undefined;
+    } };
+    const children = (dir) => { try {
+        return readdirSync(dir, { withFileTypes: true }).filter(d => d.isDirectory()).map(d => join(dir, d.name));
+    }
+    catch {
+        return [];
+    } };
+    return at(root) ?? children(root).map(at).find(Boolean) ?? children(root).flatMap(children).slice(0, 64).map(at).find(Boolean);
+}
+/** The install a T3 entry describes, from its program: an AppImage, a flatpak, a snap, or an unpacked app folder. */
+function fromEntry(e, id, dir, env) {
+    const exec = desktopExec(e.Exec ?? '');
+    if (!exec?.length)
+        return undefined;
+    let i = 0;
+    if (basename(exec[0]) === 'env') {
+        i = 1;
+        while (i < exec.length && /^[A-Za-z_]\w*=/.test(exec[i]))
+            i++;
+    }
+    const program = exec[i];
+    if (!program)
+        return undefined;
+    const entryVersion = release(e['X-AppImage-Version']);
+    if (e['X-Flatpak']) {
+        const appId = e['X-Flatpak'];
+        const root = dir.endsWith(join('exports', 'share', 'applications')) ? dirname(dirname(dirname(dir))) : '/var/lib/flatpak';
+        const files = join(root, 'app', appId, 'current', 'active', 'files');
+        const asar = findAsar(files) ?? null;
+        const command = exec.find(a => a.startsWith('--command='))?.slice('--command='.length);
+        const exe = asar ? join(dirname(dirname(asar)), basename(command || 't3code')) : files;
+        return { path: exe, version: (asar ? asarVersion(asar) : null) ?? entryVersion, linux: { format: 'flatpak', desktop_id: id, exec, asar: executable(exe) ? asar : null, flatpak: { id: appId, files } } };
+    }
+    const resolved = onPath(program, env);
+    if (!resolved)
+        return undefined;
+    if (e['X-SnapInstanceName'] || resolved.startsWith('/snap/bin/') || dir === '/var/lib/snapd/desktop/applications') {
+        const name = e['X-SnapInstanceName'] || basename(resolved);
+        let version = null;
+        try {
+            version = release(/^version:\s*['"]?([^'"\s]+)/m.exec(readFileSync(join('/snap', name, 'current', 'meta', 'snap.yaml'), 'utf8'))?.[1]);
+        }
+        catch { /* no snap metadata */ }
+        return { path: resolved, version, linux: { format: 'snap', desktop_id: id, exec, asar: null } };
+    }
+    const target = real(resolved);
+    if (isAppImage(target)) {
+        return { path: target, version: entryVersion ?? release(APPIMAGE_VERSION.exec(basename(target))?.[1]), linux: { format: 'appimage', desktop_id: id, exec, asar: null } };
+    }
+    const asar = join(dirname(target), 'resources', 'app.asar');
+    let found = false;
+    try {
+        found = statSync(asar).isFile();
+    }
+    catch { /* not an unpacked Electron app */ }
+    let deb = false;
+    try {
+        deb = readFileSync(join(dirname(target), 'resources', 'package-type'), 'utf8').trim() === 'deb';
+    }
+    catch { /* not from the .deb */ }
+    const version = (found ? asarVersion(asar) : null) ?? (deb ? dpkgVersion(env) : null) ?? entryVersion;
+    return { path: target, version, linux: { format: deb ? 'deb' : 'directory', desktop_id: id, exec, asar: found ? asar : null } };
+}
+/** The installed T3 Code apps on Linux, from the desktop entries and AppImages in `dirs` (linuxApplicationDirs). */
+export function linuxT3Apps(dirs, env) {
+    const found = [], ids = new Set(), loose = [];
+    for (const dir of dirs) {
+        let names;
+        try {
+            names = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const name of names) {
+            if (APPIMAGE.test(name)) {
+                loose.push(join(dir, name));
+                continue;
+            }
+            if (!name.endsWith('.desktop') || !MAYBE_ENTRY.test(name) || ids.has(name))
+                continue;
+            let text;
+            try {
+                text = readFileSync(join(dir, name), 'utf8');
+            }
+            catch {
+                continue;
+            }
+            // The first entry with an id wins (XDG precedence); a Hidden one removes that id.
+            ids.add(name);
+            const e = desktopEntry(text);
+            if (e.Hidden === 'true' || !isT3Entry(e) || (e.TryExec && !onPath(e.TryExec, env)))
+                continue;
+            const app = fromEntry(e, name, dir, env);
+            if (app && !found.some(f => f.path === app.path))
+                found.push(app);
+        }
+    }
+    for (const file of loose) {
+        const path = real(file);
+        if (!executable(path) || found.some(f => f.path === path))
+            continue;
+        found.push({ path, version: release(APPIMAGE_VERSION.exec(basename(path))?.[1]), linux: { format: 'appimage', desktop_id: null, exec: [path], asar: null } });
+    }
+    return found;
+}
+/** `0.0.46` and later (nightlies of 0.0.46 included). */
+const atLeast046 = (version) => {
+    const [major = 0, minor = 0, patch = 0] = /^(\d+)\.(\d+)\.(\d+)/.exec(version ?? '')?.slice(1).map(Number) ?? [];
+    return major > 0 || minor > 0 || patch >= 46;
+};
+/**
+ * Whether this install runs the Shardflux provider (ACP mode): the server in its app.asar has the ACP Registry driver
+ * (deb, unpacked installs, flatpak). An AppImage is never mounted to look: its version decides (0.0.46+ have the
+ * driver), and T3's own launcher issues its sessions. A snap starts threads over SSH.
+ */
+export function linuxSupportsAcp(app) {
+    if (app.linux.format === 'appimage')
+        return !!app.version && atLeast046(app.version);
+    return app.linux.format !== 'snap' && !!app.linux.asar && t3ArchiveSupportsAcp(app.linux.asar);
+}
+/**
+ * The bundled T3 server CLI (Electron as Node, ELECTRON_RUN_AS_NODE=1 set by the caller): the app's executable with
+ * the entry inside its app.asar; a flatpak's through `flatpak run`; an AppImage's through T3's own launcher
+ * (`<T3 home>/bin/t3`, which mounts the image). Undefined when there is none yet.
+ */
+export function linuxServerCli(app, t3Home) {
+    const { format, asar, flatpak } = app.linux;
+    if ((format === 'deb' || format === 'directory') && asar)
+        return { command: app.path, args: [join(asar, T3_SERVER_ENTRY)] };
+    if (format === 'flatpak' && flatpak && asar) {
+        const inside = (path) => `/app/${relative(flatpak.files, path)}`;
+        return { command: 'flatpak', args: ['run', `--command=${inside(app.path)}`, '--env=ELECTRON_RUN_AS_NODE=1', flatpak.id, inside(join(asar, T3_SERVER_ENTRY))] };
+    }
+    if (format === 'appimage') {
+        const launcher = join(t3Home, 'bin', 't3');
+        try {
+            if (executable(launcher) && readFileSync(launcher, 'utf8').includes(T3_LAUNCHER_MARKER))
+                return { command: launcher, args: [] };
+        }
+        catch { /* not written yet */ }
+    }
+    return undefined;
+}
+/**
+ * How T3 is opened (or brought to the front, as a second launch of T3 hands over to the running one): `gtk-launch`
+ * with its desktop entry when there is one, else its own program, started detached.
+ */
+export function linuxOpenCommands(app, env) {
+    const { desktop_id: id, exec, format, flatpak } = app.linux;
+    const gtk = id ? onPath('gtk-launch', env) : undefined;
+    return [
+        ...(gtk && id ? [{ command: gtk, args: [id], detached: false }] : []),
+        format === 'flatpak' && flatpak ? { command: 'flatpak', args: ['run', flatpak.id], detached: true } : { command: exec[0], args: exec.slice(1), detached: true },
+    ];
+}
+/** Opens T3 Code on Linux. Nothing here ever stops a T3 process: a launcher that hangs is left alone. */
+export async function openLinuxT3(env, app) {
+    let last;
+    for (const { command, args, detached } of linuxOpenCommands(app, env)) {
+        try {
+            await new Promise((resolve, reject) => {
+                const child = spawn(command, args, { env, stdio: 'ignore', detached });
+                if (detached) {
+                    child.once('spawn', () => { child.unref(); resolve(); });
+                    child.once('error', reject);
+                    return;
+                }
+                const timer = setTimeout(() => { child.unref(); reject(new Error(`${basename(command)} did not answer in time`)); }, 10_000);
+                child.once('error', e => { clearTimeout(timer); reject(e); });
+                child.once('exit', code => { clearTimeout(timer); if (code === 0)
+                    resolve();
+                else
+                    reject(new Error(`${basename(command)} exited ${code}`)); });
+            });
+            return;
+        }
+        catch (error) {
+            last = error;
+        }
+    }
+    throw new Error(`could not open T3 Code (${last instanceof Error ? last.message : String(last)})`);
+}
+/**
+ * When T3 last started, as the filesystem records it: the program's access time once it is later than its modification
+ * time (dpkg installs both at the build time; relatime updates the access time on the first start, then daily). Null
+ * before the first start and on noatime mounts.
+ */
+export function linuxLastUsed(path) {
+    try {
+        const s = statSync(path);
+        return s.atimeMs > s.mtimeMs + 1000 ? new Date(s.atimeMs).toISOString() : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/t3-mode.d.ts

@@ -1,6 +1,8 @@
 import type { Workspace } from '@shardflux/sdk';
 import type { Ctx } from './commands.js';
 import { CodedError } from './errors.js';
+import { t3HomeDir } from './t3-provider.js';
+import type { T3LinuxApp } from './t3-linux.js';
 import type { InitialImage } from './initial-prompt.js';
 export declare const T3_BUNDLE_ID = "com.t3tools.t3code";
 export type T3Mode = 'acp' | 'ssh';
@@ -8,10 +10,13 @@ export type AgentApp = 'claude' | 'codex';
 export type OpenIn = 'terminal' | 'claude-desktop' | 'web' | 'codex-app' | 't3';
 /** Where each app's new conversations can open: Claude in a terminal, Claude Desktop, claude.ai or T3; Codex in the Codex app or T3. */
 export declare const OPEN_IN_TARGETS: Record<AgentApp, readonly OpenIn[]>;
+export declare const openInTargets: (app: AgentApp, platform?: NodeJS.Platform) => readonly OpenIn[];
+/** The T3 Code `shard` uses: its .app bundle (macOS) or program (Linux, with how it was installed in `linux`). */
 export interface T3Install {
     path: string;
     version: string | null;
     mode: T3Mode;
+    linux?: T3LinuxApp;
 }
 export interface T3Status {
     installed: boolean;
@@ -41,16 +46,19 @@ export interface T3ThreadResult {
     effort: string | null;
     effort_reason?: EffortReason;
 }
-/** Native lookups that tests replace: Spotlight's last-used dates of app bundles, one `mdls` for all of them. */
+/**
+ * Native lookups that tests replace: Spotlight's last-used dates of app bundles, one `mdls` for all of them (macOS), or
+ * when each program last started, from its access time (Linux, t3-linux.ts).
+ */
 export declare const t3Native: {
-    lastUsedMany(paths: readonly string[], env: Record<string, string | undefined>): Record<string, string | null>;
+    lastUsedMany(paths: readonly string[], env: Record<string, string | undefined>, platform?: NodeJS.Platform): Record<string, string | null>;
 };
 /** Spotlight takes about 40 ms per call, so the dates are kept for a few minutes (app-usage.json in the config dir). */
 export declare const LAST_USED_TTL_MS: number;
 export declare function lastUsedDates(ctx: Ctx, paths: readonly string[], now?: number): Record<string, string | null>;
 /** The installed T3 Code, preferring a build with ACP providers when several channels are installed. */
-export declare function t3Install(env: Record<string, string | undefined>, platform?: NodeJS.Platform): T3Install | undefined;
-export declare function t3HomeDir(env: Record<string, string | undefined>): string;
+export declare function t3Install(env: Record<string, string | undefined>, platform?: NodeJS.Platform, dirs?: string[]): T3Install | undefined;
+export { t3HomeDir };
 /** The Shardflux provider instance in T3's server settings (read only; every `shard` run writes it, see t3-provider.ts). */
 export declare function t3ProviderRegistered(env: Record<string, string | undefined>): boolean;
 /**
@@ -91,10 +99,11 @@ export declare const t3NotInstalled: () => CodedError;
 /** The first line of the prompt, as T3 titles a thread before it names it. */
 export declare function t3ThreadTitle(prompt: string): string;
 /**
- * Opens T3 Code (or brings it to the front): the install `shard` chose (`open -a <path>`). Every T3 channel shares one
- * bundle id, so `open -b` could start another installed channel.
+ * Opens T3 Code (or brings it to the front): the install `shard` chose. On macOS `open -a <path>` (every T3 channel
+ * shares one bundle id, so `open -b` could start another installed channel); on Linux its desktop entry with
+ * `gtk-launch`, else its program (t3-linux.ts).
  */
-export declare function openT3(env: Record<string, string | undefined>, appPath: string): Promise<void>;
+export declare function openT3(env: Record<string, string | undefined>, install: Pick<T3Install, 'path' | 'version' | 'linux'> | undefined): Promise<void>;
 /** Starts the thread in the VM's T3 server (T3_THREAD_SCRIPT); the prompt travels on stdin, never in argv. */
 export declare function startSshThread(ctx: Ctx, ws: Workspace, version: string | undefined, projectPath: string, request: T3ThreadRequest): Promise<T3ThreadResult>;
 interface Descriptor {
@@ -118,4 +127,3 @@ export declare function t3Rpc(server: LocalT3Server, session: T3Session, tag: st
 export declare function startAcpThread(ctx: Ctx, install: T3Install, folder: string, request: T3ThreadRequest, waitMs?: number): Promise<T3ThreadResult>;
 /** The T3 thread of a Shardflux conversation started in T3 (ACP mode): the one remembered, else a search of recent Shardflux threads. */
 export declare function findAcpThread(ctx: Ctx, install: T3Install, conversationId: string): Promise<string | null>;
-export {};