sideby 0.0.0-stage → 0.2.1

package/dist/src/families/index.js

@@ -0,0 +1,40 @@
+import { packageVersion } from '../core/version.js';
+import { accountScript } from '../plugins/account-script.js';
+import { claudePlugin } from './claude/index.js';
+import { codexPlugin } from './codex/index.js';
+import { grokPlugin } from './grok/index.js';
+import { piPlugin } from './pi/index.js';
+const VERSION = packageVersion();
+/** Built-in Plugins in load order. Families register here; `account-script` is off unless enabled. */
+export const BUILTIN_PLUGINS = [
+    {
+        plugin: claudePlugin,
+        version: VERSION,
+        description: 'Claude Code family (~/.claude, CLAUDE_CONFIG_DIR)',
+        defaultEnabled: true,
+    },
+    {
+        plugin: codexPlugin,
+        version: VERSION,
+        description: 'Codex family (~/.codex, CODEX_HOME)',
+        defaultEnabled: true,
+    },
+    {
+        plugin: grokPlugin,
+        version: VERSION,
+        description: 'Grok Build family (~/.grok, GROK_HOME)',
+        defaultEnabled: true,
+    },
+    {
+        plugin: piPlugin,
+        version: VERSION,
+        description: 'pi family (~/.pi/agent, PI_CODING_AGENT_DIR)',
+        defaultEnabled: true,
+    },
+    {
+        plugin: accountScript,
+        version: VERSION,
+        description: 'Run <account>/sideby-before-launch before each launch',
+        defaultEnabled: false,
+    },
+];

package/dist/src/families/logos.d.ts

@@ -0,0 +1,21 @@
+/** Logos of the built-in Families, by Family id; each Family sets its own as `logo`. */
+export declare const BUILTIN_LOGOS: {
+    claude: {
+        title: string;
+        color: string;
+        path: string;
+    };
+    codex: {
+        title: string;
+        path: string;
+    };
+    grok: {
+        title: string;
+        fillRule: "evenodd";
+        path: string;
+    };
+    pi: {
+        title: string;
+        path: string;
+    };
+};

package/dist/src/families/logos.js

@@ -0,0 +1,26 @@
+// Built-in Family marks for the Panel (FamilyDef.logo): 24x24 single-path SVG icons, drawn inline because the page CSP
+// allows no external images.
+// Sources: Claude, OpenAI and pi from Simple Icons (CC0 1.0, https://simpleicons.org; OpenAI from v15.0.0, the last release
+// that ships it; pi is the mark from https://pi.dev). Grok from LobeHub Icons (MIT, Copyright (c) 2023 LobeHub,
+// https://github.com/lobehub/lobe-icons). The marks are trademarks of their owners and only identify each Host.
+/** Logos of the built-in Families, by Family id; each Family sets its own as `logo`. */
+export const BUILTIN_LOGOS = {
+    claude: {
+        title: 'Claude',
+        color: '#D97757',
+        path: 'm4.7144 15.9555 4.7174-2.6471.079-.2307-.079-.1275h-.2307l-.7893-.0486-2.6956-.0729-2.3375-.0971-2.2646-.1214-.5707-.1215-.5343-.7042.0546-.3522.4797-.3218.686.0608 1.5179.1032 2.2767.1578 1.6514.0972 2.4468.255h.3886l.0546-.1579-.1336-.0971-.1032-.0972L6.973 9.8356l-2.55-1.6879-1.3356-.9714-.7225-.4918-.3643-.4614-.1578-1.0078.6557-.7225.8803.0607.2246.0607.8925.686 1.9064 1.4754 2.4893 1.8336.3643.3035.1457-.1032.0182-.0728-.164-.2733-1.3539-2.4467-1.445-2.4893-.6435-1.032-.17-.6194c-.0607-.255-.1032-.4674-.1032-.7285L6.287.1335 6.6997 0l.9957.1336.419.3642.6192 1.4147 1.0018 2.2282 1.5543 3.0296.4553.8985.2429.8318.091.255h.1579v-.1457l.1275-1.706.2368-2.0947.2307-2.6957.0789-.7589.3764-.9107.7468-.4918.5828.2793.4797.686-.0668.4433-.2853 1.8517-.5586 2.9021-.3643 1.9429h.2125l.2429-.2429.9835-1.3053 1.6514-2.0643.7286-.8196.85-.9046.5464-.4311h1.0321l.759 1.1293-.34 1.1657-1.0625 1.3478-.8804 1.1414-1.2628 1.7-.7893 1.36.0729.1093.1882-.0183 2.8535-.607 1.5421-.2794 1.8396-.3157.8318.3886.091.3946-.3278.8075-1.967.4857-2.3072.4614-3.4364.8136-.0425.0304.0486.0607 1.5482.1457.6618.0364h1.621l3.0175.2247.7892.522.4736.6376-.079.4857-1.2142.6193-1.6393-.3886-3.825-.9107-1.3113-.3279h-.1822v.1093l1.0929 1.0686 2.0035 1.8092 2.5075 2.3314.1275.5768-.3218.4554-.34-.0486-2.2039-1.6575-.85-.7468-1.9246-1.621h-.1275v.17l.4432.6496 2.3436 3.5214.1214 1.0807-.17.3521-.6071.2125-.6679-.1214-1.3721-1.9246L14.38 17.959l-1.1414-1.9428-.1397.079-.674 7.2552-.3156.3703-.7286.2793-.6071-.4614-.3218-.7468.3218-1.4753.3886-1.9246.3157-1.53.2853-1.9004.17-.6314-.0121-.0425-.1397.0182-1.4328 1.9672-2.1796 2.9446-1.7243 1.8456-.4128.164-.7164-.3704.0667-.6618.4008-.5889 2.386-3.0357 1.4389-1.882.929-1.0868-.0062-.1579h-.0546l-6.3385 4.1164-1.1293.1457-.4857-.4554.0608-.7467.2307-.2429 1.9064-1.3114Z',
+    },
+    codex: {
+        title: 'OpenAI',
+        path: 'M22.2819 9.8211a5.9847 5.9847 0 0 0-.5157-4.9108 6.0462 6.0462 0 0 0-6.5098-2.9A6.0651 6.0651 0 0 0 4.9807 4.1818a5.9847 5.9847 0 0 0-3.9977 2.9 6.0462 6.0462 0 0 0 .7427 7.0966 5.98 5.98 0 0 0 .511 4.9107 6.051 6.051 0 0 0 6.5146 2.9001A5.9847 5.9847 0 0 0 13.2599 24a6.0557 6.0557 0 0 0 5.7718-4.2058 5.9894 5.9894 0 0 0 3.9977-2.9001 6.0557 6.0557 0 0 0-.7475-7.0729zm-9.022 12.6081a4.4755 4.4755 0 0 1-2.8764-1.0408l.1419-.0804 4.7783-2.7582a.7948.7948 0 0 0 .3927-.6813v-6.7369l2.02 1.1686a.071.071 0 0 1 .038.052v5.5826a4.504 4.504 0 0 1-4.4945 4.4944zm-9.6607-4.1254a4.4708 4.4708 0 0 1-.5346-3.0137l.142.0852 4.783 2.7582a.7712.7712 0 0 0 .7806 0l5.8428-3.3685v2.3324a.0804.0804 0 0 1-.0332.0615L9.74 19.9502a4.4992 4.4992 0 0 1-6.1408-1.6464zM2.3408 7.8956a4.485 4.485 0 0 1 2.3655-1.9728V11.6a.7664.7664 0 0 0 .3879.6765l5.8144 3.3543-2.0201 1.1685a.0757.0757 0 0 1-.071 0l-4.8303-2.7865A4.504 4.504 0 0 1 2.3408 7.872zm16.5963 3.8558L13.1038 8.364 15.1192 7.2a.0757.0757 0 0 1 .071 0l4.8303 2.7913a4.4944 4.4944 0 0 1-.6765 8.1042v-5.6772a.79.79 0 0 0-.407-.667zm2.0107-3.0231l-.142-.0852-4.7735-2.7818a.7759.7759 0 0 0-.7854 0L9.409 9.2297V6.8974a.0662.0662 0 0 1 .0284-.0615l4.8303-2.7866a4.4992 4.4992 0 0 1 6.6802 4.66zM8.3065 12.863l-2.02-1.1638a.0804.0804 0 0 1-.038-.0567V6.0742a4.4992 4.4992 0 0 1 7.3757-3.4537l-.142.0805L8.704 5.459a.7948.7948 0 0 0-.3927.6813zm1.0976-2.3654l2.602-1.4998 2.6069 1.4998v2.9994l-2.5974 1.4997-2.6067-1.4997Z',
+    },
+    grok: {
+        title: 'Grok',
+        fillRule: 'evenodd',
+        path: 'M9.27 15.29l7.978-5.897c.391-.29.95-.177 1.137.272.98 2.369.542 5.215-1.41 7.169-1.951 1.954-4.667 2.382-7.149 1.406l-2.711 1.257c3.889 2.661 8.611 2.003 11.562-.953 2.341-2.344 3.066-5.539 2.388-8.42l.006.007c-.983-4.232.242-5.924 2.75-9.383.06-.082.12-.164.179-.248l-3.301 3.305v-.01L9.267 15.292M7.623 16.723c-2.792-2.67-2.31-6.801.071-9.184 1.761-1.763 4.647-2.483 7.166-1.425l2.705-1.25a7.808 7.808 0 00-1.829-1A8.975 8.975 0 005.984 5.83c-2.533 2.536-3.33 6.436-1.962 9.764 1.022 2.487-.653 4.246-2.34 6.022-.599.63-1.199 1.259-1.682 1.925l7.62-6.815',
+    },
+    pi: {
+        title: 'pi',
+        path: 'M0 0v24h6v-6h6v-6H6V6h6v6h6V0Zm18 12v12h6V12Z',
+    },
+};

package/dist/src/families/pi/index.d.ts

@@ -0,0 +1,3 @@
+import type { FamilyDef, Plugin } from '../../types.ts';
+export declare const piFamily: FamilyDef;
+export declare const piPlugin: Plugin;

package/dist/src/families/pi/index.js

@@ -0,0 +1,54 @@
+// Built-in Family Plugin for pi (spec §3.4, checked against pi 1.0.2). pi keeps each Account one level
+// deeper (`~/.pi-<name>/agent`) and signs in inside the app, so there is no login command.
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { lstatOrNull } from '../../core/fs-safe.js';
+import { BUILTIN_LOGOS } from '../logos.js';
+/** `auth.json` exists after `/login`; its contents are never read. */
+async function loginState(account) {
+    return (await lstatOrNull(join(account.dir, 'auth.json'))) ? 'logged-in' : 'logged-out';
+}
+async function model(account) {
+    try {
+        const s = JSON.parse(await readFile(join(account.dir, 'settings.json'), 'utf8'));
+        const provider = typeof s?.defaultProvider === 'string' ? s.defaultProvider : '';
+        const id = typeof s?.defaultModel === 'string' ? s.defaultModel : '';
+        if (!id)
+            return undefined;
+        return provider ? `${provider}/${id}` : id;
+    }
+    catch {
+        return undefined;
+    }
+}
+export const piFamily = {
+    id: 'pi',
+    title: 'pi',
+    logo: BUILTIN_LOGOS.pi,
+    bin: 'pi',
+    installUrl: 'https://github.com/earendil-works/pi',
+    selectVar: 'PI_CODING_AGENT_DIR',
+    secretFileMeansApi: false,
+    layout: { main: '.pi/agent', account: '.pi-<name>/agent' },
+    hijackVars: [
+        'ANTHROPIC_API_KEY',
+        'ANTHROPIC_AUTH_TOKEN',
+        'ANTHROPIC_BASE_URL',
+        'OPENAI_API_KEY',
+        'OPENAI_BASE_URL',
+    ],
+    apiVars: ['ANTHROPIC_API_KEY', 'ANTHROPIC_BASE_URL', 'OPENAI_API_KEY', 'OPENAI_BASE_URL'],
+    sharedItems: [
+        { path: 'AGENTS.md', mode: 'link' },
+        { path: 'auth.json', mode: 'info', credential: true },
+    ],
+    login: { args: null, hint: 'pi signs in inside the app: start it and type /login' },
+    loginState,
+    model,
+};
+export const piPlugin = {
+    name: 'pi',
+    register(api) {
+        api.family(piFamily);
+    },
+};

package/dist/src/families/shared/sessions.d.ts

@@ -0,0 +1,9 @@
+export declare const isSessionId: (s: string | undefined) => s is string;
+/** The id after `--resume <id>`, `--resume=<id>` or `-r <id>`; Claude Code and Grok Build share this form. */
+export declare function resumeFlagSession(args: readonly string[]): string | undefined;
+/** The first UUID after the `resume` subcommand (`codex resume [options] <id>`). */
+export declare function resumeSubcommandSession(args: readonly string[]): string | undefined;
+/** `<dir>/*` + `/<entry>`: one level of grouping directories (Claude projects, Grok working directories). */
+export declare function groupedEntryWrittenAt(dir: string, entry: string, type: 'file' | 'dir'): Promise<number | undefined>;
+/** A file anywhere under `dir` whose name ends with `suffix` (Codex `sessions/YYYY/MM/DD/rollout-…-<id>.jsonl`). */
+export declare function nestedFileWrittenAt(dir: string, suffix: string): Promise<number | undefined>;

package/dist/src/families/shared/sessions.js

@@ -0,0 +1,70 @@
+// Reading which session a Host command resumes, and whether an Account holds it (ADR-0007).
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+const SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export const isSessionId = (s) => s !== undefined && SESSION_ID.test(s);
+/** Arguments before the first `--`, the ones the Host reads as its own options. */
+const options = (args) => {
+    const end = args.indexOf('--');
+    return end === -1 ? args : args.slice(0, end);
+};
+/** The id after `--resume <id>`, `--resume=<id>` or `-r <id>`; Claude Code and Grok Build share this form. */
+export function resumeFlagSession(args) {
+    const opts = options(args);
+    for (let i = 0; i < opts.length; i++) {
+        const a = opts[i];
+        const id = a.startsWith('--resume=')
+            ? a.slice('--resume='.length)
+            : a === '--resume' || a === '-r'
+                ? opts[i + 1]
+                : undefined;
+        if (isSessionId(id))
+            return id;
+    }
+    return undefined;
+}
+/** The first UUID after the `resume` subcommand (`codex resume [options] <id>`). */
+export function resumeSubcommandSession(args) {
+    const opts = options(args);
+    const at = opts.indexOf('resume');
+    return at === -1 ? undefined : opts.slice(at + 1).find(isSessionId);
+}
+/** Modification time in ms of the first of `paths` that exists with the wanted type. */
+async function firstWrittenAt(paths, type) {
+    for (const p of paths) {
+        try {
+            const st = await stat(p);
+            if (type === 'file' ? st.isFile() : st.isDirectory())
+                return st.mtimeMs;
+        }
+        catch {
+            // not here
+        }
+    }
+    return undefined;
+}
+async function subdirs(dir) {
+    try {
+        return (await readdir(dir, { withFileTypes: true }))
+            .filter((e) => e.isDirectory())
+            .map((e) => join(dir, e.name));
+    }
+    catch {
+        return [];
+    }
+}
+/** `<dir>/*` + `/<entry>`: one level of grouping directories (Claude projects, Grok working directories). */
+export async function groupedEntryWrittenAt(dir, entry, type) {
+    return firstWrittenAt((await subdirs(dir)).map((d) => join(d, entry)), type);
+}
+/** A file anywhere under `dir` whose name ends with `suffix` (Codex `sessions/YYYY/MM/DD/rollout-…-<id>.jsonl`). */
+export async function nestedFileWrittenAt(dir, suffix) {
+    let names;
+    try {
+        names = await readdir(dir, { recursive: true });
+    }
+    catch {
+        return undefined;
+    }
+    return firstWrittenAt(names.filter((n) => n.endsWith(suffix)).map((n) => join(dir, n)), 'file');
+}

package/dist/src/families/shared/toml.d.ts

@@ -0,0 +1,5 @@
+/**
+ * `key = "value"` among the top-level keys of a TOML file, i.e. before the first `[table]` header.
+ * Only a whole-line header ends the top level, so a multi-line array line such as `  ["a"],` does not.
+ */
+export declare function topLevelTomlString(text: string, key: string): string | undefined;

package/dist/src/families/shared/toml.js

@@ -0,0 +1,16 @@
+const TABLE_HEADER = /^\s*\[\[?[^\]\s][^\]]*\]\]?\s*(#.*)?$/;
+/**
+ * `key = "value"` among the top-level keys of a TOML file, i.e. before the first `[table]` header.
+ * Only a whole-line header ends the top level, so a multi-line array line such as `  ["a"],` does not.
+ */
+export function topLevelTomlString(text, key) {
+    const pattern = new RegExp(`^\\s*${key}\\s*=\\s*(?:"([^"]*)"|'([^']*)')`);
+    for (const line of text.split(/\r?\n/)) {
+        if (TABLE_HEADER.test(line) && !/^\s*\[\s*["'\d]/.test(line))
+            return undefined;
+        const m = pattern.exec(line);
+        if (m)
+            return m[1] ?? m[2];
+    }
+    return undefined;
+}

package/dist/src/index.d.ts

@@ -0,0 +1,5 @@
+export { createPanelHandler, type PanelFamily, type PanelHandler, type PanelHandlerOptions, type PanelState, } from './panel/handler.ts';
+export { startPanelServer } from './panel/server.ts';
+export type { PanelTheme, PanelThemeTokens } from './panel/theme.ts';
+export { type AccountStatus, createRuntime, type DoctorOptions, type FamilyDetail, type FamilyInfo, type Runtime, type SharedItemInfo, } from './runtime.ts';
+export type * from './types.ts';

package/dist/src/index.js

@@ -0,0 +1,4 @@
+// Library entry: the Panel handler for embedding, the Runtime for tools built on sideby, and Plugin types.
+export { createPanelHandler, } from './panel/handler.js';
+export { startPanelServer } from './panel/server.js';
+export { createRuntime, } from './runtime.js';

package/dist/src/panel/background.d.ts

@@ -0,0 +1,62 @@
+import type { Paths } from '../core/paths.ts';
+import type { Env } from '../types.ts';
+export declare const DETACHED_FLAG = "serve-detached";
+export interface PanelPidFile {
+    pid: number;
+    port: number;
+    url: string;
+    startedAt: string;
+    /** Random id the Panel also returns on `/api/health`. */
+    instance: string;
+    /** `ps -o lstart=` of the process, when `ps` gave one; a reused pid has another. */
+    processStart?: string;
+}
+export declare const pidFilePath: (p: Paths) => string;
+export declare const logFilePath: (p: Paths) => string;
+export declare function readPidFile(p: Paths): Promise<PanelPidFile | undefined>;
+/** When `pid` started, as `ps` prints it; with the pid it names one process, which a reused pid does not match. */
+export declare const processStartTime: (pid: number) => Promise<string | undefined>;
+/** URL of a running background Panel, or of any sideby Panel on `port`; removes a stale pid file. */
+export declare function findRunningPanel(p: Paths, port: number): Promise<string | undefined>;
+export interface StartBackgroundOptions {
+    paths: Paths;
+    env: Env;
+    /** Absolute path of the sideby CLI entry the detached process runs. */
+    entry: string;
+    port?: number;
+}
+/**
+ * Makes sure one background Panel runs and returns its URL. Reuses a running one; otherwise starts
+ * `sideby ui --serve-detached` in its own session, logging to the state directory, and waits until it listens.
+ */
+export declare function startBackgroundPanel(opts: StartBackgroundOptions): Promise<{
+    url: string;
+    reused: boolean;
+    pid?: number;
+    replaced?: boolean;
+}>;
+/**
+ * Body of the detached process: serve the Panel with Hosts found through the login shell's PATH, tell the
+ * launching process the URL over IPC, keep the pid file while running, and remove it on SIGTERM or SIGINT.
+ */
+export declare function serveDetached(opts: {
+    paths: Paths;
+    env: Env;
+    port?: number;
+    runtimeFactory: (env: Env) => Promise<import('../runtime.ts').Runtime>;
+    log: (s: string) => void;
+}): Promise<number>;
+export type StopResult = {
+    status: 'stopped';
+    pid: number;
+    url: string;
+} | {
+    status: 'not-running';
+    detail?: string;
+} | {
+    status: 'failed';
+    pid: number;
+    detail: string;
+};
+/** Stops the background Panel named in the pid file, signalling it only when checkPanel confirms it. */
+export declare function stopBackgroundPanel(paths: Paths): Promise<StopResult>;

package/dist/src/panel/background.js

@@ -0,0 +1,274 @@
+// `sideby ui --background` and `--stop`: one detached Panel per state directory, found again through a pid file.
+// The detached process runs `sideby ui --serve-detached`; that flag is internal. `--stop` signals a pid only when
+// the process, its start time and the Panel answering on the recorded port all match the pid file.
+import { execFile, spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { mkdir, open, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { loginShellPath } from '../core/login-path.js';
+import { buildId } from '../core/version.js';
+import { DEFAULT_PANEL_PORT, isSidebyPanel, panelIdentity, startPanelServer, } from './server.js';
+export const DETACHED_FLAG = 'serve-detached';
+const START_TIMEOUT_MS = 20_000;
+const LOCK_STALE_MS = 30_000;
+const STOP_TIMEOUT_MS = 5000;
+const LOG_MAX_BYTES = 1_000_000;
+export const pidFilePath = (p) => join(p.stateDir, 'panel.json');
+export const logFilePath = (p) => join(p.stateDir, 'panel.log');
+const lockPath = (p) => join(p.stateDir, 'panel.lock');
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export async function readPidFile(p) {
+    try {
+        const d = JSON.parse(await readFile(pidFilePath(p), 'utf8'));
+        if (Number.isInteger(d.pid) && Number.isInteger(d.port) && typeof d.url === 'string')
+            return { ...d, instance: typeof d.instance === 'string' ? d.instance : '' };
+    }
+    catch { }
+    return undefined;
+}
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+/** Output of `ps -o <field>= -p <pid>`, or undefined when the process is gone or `ps` is unavailable. */
+function psField(pid, field) {
+    return new Promise((resolve) => {
+        execFile('ps', ['-ww', '-o', `${field}=`, '-p', String(pid)], { timeout: 3000, env: { ...process.env, LC_ALL: 'C' } }, (err, stdout) => resolve(err ? undefined : stdout.trim() || undefined));
+    });
+}
+/** When `pid` started, as `ps` prints it; with the pid it names one process, which a reused pid does not match. */
+export const processStartTime = (pid) => psField(pid, 'lstart');
+/**
+ * Checks that the pid file names a live detached Panel: the process is alive, started when the pid file says,
+ * runs `ui --serve-detached`, and the Panel on the recorded port answers with the same instance id and pid.
+ */
+async function checkPanel(rec) {
+    const stale = (reason) => ({ status: 'stale', reason });
+    if (!rec.instance)
+        return stale('it names no panel instance');
+    if (!alive(rec.pid))
+        return stale(`process ${rec.pid} is not running`);
+    if (rec.processStart && (await processStartTime(rec.pid)) !== rec.processStart)
+        return stale(`process ${rec.pid} is not the one that wrote it`);
+    const cmd = await psField(rec.pid, 'command');
+    if (!(cmd && / ui( |$)/.test(cmd) && cmd.includes(`--${DETACHED_FLAG}`)))
+        return stale(`process ${rec.pid} is not a sideby panel`);
+    const id = await panelIdentity(rec.port);
+    if (!id)
+        return {
+            status: 'unconfirmed',
+            reason: `process ${rec.pid} does not answer as a sideby panel on port ${rec.port}; if it is one, stop it with \`kill ${rec.pid}\``,
+        };
+    if (id.instance !== rec.instance || id.pid !== rec.pid)
+        return stale(`the panel on port ${rec.port} is not the one it names`);
+    return { status: 'ours', ...(id.build ? { build: id.build } : {}) };
+}
+/** URL of a running background Panel, or of any sideby Panel on `port`; removes a stale pid file. */
+export async function findRunningPanel(p, port) {
+    const rec = await readPidFile(p);
+    if (rec) {
+        const check = await checkPanel(rec);
+        if (check.status === 'ours')
+            return rec.url;
+        if (check.status === 'stale')
+            await rm(pidFilePath(p), { force: true });
+    }
+    return (await isSidebyPanel(port)) ? `http://127.0.0.1:${port}/` : undefined;
+}
+/**
+ * Stops this state directory's background Panel when it runs another build than `build` (or is older than build
+ * ids). Only a Panel the pid file names and that answers as itself is stopped; true when one was.
+ */
+async function stopOutdated(p, build) {
+    const rec = await readPidFile(p);
+    if (!rec)
+        return false;
+    const check = await checkPanel(rec);
+    if (check.status !== 'ours' || check.build === build)
+        return false;
+    return (await stopBackgroundPanel(p)).status === 'stopped';
+}
+/** Takes the start lock, waiting while another launch holds it; a lock older than 30 s is taken over. */
+async function withStartLock(p, fn) {
+    const lock = lockPath(p);
+    const deadline = Date.now() + START_TIMEOUT_MS;
+    for (;;) {
+        try {
+            const fh = await open(lock, 'wx', 0o600);
+            await fh.writeFile(String(process.pid));
+            await fh.close();
+            break;
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+            const age = await stat(lock).then((s) => Date.now() - s.mtimeMs, () => 0);
+            if (age > LOCK_STALE_MS || Date.now() > deadline)
+                await rm(lock, { force: true });
+            else
+                await sleep(200);
+        }
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        await rm(lock, { force: true });
+    }
+}
+async function openLog(p) {
+    const log = logFilePath(p);
+    const size = await stat(log).then((s) => s.size, () => 0);
+    if (size > LOG_MAX_BYTES)
+        await rename(log, `${log}.1`).catch(() => { });
+    return open(log, 'a', 0o600);
+}
+/**
+ * Makes sure one background Panel runs and returns its URL. Reuses a running one; otherwise starts
+ * `sideby ui --serve-detached` in its own session, logging to the state directory, and waits until it listens.
+ */
+export async function startBackgroundPanel(opts) {
+    const { paths } = opts;
+    const port = opts.port ?? DEFAULT_PANEL_PORT;
+    // After an upgrade or reinstall the old background Panel still runs the old code: replace it.
+    const replaced = await stopOutdated(paths, buildId(opts.env));
+    const running = await findRunningPanel(paths, port);
+    if (running)
+        return { url: running, reused: true };
+    await mkdir(paths.stateDir, { recursive: true, mode: 0o700 });
+    return withStartLock(paths, async () => {
+        // Another launch may have started one while this one waited for the lock.
+        const again = await findRunningPanel(paths, port);
+        if (again)
+            return { url: again, reused: true };
+        const log = await openLog(paths);
+        try {
+            await log.write(`\n[${new Date().toISOString()}] starting background panel on port ${port}\n`);
+            const child = spawn(process.execPath, [opts.entry, 'ui', `--${DETACHED_FLAG}`, '--no-open', '--port', String(port)], {
+                env: opts.env,
+                detached: true,
+                stdio: ['ignore', log.fd, log.fd, 'ipc'],
+            });
+            const msg = await new Promise((resolve, reject) => {
+                const timer = setTimeout(() => {
+                    child.kill('SIGTERM');
+                    reject(new Error(`the background panel did not start; see ${logFilePath(paths)}`));
+                }, START_TIMEOUT_MS);
+                child.once('message', (m) => {
+                    clearTimeout(timer);
+                    resolve(m);
+                });
+                child.once('error', (err) => {
+                    clearTimeout(timer);
+                    reject(err);
+                });
+                child.once('exit', (code) => {
+                    clearTimeout(timer);
+                    reject(new Error(`the background panel exited (code ${code}); see ${logFilePath(paths)}`));
+                });
+            });
+            child.removeAllListeners();
+            if (child.connected)
+                child.disconnect();
+            child.unref();
+            if (msg.reused)
+                return { url: msg.url, reused: true };
+            return { url: msg.url, reused: false, pid: child.pid, ...(replaced ? { replaced } : {}) };
+        }
+        finally {
+            await log.close();
+        }
+    });
+}
+/**
+ * Body of the detached process: serve the Panel with Hosts found through the login shell's PATH, tell the
+ * launching process the URL over IPC, keep the pid file while running, and remove it on SIGTERM or SIGINT.
+ */
+export async function serveDetached(opts) {
+    const { paths, log } = opts;
+    // Started now, awaited by the first request: the server listens without waiting for the shell.
+    const envReady = loginShellPath(opts.env).then((r) => {
+        log(r.source === 'login-shell'
+            ? 'host PATH: from the login shell'
+            : `host PATH: login shell unusable (${r.reason}); using the inherited PATH`);
+        return { ...opts.env, PATH: r.path };
+    });
+    const instance = randomBytes(16).toString('hex');
+    const srv = await startPanelServer({
+        runtimeFactory: async () => opts.runtimeFactory(await envReady),
+        instance,
+        ...(opts.port ? { port: opts.port } : {}),
+        open: false,
+        log,
+    });
+    const send = (m) => {
+        if (process.send)
+            process.send(m);
+        if (process.connected)
+            process.disconnect();
+    };
+    if (srv.reused) {
+        send({ url: srv.url, reused: true });
+        return 0;
+    }
+    const rec = {
+        pid: process.pid,
+        port: Number(new URL(srv.url).port),
+        url: srv.url,
+        startedAt: new Date().toISOString(),
+        instance,
+    };
+    const processStart = await processStartTime(process.pid);
+    if (processStart)
+        rec.processStart = processStart;
+    await writeFile(pidFilePath(paths), `${JSON.stringify(rec, null, 2)}\n`, { mode: 0o600 });
+    send({ url: srv.url, reused: false });
+    await new Promise((resolve) => {
+        const stop = (sig) => {
+            log(`[${new Date().toISOString()}] ${sig}: stopping`);
+            void srv.close().finally(resolve);
+        };
+        process.once('SIGTERM', () => stop('SIGTERM'));
+        process.once('SIGINT', () => stop('SIGINT'));
+        process.on('SIGHUP', () => { });
+    });
+    const now = await readPidFile(paths);
+    if (now?.pid === process.pid)
+        await rm(pidFilePath(paths), { force: true });
+    return 0;
+}
+/** Stops the background Panel named in the pid file, signalling it only when checkPanel confirms it. */
+export async function stopBackgroundPanel(paths) {
+    const rec = await readPidFile(paths);
+    if (!rec)
+        return { status: 'not-running' };
+    const check = await checkPanel(rec);
+    if (check.status === 'stale') {
+        await rm(pidFilePath(paths), { force: true });
+        return { status: 'not-running', detail: `removed a stale pid file (${check.reason})` };
+    }
+    if (check.status === 'unconfirmed')
+        return { status: 'failed', pid: rec.pid, detail: check.reason };
+    try {
+        process.kill(rec.pid, 'SIGTERM');
+    }
+    catch (err) {
+        return { status: 'failed', pid: rec.pid, detail: err.message };
+    }
+    const deadline = Date.now() + STOP_TIMEOUT_MS;
+    while (alive(rec.pid) && Date.now() < deadline)
+        await sleep(100);
+    if (alive(rec.pid))
+        return {
+            status: 'failed',
+            pid: rec.pid,
+            detail: `process ${rec.pid} did not exit within ${STOP_TIMEOUT_MS / 1000} s; stop it with \`kill ${rec.pid}\``,
+        };
+    await rm(pidFilePath(paths), { force: true });
+    return { status: 'stopped', pid: rec.pid, url: rec.url };
+}