sideby 0.0.0-stage → 0.1.0

package/dist/src/core/fs-safe.d.ts

@@ -0,0 +1,38 @@
+import type { Stats } from 'node:fs';
+export declare function lstatOrNull(p: string): Promise<Stats | null>;
+export declare function statOrNull(p: string): Promise<Stats | null>;
+export declare function realpathOrNull(p: string): Promise<string | null>;
+/** True when `link` is a symlink whose resolved target is the same file as `target`. */
+export declare function linksTo(link: string, target: string): Promise<boolean>;
+export declare function sha256(data: string | Uint8Array): string;
+export declare function fileHash(p: string): Promise<string | null>;
+/**
+ * Writes via a temp file in the same directory, fsyncs, then renames over `path`.
+ * Refuses to write when `path` is a symlink so a write can never pass through a link into another directory.
+ */
+export declare function writeFileAtomic(path: string, data: string | Uint8Array, mode?: number, 
+/** Checked after the temp file is complete, right before the rename; false aborts and keeps `path`. */
+beforeRename?: () => Promise<boolean>): Promise<boolean>;
+/**
+ * Writes only if the file still has `expectedHash` (null = must not exist), checking both before writing and
+ * again right before the rename. This narrows, but cannot close, the window in which another program (for
+ * example the Host saving the same file) could write in between: plain files offer no compare-and-swap.
+ */
+export declare function writeIfUnchanged(path: string, expectedHash: string | null, data: string | Uint8Array, mode?: number): Promise<boolean>;
+/**
+ * Throws unless `target` stays inside `root` both by name (no `..`) and on disk (no parent directory that is a
+ * symlink leading elsewhere), so a repair can never write into another Account or the Main Account.
+ */
+export declare function assertInside(root: string, target: string): Promise<void>;
+/** JSON.parse whose error never quotes the input: parse errors from Node include a slice of the text. */
+export declare function parseJsonSafely(text: string, label: string): unknown;
+/** Recursive comparison of files, directories and symlink targets. Modes and times are ignored. */
+export declare function sameContent(a: string, b: string): Promise<boolean>;
+/**
+ * Copies `src` (resolving it if it is a symlink) to `dst`, keeping modes, hidden files and nested symlinks.
+ * Builds the copy beside `dst` and swaps it in, so a failure leaves the old `dst` untouched.
+ * Refuses when `dst` is a symlink: callers must remove links explicitly.
+ */
+export declare function replaceWithCopy(src: string, dst: string): Promise<void>;
+export declare function isEmptyDir(p: string): Promise<boolean>;
+export declare function permBits(st: Stats): number;

package/dist/src/core/fs-safe.js

@@ -0,0 +1,205 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { cp, lstat, open, readdir, readFile, readlink, realpath, rename, rm, stat } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, relative, sep } from 'node:path';
+export async function lstatOrNull(p) {
+    try {
+        return await lstat(p);
+    }
+    catch {
+        return null;
+    }
+}
+export async function statOrNull(p) {
+    try {
+        return await stat(p);
+    }
+    catch {
+        return null;
+    }
+}
+export async function realpathOrNull(p) {
+    try {
+        return await realpath(p);
+    }
+    catch {
+        return null;
+    }
+}
+/** True when `link` is a symlink whose resolved target is the same file as `target`. */
+export async function linksTo(link, target) {
+    const st = await lstatOrNull(link);
+    if (!st?.isSymbolicLink())
+        return false;
+    const [a, b] = await Promise.all([realpathOrNull(link), realpathOrNull(target)]);
+    return a !== null && a === b;
+}
+export function sha256(data) {
+    return createHash('sha256').update(data).digest('hex');
+}
+export async function fileHash(p) {
+    try {
+        return sha256(await readFile(p));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Writes via a temp file in the same directory, fsyncs, then renames over `path`.
+ * Refuses to write when `path` is a symlink so a write can never pass through a link into another directory.
+ */
+export async function writeFileAtomic(path, data, mode = 0o600, 
+/** Checked after the temp file is complete, right before the rename; false aborts and keeps `path`. */
+beforeRename) {
+    const existing = await lstatOrNull(path);
+    if (existing?.isSymbolicLink())
+        throw new Error(`refusing to write through a symlink: ${path}`);
+    const tmp = join(dirname(path), `.${basename(path)}.sideby-${randomBytes(6).toString('hex')}.tmp`);
+    const fh = await open(tmp, 'wx', mode);
+    try {
+        await fh.writeFile(data);
+        // Set the final mode before the rename (open's mode is reduced by the umask), so nothing can fail
+        // after the target has been replaced.
+        await fh.chmod(mode);
+        await fh.sync();
+    }
+    catch (err) {
+        await fh.close();
+        await rm(tmp, { force: true });
+        throw err;
+    }
+    await fh.close();
+    try {
+        if (beforeRename && !(await beforeRename())) {
+            await rm(tmp, { force: true });
+            return false;
+        }
+        await rename(tmp, path);
+        return true;
+    }
+    catch (err) {
+        await rm(tmp, { force: true });
+        throw err;
+    }
+}
+/**
+ * Writes only if the file still has `expectedHash` (null = must not exist), checking both before writing and
+ * again right before the rename. This narrows, but cannot close, the window in which another program (for
+ * example the Host saving the same file) could write in between: plain files offer no compare-and-swap.
+ */
+export async function writeIfUnchanged(path, expectedHash, data, mode = 0o600) {
+    if ((await fileHash(path)) !== expectedHash)
+        return false;
+    return writeFileAtomic(path, data, mode, async () => (await fileHash(path)) === expectedHash);
+}
+/**
+ * Throws unless `target` stays inside `root` both by name (no `..`) and on disk (no parent directory that is a
+ * symlink leading elsewhere), so a repair can never write into another Account or the Main Account.
+ */
+export async function assertInside(root, target) {
+    const rel = relative(root, target);
+    if (rel === '' || rel.startsWith('..') || isAbsolute(rel))
+        throw new Error(`refusing to write outside the account directory: ${target}`);
+    const rootReal = (await realpathOrNull(root)) ?? root;
+    let dir = dirname(target);
+    while (!(await lstatOrNull(dir))) {
+        const up = dirname(dir);
+        if (up === dir)
+            break;
+        dir = up;
+    }
+    const real = (await realpathOrNull(dir)) ?? dir;
+    if (real !== rootReal && !real.startsWith(`${rootReal}${sep}`))
+        throw new Error(`refusing to write outside the account directory: ${target} (a parent directory is a link)`);
+}
+/** JSON.parse whose error never quotes the input: parse errors from Node include a slice of the text. */
+export function parseJsonSafely(text, label) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error(`${label} is not valid JSON`);
+    }
+}
+/** Recursive comparison of files, directories and symlink targets. Modes and times are ignored. */
+export async function sameContent(a, b) {
+    const [sa, sb] = await Promise.all([lstatOrNull(a), lstatOrNull(b)]);
+    if (!sa || !sb)
+        return false;
+    if (sa.isSymbolicLink() || sb.isSymbolicLink()) {
+        if (!(sa.isSymbolicLink() && sb.isSymbolicLink()))
+            return false;
+        return (await readlink(a)) === (await readlink(b));
+    }
+    if (sa.isFile() && sb.isFile()) {
+        if (sa.size !== sb.size)
+            return false;
+        const [ba, bb] = await Promise.all([readFile(a), readFile(b)]);
+        return ba.equals(bb);
+    }
+    if (sa.isDirectory() && sb.isDirectory()) {
+        const [ea, eb] = await Promise.all([readdir(a), readdir(b)]);
+        if (ea.length !== eb.length)
+            return false;
+        ea.sort();
+        eb.sort();
+        for (let i = 0; i < ea.length; i++) {
+            if (ea[i] !== eb[i])
+                return false;
+            if (!(await sameContent(join(a, ea[i]), join(b, eb[i]))))
+                return false;
+        }
+        return true;
+    }
+    return false;
+}
+/**
+ * Copies `src` (resolving it if it is a symlink) to `dst`, keeping modes, hidden files and nested symlinks.
+ * Builds the copy beside `dst` and swaps it in, so a failure leaves the old `dst` untouched.
+ * Refuses when `dst` is a symlink: callers must remove links explicitly.
+ */
+export async function replaceWithCopy(src, dst) {
+    const existing = await lstatOrNull(dst);
+    if (existing?.isSymbolicLink())
+        throw new Error(`refusing to copy over a symlink: ${dst}`);
+    const source = (await realpathOrNull(src)) ?? src;
+    const tmp = join(dirname(dst), `.${basename(dst)}.sideby-${randomBytes(6).toString('hex')}.tmp`);
+    try {
+        await cp(source, tmp, {
+            recursive: true,
+            verbatimSymlinks: true,
+            preserveTimestamps: true,
+            errorOnExist: true,
+        });
+    }
+    catch (err) {
+        await rm(tmp, { recursive: true, force: true });
+        throw err;
+    }
+    if (!existing) {
+        await rename(tmp, dst);
+        return;
+    }
+    const old = `${tmp}.old`;
+    await rename(dst, old);
+    try {
+        await rename(tmp, dst);
+    }
+    catch (err) {
+        await rename(old, dst);
+        await rm(tmp, { recursive: true, force: true });
+        throw err;
+    }
+    await rm(old, { recursive: true, force: true });
+}
+export async function isEmptyDir(p) {
+    try {
+        return (await readdir(p)).length === 0;
+    }
+    catch {
+        return false;
+    }
+}
+export function permBits(st) {
+    return st.mode & 0o777;
+}

package/dist/src/core/handoff.d.ts

@@ -0,0 +1,41 @@
+import type { Account, LoginState, QuotaResult } from '../types.ts';
+export type HandoffState = 'ready' | 'unknown' | 'api' | 'full' | 'logged-out';
+export interface HandoffCandidate {
+    ref: string;
+    name: string;
+    isMain: boolean;
+    kind: Account['kind'];
+    login: LoginState | 'not-needed';
+    quota: QuotaResult;
+}
+export interface HandoffEntry {
+    ref: string;
+    kind: Account['kind'];
+    state: HandoffState;
+    /** Quota Pressure in percent; null when the Account has no Quota. */
+    pressure: number | null;
+    /** For `full`: when the last full window resets, so the Account is usable again. */
+    resetsAt?: string;
+    /** When the Quota was recorded; it is only as fresh as the Account's last session. */
+    observedAt?: string;
+}
+export interface HandoffPlan {
+    family: string;
+    /** The recommended Account, or null when none can be used now. */
+    pick: string | null;
+    /** Every Account, best first; the ones that cannot be picked come last. */
+    accounts: HandoffEntry[];
+    /**
+     * Whether any Account has Quota data. Without any, the pick is only a guess (often the Account that just ran
+     * out), so `sideby next` does not start it and the Panel shows no recommendation.
+     */
+    hasQuota: boolean;
+    /** Set when nothing can be picked and some Accounts are full: the first to come back. */
+    earliestReset?: {
+        ref: string;
+        at: string;
+    };
+}
+export declare function planHandoff(family: string, candidates: readonly HandoffCandidate[], now: Date, opts?: {
+    includeApi?: boolean;
+}): HandoffPlan;

package/dist/src/core/handoff.js

@@ -0,0 +1,54 @@
+import { QUOTA_FAIL_PERCENT, quotaPressure, windowReset } from './quota-levels.js';
+const ORDER = { ready: 0, unknown: 1, api: 2, full: 3, 'logged-out': 4 };
+/** A full Account without a readable reset time sorts after every one that has one. */
+const resetTime = (e) => (e.resetsAt ? Date.parse(e.resetsAt) : Number.POSITIVE_INFINITY);
+function entry(c, now) {
+    const pressure = quotaPressure(c.quota, now);
+    const base = {
+        ref: c.ref,
+        kind: c.kind,
+        pressure,
+        ...(c.quota.status === 'ok' ? { observedAt: c.quota.observedAt } : {}),
+    };
+    if (c.kind === 'api')
+        return { ...base, state: 'api' };
+    if (c.login === 'logged-out')
+        return { ...base, state: 'logged-out' };
+    if (pressure === null)
+        return { ...base, state: 'unknown' };
+    if (pressure < QUOTA_FAIL_PERCENT)
+        return { ...base, state: 'ready' };
+    // Usable again only when every full window has reset: the latest of their reset times.
+    let last;
+    if (c.quota.status === 'ok')
+        for (const w of c.quota.windows) {
+            const t = Date.parse(w.resetsAt);
+            if (w.usedPercent >= QUOTA_FAIL_PERCENT && !windowReset(w.resetsAt, now) && Number.isFinite(t))
+                last = Math.max(last ?? t, t);
+        }
+    return { ...base, state: 'full', ...(last === undefined ? {} : { resetsAt: new Date(last).toISOString() }) };
+}
+export function planHandoff(family, candidates, now, opts = {}) {
+    const byRef = new Map(candidates.map((c) => [c.ref, c]));
+    const tie = (a, b) => {
+        const x = byRef.get(a.ref);
+        const y = byRef.get(b.ref);
+        return Number(y.isMain) - Number(x.isMain) || x.name.localeCompare(y.name, undefined, { numeric: true });
+    };
+    const accounts = candidates
+        .map((c) => entry(c, now))
+        .sort((a, b) => ORDER[a.state] - ORDER[b.state] ||
+        (a.state === 'ready' ? a.pressure - b.pressure : 0) ||
+        (a.state === 'full' ? resetTime(a) - resetTime(b) || 0 : 0) ||
+        tie(a, b));
+    const usable = (e) => e.state === 'ready' || e.state === 'unknown' || (e.state === 'api' && Boolean(opts.includeApi));
+    const pick = accounts.find(usable)?.ref ?? null;
+    const hasQuota = accounts.some((e) => e.state === 'ready' || e.state === 'full');
+    const plan = { family, pick, accounts, hasQuota };
+    if (pick === null) {
+        const first = accounts.find((e) => e.state === 'full' && e.resetsAt);
+        if (first?.resetsAt)
+            plan.earliestReset = { ref: first.ref, at: first.resetsAt };
+    }
+    return plan;
+}

package/dist/src/core/identity.d.ts

@@ -0,0 +1,23 @@
+import type { AccountIdentity } from '../types.ts';
+/** The email when `v` looks like one address, else undefined. */
+export declare function cleanEmail(v: unknown): string | undefined;
+/** A short single-line organization name, else undefined. */
+export declare function cleanOrg(v: unknown): string | undefined;
+/** `{ email?, org? }` without empty fields, or undefined when both are missing. */
+export declare function identityOf(email: unknown, org?: unknown): AccountIdentity | undefined;
+/**
+ * The email claim of a JWT such as Codex's `id_token`: the payload segment is base64url-decoded and parsed, and only
+ * `email` is kept. The signature is not checked (the token is the Host's own file, read for display only); the
+ * token itself and every other claim are dropped.
+ */
+export declare function jwtEmail(token: unknown): string | undefined;
+/** Counters of the identity cache, for tests. */
+export declare const identityMemoStats: {
+    hits: number;
+    misses: number;
+};
+/**
+ * Reads one JSON login file and keeps only what `pick` returns from it. Undefined when the file is missing, is not
+ * JSON or holds no identity. `pick` must return identity fields only (identityOf builds one).
+ */
+export declare function identityFromJsonFile(path: string, pick: (data: unknown) => AccountIdentity | undefined): Promise<AccountIdentity | undefined>;

package/dist/src/core/identity.js

@@ -0,0 +1,79 @@
+// Who an Account is signed in as: the email (and for Claude the organization) from the Host's own login file
+// (ADR-0003). Only these identity fields are read out of the file; tokens and every other field are dropped as soon
+// as the file is parsed, and are never stored, logged or returned. Each file's pick is remembered until the file
+// changes (core/file-memo.ts).
+import { readFile, stat } from 'node:fs/promises';
+import { FileMemo } from './file-memo.js';
+const MAX_EMAIL = 254;
+const MAX_ORG = 120;
+// One address, no spaces or control characters; the shape only, not a deliverability check.
+const EMAIL = /^[^\s@\p{Cc}]+@[^\s@\p{Cc}]+\.[^\s@\p{Cc}]+$/u;
+/** The email when `v` looks like one address, else undefined. */
+export function cleanEmail(v) {
+    return typeof v === 'string' && v.length <= MAX_EMAIL && EMAIL.test(v) ? v : undefined;
+}
+/** A short single-line organization name, else undefined. */
+export function cleanOrg(v) {
+    if (typeof v !== 'string')
+        return undefined;
+    const s = v.trim();
+    return s && s.length <= MAX_ORG && !/\p{Cc}/u.test(s) ? s : undefined;
+}
+/** `{ email?, org? }` without empty fields, or undefined when both are missing. */
+export function identityOf(email, org) {
+    const e = cleanEmail(email);
+    const o = cleanOrg(org);
+    if (!e && !o)
+        return undefined;
+    return { ...(e ? { email: e } : {}), ...(o ? { org: o } : {}) };
+}
+/**
+ * The email claim of a JWT such as Codex's `id_token`: the payload segment is base64url-decoded and parsed, and only
+ * `email` is kept. The signature is not checked (the token is the Host's own file, read for display only); the
+ * token itself and every other claim are dropped.
+ */
+export function jwtEmail(token) {
+    if (typeof token !== 'string')
+        return undefined;
+    const parts = token.split('.');
+    if (parts.length !== 3 || !parts[1])
+        return undefined;
+    try {
+        const claims = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+        return typeof claims === 'object' && claims !== null
+            ? cleanEmail(claims.email)
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+const memo = new FileMemo();
+/** Counters of the identity cache, for tests. */
+export const identityMemoStats = memo.stats;
+/**
+ * Reads one JSON login file and keeps only what `pick` returns from it. Undefined when the file is missing, is not
+ * JSON or holds no identity. `pick` must return identity fields only (identityOf builds one).
+ */
+export async function identityFromJsonFile(path, pick) {
+    let st;
+    try {
+        st = await stat(path);
+    }
+    catch {
+        return undefined;
+    }
+    if (!st.isFile())
+        return undefined;
+    const pass = memo.pass(path);
+    const value = await pass.get(path, st, async () => {
+        try {
+            return pick(JSON.parse(await readFile(path, 'utf8'))) ?? null;
+        }
+        catch {
+            return null;
+        }
+    });
+    pass.done();
+    return value ?? undefined;
+}

package/dist/src/core/last-doctor.d.ts

@@ -0,0 +1,36 @@
+import type { Finding } from '../types.ts';
+import type { DoctorReport } from './doctor.ts';
+export type StoredFinding = Omit<Finding, 'fix'>;
+export interface HistoryEntry {
+    at: string;
+    findings: StoredFinding[];
+}
+export interface DoctorHistory {
+    version: 2;
+    /** Latest result per Account ref; an Account absent here was never checked. */
+    accounts: Record<string, HistoryEntry>;
+    /** Latest Family-level findings (for example a missing Main Account), per Family id. */
+    general: Record<string, HistoryEntry>;
+}
+/** What one Doctor run covered: every Family, one Family, or one Account. */
+export type DoctorScope = {
+    kind: 'all';
+} | {
+    kind: 'family';
+    family: string;
+} | {
+    kind: 'account';
+    ref: string;
+};
+/**
+ * Pure merge: Accounts inside the scope are replaced by this run (and dropped when the run no longer
+ * reports them: deleted, ignored, no longer an Account); Accounts outside the scope are kept. Family-level
+ * findings are replaced for every Family the run touched, even with an empty list.
+ */
+export declare function mergeDoctorHistory(prev: DoctorHistory | undefined, report: DoctorReport, scope: DoctorScope, at: Date): DoctorHistory;
+/** Every finding in the history, Family-level first. */
+export declare function historyFindings(h: DoctorHistory): StoredFinding[];
+/** Older formats (without per-Account entries) count as no history. */
+export declare function readDoctorHistory(stateDir: string): Promise<DoctorHistory | undefined>;
+/** Best effort: recording a check never fails the check itself. */
+export declare function writeDoctorHistory(stateDir: string, history: DoctorHistory): Promise<void>;

package/dist/src/core/last-doctor.js

@@ -0,0 +1,69 @@
+// Doctor history: the latest result per Account (and per Family for Family-level findings), kept in
+// sideby's state directory so the Panel can tell "healthy" from "not checked". A run only replaces what
+// it covered, so checking one Account never makes the others look healthy.
+import { mkdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { writeFileAtomic } from './fs-safe.js';
+const FILE = 'last-doctor.json';
+const strip = ({ fix: _fix, ...f }) => f;
+const familyOfRef = (ref) => ref.slice(0, ref.indexOf(':'));
+function inScope(scope, ref) {
+    if (scope.kind === 'all')
+        return true;
+    if (scope.kind === 'family')
+        return familyOfRef(ref) === scope.family;
+    return ref === scope.ref;
+}
+/**
+ * Pure merge: Accounts inside the scope are replaced by this run (and dropped when the run no longer
+ * reports them: deleted, ignored, no longer an Account); Accounts outside the scope are kept. Family-level
+ * findings are replaced for every Family the run touched, even with an empty list.
+ */
+export function mergeDoctorHistory(prev, report, scope, at) {
+    const when = at.toISOString();
+    const accounts = {};
+    for (const [ref, entry] of Object.entries(prev?.accounts ?? {}))
+        if (!inScope(scope, ref))
+            accounts[ref] = entry;
+    for (const a of report.accounts)
+        accounts[a.ref] = { at: when, findings: a.findings.map(strip) };
+    const touched = new Set(scope.kind === 'all'
+        ? [...report.accounts.map((a) => a.family), ...report.general.map((f) => familyOfRef(f.account))]
+        : [scope.kind === 'family' ? scope.family : familyOfRef(scope.ref)]);
+    const general = {};
+    for (const [family, entry] of Object.entries(prev?.general ?? {}))
+        if (scope.kind !== 'all' && !touched.has(family))
+            general[family] = entry;
+    for (const family of touched)
+        general[family] = {
+            at: when,
+            findings: report.general.filter((f) => familyOfRef(f.account) === family).map(strip),
+        };
+    return { version: 2, accounts, general };
+}
+/** Every finding in the history, Family-level first. */
+export function historyFindings(h) {
+    return [...Object.values(h.general), ...Object.values(h.accounts)].flatMap((e) => e.findings);
+}
+/** Older formats (without per-Account entries) count as no history. */
+export async function readDoctorHistory(stateDir) {
+    try {
+        const data = JSON.parse(await readFile(join(stateDir, FILE), 'utf8'));
+        if (data?.version !== 2 || typeof data.accounts !== 'object' || typeof data.general !== 'object')
+            return undefined;
+        return data;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Best effort: recording a check never fails the check itself. */
+export async function writeDoctorHistory(stateDir, history) {
+    try {
+        await mkdir(stateDir, { recursive: true, mode: 0o700 });
+        await writeFileAtomic(join(stateDir, FILE), `${JSON.stringify(history, null, 2)}\n`);
+    }
+    catch {
+        // ignore
+    }
+}

package/dist/src/core/launch.d.ts

@@ -0,0 +1,35 @@
+import type { HookBus } from '../plugins/bus.ts';
+import type { Account, Env, FamilyDef } from '../types.ts';
+export interface PreparedLaunch {
+    account: Account;
+    family: FamilyDef;
+    bin: string;
+    args: string[];
+    env: Env;
+    /** Printed before launching when sign-in happens inside the Host. */
+    notice?: string;
+}
+/** Finds an executable on PATH; returns null when the Host is not installed. */
+export declare function which(bin: string, env: Env): Promise<string | null>;
+/**
+ * Builds the Host's environment and arguments (spec §3.5):
+ * copy the current env, clear Hijack Variables, merge the Secret File, set the select variable,
+ * then let `launch.before` hooks adjust or abort. Never touches the caller's environment.
+ */
+export declare function prepareLaunch(opts: {
+    account: Account;
+    family: FamilyDef;
+    baseEnv: Env;
+    accountArgs: readonly string[];
+    userArgs: readonly string[];
+    command: 'run' | 'login';
+    bus: HookBus;
+}): Promise<PreparedLaunch>;
+/**
+ * Runs the Host with the terminal attached and returns sideby's exit code (spec §3.5):
+ * the Host's own code, 128 + signal number when a signal ended it, 1 when it could not start.
+ * While the Host runs, sideby ignores SIGINT/SIGQUIT (the terminal delivers them to the whole foreground
+ * process group, so the Host receives them directly) and forwards SIGTERM/SIGHUP once. SIGTSTP keeps its
+ * default action so Ctrl-Z suspends sideby together with the Host and `fg` resumes both.
+ */
+export declare function runHost(p: PreparedLaunch): Promise<number>;