sideby 0.0.0-stage → 0.2.1

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,37 @@
+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;
+}
+/** What `runHost` needs: a prepared Account launch, or the Host run unchanged (`sideby resume`). */
+export type HostLaunch = Pick<PreparedLaunch, 'family' | 'bin' | 'args' | 'env'>;
+/** 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: HostLaunch): Promise<number>;

package/dist/src/core/launch.js

@@ -0,0 +1,108 @@
+import { spawn } from 'node:child_process';
+import { access, constants } from 'node:fs/promises';
+import { constants as osConstants } from 'node:os';
+import { delimiter, join } from 'node:path';
+import { readSecretFile } from './secret-file.js';
+/** Finds an executable on PATH; returns null when the Host is not installed. */
+export async function which(bin, env) {
+    for (const dir of (env.PATH ?? '').split(delimiter)) {
+        if (!dir)
+            continue;
+        const p = join(dir, bin);
+        try {
+            await access(p, constants.X_OK);
+            return p;
+        }
+        catch {
+            // keep looking
+        }
+    }
+    return 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 async function prepareLaunch(opts) {
+    const { account, family } = opts;
+    const env = { ...opts.baseEnv };
+    for (const v of family.hijackVars)
+        delete env[v];
+    delete env[family.selectVar];
+    if (account.secretFile)
+        Object.assign(env, await readSecretFile(account.secretFile, opts.baseEnv));
+    if (!account.isMain)
+        env[family.selectVar] = account.dir;
+    let args;
+    let notice;
+    if (opts.command === 'login') {
+        // Family arguments still apply: Codex must store a non-main login in the Account's own file.
+        const base = family.defaultArgs?.(account, []) ?? [];
+        if (family.login.args)
+            args = [...base, ...family.login.args];
+        else {
+            args = base;
+            notice = family.login.hint;
+        }
+    }
+    else {
+        args = [...(family.defaultArgs?.(account, opts.userArgs) ?? []), ...opts.accountArgs, ...opts.userArgs];
+    }
+    await opts.bus.run('launch.before', family.id, {
+        account,
+        family,
+        env,
+        args,
+        config: {},
+        command: opts.command,
+    });
+    return { account, family, bin: family.bin, args, env, ...(notice ? { notice } : {}) };
+}
+/**
+ * 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 function runHost(p) {
+    return new Promise((resolve) => {
+        const child = spawn(p.bin, p.args, { stdio: 'inherit', env: p.env });
+        const ignore = () => { };
+        const forwarded = new Set();
+        const forward = (sig) => () => {
+            if (forwarded.has(sig) || child.exitCode !== null || child.signalCode !== null)
+                return;
+            forwarded.add(sig);
+            child.kill(sig);
+        };
+        const handlers = [
+            ['SIGINT', ignore],
+            ['SIGQUIT', ignore],
+            ['SIGTERM', forward('SIGTERM')],
+            ['SIGHUP', forward('SIGHUP')],
+        ];
+        for (const [s, h] of handlers)
+            process.on(s, h);
+        const cleanup = () => {
+            for (const [s, h] of handlers)
+                process.off(s, h);
+        };
+        child.once('error', (err) => {
+            cleanup();
+            const msg = err.code === 'ENOENT'
+                ? `${p.family.title} is not installed (\`${p.bin}\` not found on PATH); install it: ${p.family.installUrl}`
+                : `could not start ${p.bin}: ${err.message}`;
+            process.stderr.write(`sideby: ${msg}\n`);
+            resolve(1);
+        });
+        child.once('exit', (code, signal) => {
+            cleanup();
+            if (signal)
+                resolve(128 + (osConstants.signals[signal] ?? 0));
+            else
+                resolve(code ?? 1);
+        });
+    });
+}

package/dist/src/core/login-path.d.ts

@@ -0,0 +1,23 @@
+import type { Env } from '../types.ts';
+export declare const LOGIN_PATH_TIMEOUT_MS = 5000;
+export interface LoginPathOptions {
+    /** Shell to ask; defaults to `$SHELL`, then the account's shell, then `/bin/sh`. */
+    shell?: string;
+    timeoutMs?: number;
+}
+export interface LoginPathResult {
+    path: string;
+    /** `login-shell` when the shell answered, `fallback` when its answer was unusable and `path` is the current one. */
+    source: 'login-shell' | 'fallback';
+    /** Why the fallback was used. */
+    reason?: string;
+}
+/** Joins PATH lists, first occurrence wins, dropping empty and relative entries. */
+export declare function mergePaths(...lists: (string | undefined)[]): string;
+/** Reads the PATH between the markers; rc files may print anything before or after them. */
+export declare function parseMarkedPath(stdout: string): string | undefined;
+/**
+ * Asks the login shell (`$SHELL -ilc`) for its PATH and merges it in front of `env.PATH`.
+ * Never throws: on a timeout, a missing shell or unreadable output it returns the current PATH.
+ */
+export declare function loginShellPath(env: Env, opts?: LoginPathOptions): Promise<LoginPathResult>;

package/dist/src/core/login-path.js

@@ -0,0 +1,96 @@
+// PATH as the user's login shell sets it. An app started from Finder, a dock or launchd gets a minimal PATH, so
+// Hosts installed under ~/.local/bin, ~/.grok/bin or a version manager would look "not installed".
+import { spawn } from 'node:child_process';
+import { userInfo } from 'node:os';
+import { delimiter, isAbsolute } from 'node:path';
+const BEGIN = '__SIDEBY_PATH_BEGIN__';
+const END = '__SIDEBY_PATH_END__';
+export const LOGIN_PATH_TIMEOUT_MS = 5000;
+/** Joins PATH lists, first occurrence wins, dropping empty and relative entries. */
+export function mergePaths(...lists) {
+    const seen = new Set();
+    for (const list of lists)
+        for (const dir of (list ?? '').split(delimiter))
+            if (dir && isAbsolute(dir) && !seen.has(dir))
+                seen.add(dir);
+    return [...seen].join(delimiter);
+}
+/** Reads the PATH between the markers; rc files may print anything before or after them. */
+export function parseMarkedPath(stdout) {
+    const end = stdout.lastIndexOf(END);
+    if (end === -1)
+        return undefined;
+    const begin = stdout.lastIndexOf(BEGIN, end);
+    if (begin === -1)
+        return undefined;
+    const value = stdout.slice(begin + BEGIN.length, end).trim();
+    if (!value || /[\r\n]/.test(value))
+        return undefined;
+    const dirs = value.split(delimiter).filter((d) => d && isAbsolute(d));
+    return dirs.length ? dirs.join(delimiter) : undefined;
+}
+function defaultShell(env) {
+    if (env.SHELL && isAbsolute(env.SHELL))
+        return env.SHELL;
+    try {
+        const s = userInfo().shell;
+        if (s && isAbsolute(s))
+            return s;
+    }
+    catch { }
+    return '/bin/sh';
+}
+/**
+ * Asks the login shell (`$SHELL -ilc`) for its PATH and merges it in front of `env.PATH`.
+ * Never throws: on a timeout, a missing shell or unreadable output it returns the current PATH.
+ */
+export function loginShellPath(env, opts = {}) {
+    const current = env.PATH ?? '';
+    const shell = opts.shell ?? defaultShell(env);
+    const timeoutMs = opts.timeoutMs ?? LOGIN_PATH_TIMEOUT_MS;
+    // `printenv` prints the exported PATH the same way in sh, bash, zsh and fish (where $PATH is a list).
+    const script = `echo ${BEGIN}; printenv PATH; echo ${END}`;
+    return new Promise((resolve) => {
+        let done = false;
+        let out = '';
+        const finish = (reason) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            // A shell that printed its PATH but hangs on exit (an rc file started something) still counts.
+            const found = parseMarkedPath(out);
+            if (found)
+                resolve({ path: mergePaths(found, current), source: 'login-shell' });
+            else
+                resolve({ path: current, source: 'fallback', reason: reason ?? 'no PATH in the shell output' });
+        };
+        let child;
+        try {
+            child = spawn(shell, ['-ilc', script], {
+                env: env,
+                stdio: ['ignore', 'pipe', 'ignore'],
+                // Own process group, so a timeout also stops whatever the rc files started.
+                detached: true,
+            });
+        }
+        catch (err) {
+            resolve({ path: current, source: 'fallback', reason: err instanceof Error ? err.message : String(err) });
+            return;
+        }
+        const timer = setTimeout(() => {
+            try {
+                if (child.pid)
+                    process.kill(-child.pid, 'SIGKILL');
+            }
+            catch { }
+            finish(`${shell} did not answer within ${timeoutMs} ms`);
+        }, timeoutMs);
+        child.stdout?.on('data', (d) => {
+            if (out.length < 1_000_000)
+                out += d;
+        });
+        child.once('error', (err) => finish(err.message));
+        child.once('close', () => finish());
+    });
+}

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

@@ -0,0 +1,13 @@
+import type { Env } from '../types.ts';
+export interface Paths {
+    home: string;
+    configDir: string;
+    stateDir: string;
+    configFile: string;
+    userPluginsDir: string;
+}
+export declare function resolvePaths(env?: Env): Paths;
+/** Expands a leading `~` or `~/`; returns undefined for relative paths so callers can reject them. */
+export declare function expandUserPath(p: string, home: string): string | undefined;
+/** Replaces the HOME prefix with `~` for user-facing output. */
+export declare function tildify(p: string, home: string): string;

package/dist/src/core/paths.js

@@ -0,0 +1,32 @@
+import { homedir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+export function resolvePaths(env = process.env) {
+    const home = env.HOME || homedir();
+    const configBase = absOr(env.XDG_CONFIG_HOME, join(home, '.config'));
+    const stateBase = absOr(env.XDG_STATE_HOME, join(home, '.local', 'state'));
+    const configDir = join(configBase, 'sideby');
+    return {
+        home,
+        configDir,
+        stateDir: join(stateBase, 'sideby'),
+        configFile: join(configDir, 'config.json'),
+        userPluginsDir: join(configDir, 'plugins'),
+    };
+}
+/** Expands a leading `~` or `~/`; returns undefined for relative paths so callers can reject them. */
+export function expandUserPath(p, home) {
+    if (p === '~')
+        return home;
+    if (p.startsWith('~/'))
+        return join(home, p.slice(2));
+    return isAbsolute(p) ? p : undefined;
+}
+/** Replaces the HOME prefix with `~` for user-facing output. */
+export function tildify(p, home) {
+    if (p === home)
+        return '~';
+    return p.startsWith(`${home}/`) ? `~${p.slice(home.length)}` : p;
+}
+function absOr(value, fallback) {
+    return value && isAbsolute(value) ? value : fallback;
+}

package/dist/src/core/quota-levels.d.ts

@@ -0,0 +1,19 @@
+import type { QuotaResult } from '../types.ts';
+/**
+ * How full a Quota window must be before the CLI and the Panel warn about it, and the Usage window both
+ * report. One rule for both surfaces: the Panel interpolates these numbers into its inline script.
+ */
+export declare const QUOTA_FAIL_PERCENT = 85;
+export declare const QUOTA_WARN_PERCENT = 60;
+/** Days of Usage every Family reports. */
+export declare const USAGE_DAYS = 7;
+export type QuotaLevel = 'ok' | 'warn' | 'fail';
+export declare function quotaLevel(usedPercent: number): QuotaLevel;
+/** True once a window's reset time has passed; an unreadable time never counts as reset. */
+export declare function windowReset(resetsAt: string, now: Date): boolean;
+/**
+ * Quota Pressure: the used percent of the fullest window that has not reset yet (0 when all have reset),
+ * or null when the Account has no Quota. The Panel keeps its own copy (`quotaPressure` in page-logic.ts,
+ * -1 for null) because page-logic helpers must be self-contained; a test keeps the two equal.
+ */
+export declare function quotaPressure(quota: QuotaResult | undefined, now: Date): number | null;

package/dist/src/core/quota-levels.js

@@ -0,0 +1,34 @@
+/**
+ * How full a Quota window must be before the CLI and the Panel warn about it, and the Usage window both
+ * report. One rule for both surfaces: the Panel interpolates these numbers into its inline script.
+ */
+export const QUOTA_FAIL_PERCENT = 85;
+export const QUOTA_WARN_PERCENT = 60;
+/** Days of Usage every Family reports. */
+export const USAGE_DAYS = 7;
+export function quotaLevel(usedPercent) {
+    if (usedPercent >= QUOTA_FAIL_PERCENT)
+        return 'fail';
+    if (usedPercent >= QUOTA_WARN_PERCENT)
+        return 'warn';
+    return 'ok';
+}
+/** True once a window's reset time has passed; an unreadable time never counts as reset. */
+export function windowReset(resetsAt, now) {
+    const t = Date.parse(resetsAt);
+    return Number.isFinite(t) && t <= now.getTime();
+}
+/**
+ * Quota Pressure: the used percent of the fullest window that has not reset yet (0 when all have reset),
+ * or null when the Account has no Quota. The Panel keeps its own copy (`quotaPressure` in page-logic.ts,
+ * -1 for null) because page-logic helpers must be self-contained; a test keeps the two equal.
+ */
+export function quotaPressure(quota, now) {
+    if (quota?.status !== 'ok' || quota.windows.length === 0)
+        return null;
+    let max = 0;
+    for (const w of quota.windows)
+        if (!windowReset(w.resetsAt, now))
+            max = Math.max(max, Math.min(100, Number(w.usedPercent) || 0));
+    return max;
+}

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

@@ -0,0 +1,9 @@
+import type { Account, FamilyDef } from '../types.ts';
+export interface ResumeRoute {
+    /** The session the Host arguments resume by id; absent when they resume none. */
+    sessionId?: string;
+    /** The Account that last wrote that session; absent when no Account holds it. */
+    account?: Account;
+}
+/** Asks every Account of the Family for the session and picks the one that wrote it last. */
+export declare function findResumeRoute(family: FamilyDef, accounts: readonly Account[], args: readonly string[]): Promise<ResumeRoute>;

package/dist/src/core/resume.js

@@ -0,0 +1,15 @@
+/** Asks every Account of the Family for the session and picks the one that wrote it last. */
+export async function findResumeRoute(family, accounts, args) {
+    const sessionId = family.resumedSession?.(args);
+    if (!sessionId || !family.sessionWrittenAt)
+        return {};
+    const own = accounts.filter((a) => a.family === family.id);
+    const written = await Promise.all(own.map((a) => family.sessionWrittenAt(a, sessionId).catch(() => undefined)));
+    let best;
+    own.forEach((account, i) => {
+        const at = written[i];
+        if (at !== undefined && (!best || at > best.at))
+            best = { account, at };
+    });
+    return best ? { sessionId, account: best.account } : { sessionId };
+}

package/dist/src/core/secret-file.d.ts

@@ -0,0 +1,30 @@
+import { UserError } from './errors.ts';
+export declare class SecretFileError extends UserError {
+}
+/** Non-secret locations a Secret File may reference from the environment, such as `$HOME/bin/notify`. */
+export declare const SECRET_FILE_ENV_REFS: readonly ['HOME', 'USER', 'LOGNAME', 'TMPDIR', 'XDG_CONFIG_HOME', 'XDG_DATA_HOME', 'XDG_STATE_HOME', 'XDG_CACHE_HOME'];
+/**
+ * Parses the dotenv subset sideby supports: KEY=VALUE, optional `export `, quotes and comments.
+ * `$NAME` and `${NAME}` in unquoted or double-quoted values expand to a key defined earlier in the
+ * same file, else to one of SECRET_FILE_ENV_REFS from `env`; no other variable is read and nothing is
+ * executed. Errors name the line, never its content.
+ */
+export declare function parseSecretFile(text: string, file: string, env?: Readonly<Record<string, string | undefined>>): Record<string, string>;
+export type SecretFileState = {
+    kind: 'ok';
+} | {
+    kind: 'missing';
+} | {
+    kind: 'not-file';
+} | {
+    kind: 'mode';
+    mode: number;
+};
+/**
+ * The one Secret File rule, used by Launch and by Doctor: the Account's own regular file (never a link)
+ * with mode 600. Only the file's type and mode are inspected, never its contents.
+ */
+export declare function inspectSecretFile(file: string): Promise<SecretFileState>;
+/** Reads a Secret File after inspectSecretFile accepts it. */
+export declare function readSecretFile(file: string, env?: Readonly<Record<string, string | undefined>>): Promise<Record<string, string>>;
+export declare function secretFileTemplate(vars: readonly string[], familyTitle: string): string;