sideby 0.12.0 → 0.13.0

package/dist/src/core/browser-profiles.js

@@ -0,0 +1,361 @@
+// Browser Sign-ins (spec §3.24, ADR-0023): which Browser Profile of Google Chrome signed in to each Account's vendor
+// website, from Chrome's local data on this computer only. Read-only: `Local State` gives each profile's folder,
+// display name and the email of the Google account it is signed in to Chrome with, `Local Storage/leveldb` the key
+// names of claude.ai and chatgpt.com (core/leveldb-keys.ts). Never Cookies, Login Data, IndexedDB or the Keychain,
+// never a value, never the network. The Host-side id each match needs (families/browser.ts) is compared in memory
+// and never leaves this module. Opening a website starts Chrome unchanged with `open`, through `DesktopDeps.exec`,
+// so tests never start a real browser. On WSL the Chrome is the one installed on Windows: its folders come from one
+// `cmd.exe` call, and it is started with `cmd.exe /c start` (spec §3.24, WSL).
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join, win32 } from 'node:path';
+import { matchedOrigins, websiteDef } from '../families/browser.js';
+import { editConfigBrowser } from './config.js';
+import { depsFor, findApp } from './desktop-app.js';
+import { UserError } from './errors.js';
+import { localStorageKeys } from './leveldb-keys.js';
+const OPEN = '/usr/bin/open';
+export const CHROME = {
+    title: 'Google Chrome',
+    bundleId: 'com.google.Chrome',
+    bundleNames: ['Google Chrome.app'],
+};
+export const CHROME_DOWNLOAD = 'https://www.google.com/chrome/';
+const MAX_LOCAL_STATE = 16 * 1024 * 1024;
+/** Chrome's user data folder on macOS. */
+export function chromeUserData(home) {
+    return join(home, 'Library', 'Application Support', 'Google', 'Chrome');
+}
+/** A Windows drive path (`C:\Windows`) as WSL mounts it (`/mnt/c/Windows`); undefined for anything else. */
+function toUnix(win, mount) {
+    const m = /^([A-Za-z]):\\(.*)$/.exec(win.trim());
+    if (!m)
+        return undefined;
+    return join(mount, m[1].toLowerCase(), ...m[2].split('\\').filter(Boolean));
+}
+const windowsMemo = new Map();
+/**
+ * `%LOCALAPPDATA%` and the Program Files folders, from one `cmd.exe` call, remembered for the process. When cmd.exe
+ * fails, the only Windows user with Chrome data under `<mount>/c/Users`; several are not guessed between.
+ */
+async function windowsDirs(deps, mount, problems) {
+    const hit = windowsMemo.get(mount);
+    if (hit)
+        return hit;
+    const r = await deps.exec(join(mount, 'c', 'Windows', 'System32', 'cmd.exe'), [
+        '/d',
+        '/c',
+        'echo %LOCALAPPDATA%^|%ProgramFiles%^|%ProgramFiles(x86)%',
+    ]);
+    const parts = r.code === 0 ? r.stdout.trim().split('|') : [];
+    const dir = (win) => {
+        const unix = win ? toUnix(win, mount) : undefined;
+        return win && unix ? { win: win.trim(), unix } : undefined;
+    };
+    const local = dir(parts[0]);
+    if (local) {
+        const found = {
+            localAppData: local,
+            programs: [dir(parts[1]), dir(parts[2])].filter((d) => d !== undefined),
+        };
+        windowsMemo.set(mount, found);
+        return found;
+    }
+    // cmd.exe did not answer (interop off, or no C: drive): look for the one Windows user that has Chrome.
+    const users = join(mount, 'c', 'Users');
+    const withChrome = [];
+    for (const u of await readdir(users).catch(() => [])) {
+        const st = await stat(join(users, u, 'AppData', 'Local', 'Google', 'Chrome', 'User Data', 'Local State')).catch(() => null);
+        if (st?.isFile())
+            withChrome.push(u);
+    }
+    if (withChrome.length > 1)
+        problems.push(`several Windows users have Chrome data (${withChrome.join(', ')}) and cmd.exe did not say which is yours; check that WSL can run Windows programs (\`cmd.exe /c ver\`)`);
+    const only = withChrome.length === 1 ? withChrome[0] : undefined;
+    return {
+        ...(only
+            ? {
+                localAppData: {
+                    win: `C:\\Users\\${only}\\AppData\\Local`,
+                    unix: join(users, only, 'AppData', 'Local'),
+                },
+            }
+            : {}),
+        programs: [],
+    };
+}
+/** Where Chrome keeps its data: under the home folder on macOS, in Windows' own folder on WSL; null elsewhere. */
+async function userDataFor(rt, deps, problems) {
+    if (deps.platform === 'darwin')
+        return chromeUserData(rt.paths.home);
+    if (!deps.wslMount)
+        return null;
+    const win = await windowsDirs(deps, deps.wslMount, problems);
+    return win.localAppData ? join(win.localAppData.unix, 'Google', 'Chrome', 'User Data') : null;
+}
+/** Characters cmd.exe would treat as more than a path, even inside quotes. */
+const CMD_UNSAFE = /["%&|<>^\r\n]/;
+const EMAIL = /^[^\s@]{1,64}@[^\s@]{1,190}$/;
+/**
+ * Each profile's folder, display name and Google account email (`user_name`, kept only when it is an email) from
+ * `Local State`; nothing else of the file is kept.
+ */
+async function profileEntries(userData, problems) {
+    const file = join(userData, 'Local State');
+    let text;
+    try {
+        const st = await stat(file);
+        if (!st.isFile() || st.size > MAX_LOCAL_STATE) {
+            problems.push(`${file} is not a readable file`);
+            return [];
+        }
+        text = await readFile(file, 'utf8');
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return null;
+        problems.push(`${file} could not be read`);
+        return [];
+    }
+    let cache;
+    try {
+        cache = JSON.parse(text)?.profile?.info_cache;
+    }
+    catch {
+        problems.push(`${file} is not valid JSON`);
+        return [];
+    }
+    if (typeof cache !== 'object' || cache === null)
+        return [];
+    const out = [];
+    for (const [dir, info] of Object.entries(cache)) {
+        if (!/^[\w .-]{1,64}$/.test(dir) || dir.startsWith('.'))
+            continue;
+        const n = info?.name;
+        const name = typeof n === 'string' && n.trim() && !/\p{Cc}/u.test(n) ? n.trim().slice(0, 80) : dir;
+        const u = info?.user_name;
+        const email = typeof u === 'string' && EMAIL.test(u.trim()) ? u.trim() : undefined;
+        out.push({ dir, name, ...(email ? { email } : {}) });
+    }
+    return out;
+}
+/** Key names per profile folder, remembered while none of its LevelDB files changed. */
+const keyMemo = new Map();
+async function profileKeys(dir, origins) {
+    let sig = origins.join(',');
+    try {
+        for (const n of (await readdir(dir)).sort()) {
+            const st = await stat(join(dir, n)).catch(() => null);
+            if (st)
+                sig += `|${n}:${st.size}:${st.mtimeMs}:${st.ino}`;
+        }
+    }
+    catch {
+        return { keys: new Map(), problems: [] };
+    }
+    const hit = keyMemo.get(dir);
+    if (hit?.sig === sig)
+        return hit.value;
+    const value = await localStorageKeys(dir, origins);
+    keyMemo.set(dir, { sig, value });
+    return value;
+}
+const BOUNDARY = /[A-Za-z0-9_]/;
+/** `id` appears in `key` as a whole segment: not glued to another letter, digit or underscore. */
+export function keyHasId(key, id) {
+    const k = key.toLowerCase();
+    const i0 = id.toLowerCase();
+    for (let i = k.indexOf(i0); i >= 0; i = k.indexOf(i0, i + 1)) {
+        const before = k[i - 1];
+        const after = k[i + i0.length];
+        if ((before === undefined || !BOUNDARY.test(before)) && (after === undefined || !BOUNDARY.test(after)))
+            return true;
+    }
+    return false;
+}
+/** Accounts that a Browser Sign-in can apply to: Subscription Accounts of built-in Families with a website. */
+function eligible(rt, accounts) {
+    return accounts.filter((a) => a.kind !== 'api' &&
+        websiteDef(a.family) &&
+        rt.plugins.some((p) => p.source === 'builtin' && p.families.includes(a.family)));
+}
+/** The Browser Report for `sideby browser` and the Panel. Reads nothing of the browser while it is off. */
+export async function browserReport(rt, accounts) {
+    const enabled = rt.config.browser?.signIns === true;
+    const list = eligible(rt, accounts);
+    const fams = [...new Set(list.map((a) => a.family))];
+    const families = {
+        matched: fams.filter((f) => websiteDef(f)?.match),
+        openOnly: fams.filter((f) => !websiteDef(f)?.match),
+    };
+    const base = { enabled, browser: CHROME.title, families };
+    if (!enabled)
+        return { ...base, found: false, profiles: [], problems: [] };
+    const problems = [];
+    const userData = await userDataFor(rt, depsFor(rt), problems);
+    if (userData === null)
+        return { ...base, found: false, profiles: [], problems };
+    const entries = await profileEntries(userData, problems);
+    if (entries === null)
+        return { ...base, found: false, profiles: [], problems };
+    const ids = [];
+    for (const a of list) {
+        const m = websiteDef(a.family)?.match;
+        const id = m ? await m.signInId(a) : undefined;
+        if (m && id)
+            ids.push({ ref: a.ref, origin: m.origin, id });
+    }
+    const origins = matchedOrigins();
+    const read = [];
+    for (const e of entries) {
+        const r = await profileKeys(join(userData, e.dir, 'Local Storage', 'leveldb'), origins);
+        for (const p of r.problems)
+            problems.push(`${e.name}: ${p}`);
+        const counts = ids.map(({ origin, id }) => [...(r.keys.get(origin) ?? [])].filter((k) => keyHasId(k, id)).length);
+        const changedAt = 'changedAt' in r && r.changedAt ? new Date(r.changedAt).toISOString() : undefined;
+        read.push({ e, counts, ...(changedAt ? { changedAt } : {}) });
+    }
+    // A site keeps a few keys for whoever is signed in, and may leave one behind after a sign-out or a switch. So a
+    // trace counts only when it is at least half as strong as the strongest one of the same id (across profiles) and of
+    // the same website in the same profile (across ids).
+    const bestOfId = ids.map((_, i) => Math.max(0, ...read.map((x) => x.counts[i])));
+    const profiles = read.map(({ e, counts, changedAt }) => {
+        const bestOfSite = (origin) => Math.max(0, ...ids.map((x, i) => (x.origin === origin ? counts[i] : 0)));
+        const signIns = ids
+            .filter((x, i) => {
+            const n = counts[i];
+            return n > 0 && n * 2 >= bestOfId[i] && n * 2 >= bestOfSite(x.origin);
+        })
+            .map((x) => x.ref);
+        return {
+            dir: e.dir,
+            name: e.name,
+            ...(e.email ? { email: e.email } : {}),
+            signIns,
+            ...(changedAt ? { changedAt } : {}),
+        };
+    });
+    profiles.sort((a, b) => (b.changedAt ?? '').localeCompare(a.changedAt ?? '') || a.dir.localeCompare(b.dir));
+    return { ...base, found: true, profiles, problems };
+}
+/**
+ * Opens an Account's vendor website in one Browser Profile: the one given (folder or name), else the only profile
+ * that signed in to it. Several or none: refuses with the choices, so the caller can ask. `profile` must be a folder
+ * Chrome lists in `Local State`.
+ */
+export async function openInBrowser(rt, account, profile) {
+    const deps = depsFor(rt);
+    if (deps.platform !== 'darwin' && !deps.wslMount)
+        throw new UserError(`opening a browser user works on macOS and WSL only for now (this is ${deps.platform}); open ${websiteDef(account.family)?.url ?? 'the website'} yourself`, { code: 'unsupported' });
+    const site = websiteDef(account.family);
+    if (!site || account.kind === 'api' || !eligible(rt, [account]).length)
+        throw new UserError(`${account.ref} has no website to open; only Claude, Codex and Grok subscription accounts do`, {
+            code: 'no-website',
+        });
+    const problems = [];
+    const launch = await chromeLauncher(deps, problems);
+    if (!launch)
+        throw new UserError(`${CHROME.title} is not installed; get it from ${CHROME_DOWNLOAD}`, {
+            code: 'not-installed',
+        });
+    const entries = (await profileEntries(launch.userData ?? chromeUserData(rt.paths.home), problems)) ?? [];
+    if (!entries.length)
+        throw new UserError(`${CHROME.title} has no browser users yet; open it once, then try again`, {
+            code: 'no-profiles',
+        });
+    let pick;
+    if (profile) {
+        pick = entries.find((e) => e.dir === profile);
+        if (!pick) {
+            const p = profile.toLowerCase();
+            const byName = entries.filter((e) => e.name.toLowerCase() === p);
+            if (!byName.length)
+                byName.push(...entries.filter((e) => e.email?.toLowerCase() === p));
+            if (byName.length > 1)
+                throw new UserError(`several browser users are named "${profile}"; pass the folder instead: ${byName.map((e) => e.dir).join(', ')}`, { code: 'profile-ambiguous' });
+            pick = byName[0];
+        }
+        if (!pick)
+            throw new UserError(`no browser user "${profile}"; choose one of: ${entries.map((e) => `${e.name} (${e.dir})`).join(', ')}`, { code: 'profile-unknown' });
+    }
+    else {
+        const report = rt.config.browser?.signIns === true ? await browserReport(rt, [account]) : undefined;
+        const found = report?.profiles.filter((p) => p.signIns.includes(account.ref)) ?? [];
+        if (found.length !== 1) {
+            const why = !site.match
+                ? `${site.url.replace('https://', '')} keeps nothing sideby can compare, so name the browser user`
+                : !report
+                    ? `finding it is off (turn it on with \`sideby browser --enable\`)`
+                    : found.length
+                        ? `${found.length} browser users signed in to ${account.ref}`
+                        : `no browser user signed in to ${account.ref}`;
+            const choices = (found.length ? found : entries).map((e) => `${e.name} (${e.dir})`).join(', ');
+            throw new UserError(`${why}; pass --profile with one of: ${choices}`, { code: 'profile-needed' });
+        }
+        pick = entries.find((e) => e.dir === found[0]?.dir);
+        if (!pick)
+            throw new UserError('that browser user is gone; run `sideby browser` again', {
+                code: 'profile-unknown',
+            });
+    }
+    const [cmd, ...args] = launch.command(`--profile-directory=${pick.dir}`, site.url);
+    const r = await deps.exec(cmd, args);
+    if (r.code !== 0)
+        throw new UserError(`could not open ${CHROME.title}: ${launch.windows ? `cmd.exe exited with ${r.code}` : r.stderr.trim() || `open exited with ${r.code}`}; open it once by hand, then try again`, { code: 'open-failed' });
+    return {
+        ref: account.ref,
+        url: site.url,
+        profile: { dir: pick.dir, name: pick.name },
+        command: [cmd, ...args],
+    };
+}
+/** How to start Chrome here: `open` on macOS, `cmd.exe /c start` with Windows' chrome.exe on WSL; null when absent. */
+async function chromeLauncher(deps, problems) {
+    if (deps.platform === 'darwin') {
+        const app = await findApp(CHROME, deps, { spotlight: true });
+        return app && { windows: false, command: (...a) => [OPEN, '-na', app.path, '--args', ...a] };
+    }
+    const mount = deps.wslMount;
+    const win = await windowsDirs(deps, mount, problems);
+    const local = win.localAppData;
+    if (!local)
+        return null;
+    for (const d of [...win.programs, local]) {
+        const exe = join(d.unix, 'Google', 'Chrome', 'Application', 'chrome.exe');
+        if (!(await stat(exe).catch(() => null))?.isFile())
+            continue;
+        const winExe = win32.join(d.win, 'Google', 'Chrome', 'Application', 'chrome.exe');
+        if (CMD_UNSAFE.test(winExe))
+            continue;
+        const cmd = join(mount, 'c', 'Windows', 'System32', 'cmd.exe');
+        return {
+            userData: join(local.unix, 'Google', 'Chrome', 'User Data'),
+            windows: true,
+            command: (...a) => [cmd, '/d', '/c', 'start', '', winExe, ...a],
+        };
+    }
+    return null;
+}
+/** What turning Browser Sign-ins on reads, for the confirmation in the CLI and the Panel. */
+export const BROWSER_READS = [
+    "the name of each Google Chrome browser user and the Google account email it uses in Chrome (from Chrome's Local State)",
+    'the key names claude.ai and chatgpt.com keep in each browser user’s Local Storage, never their values',
+    'the account id in each Claude and Codex login file, only to compare; it is never shown or saved',
+];
+/** Turns Browser Sign-ins on or off in config `browser.signIns`; without `apply`, shows the change only. */
+export async function setBrowserSignIns(rt, on, opts) {
+    const r = await editConfigBrowser(rt.paths.configFile, (cur) => {
+        const next = { ...cur };
+        if (on)
+            next.signIns = true;
+        else
+            delete next.signIns;
+        return next;
+    }, { dryRun: !opts.apply });
+    return {
+        enabled: on,
+        changed: r.changed,
+        applied: opts.apply && r.changed,
+        file: rt.paths.configFile,
+        reads: BROWSER_READS,
+    };
+}

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

@@ -66,6 +66,9 @@ export declare const ConfigSchema: Type.TObject<{
         check: Type.TOptional<Type.TBoolean>;
         auto: Type.TOptional<Type.TBoolean>;
     }>>;
+    browser: Type.TOptional<Type.TObject<{
+        signIns: Type.TOptional<Type.TBoolean>;
+    }>>;
     shellInitFile: Type.TOptional<Type.TObject<{
         zsh: Type.TOptional<Type.TString>;
         bash: Type.TOptional<Type.TString>;
@@ -101,6 +104,18 @@ export declare function editConfigUpdate(file: string, edit: (current: UpdateCon
     before: UpdateConfig | undefined;
     after: UpdateConfig | undefined;
 }>;
+export type BrowserConfig = NonNullable<Config['browser']>;
+/**
+ * `sideby browser --enable|--disable` and the Panel's switch (spec §3.24): changes the config `browser` key with
+ * `edit` (see `editConfigKey` for how the file is written). With `dryRun`, shows the change without writing.
+ */
+export declare function editConfigBrowser(file: string, edit: (current: BrowserConfig) => BrowserConfig, opts?: {
+    dryRun?: boolean;
+}): Promise<{
+    changed: boolean;
+    before: BrowserConfig | undefined;
+    after: BrowserConfig | undefined;
+}>;
 export type AccountsConfig = NonNullable<Config['accounts']>;
 /**
  * `sideby model` (spec §3.19): changes the config `accounts` key with `edit` (see `editConfigKey` for how the file is

package/dist/src/core/config.js

@@ -101,6 +101,11 @@ export const ConfigSchema = Type.Object({
             description: 'Install a newer version by itself after a check, when no `sideby run` is running and the version is not a major one. Off by default.',
         })),
     }, { additionalProperties: false, description: 'Update Check and Auto Update (ADR-0021).' })),
+    browser: Type.Optional(Type.Object({
+        signIns: Type.Optional(Type.Boolean({
+            description: "Look in Google Chrome's local data for which browser user signed in to each Account's website (key names only, never cookies or passwords; nothing leaves this computer). Off by default.",
+        })),
+    }, { additionalProperties: false, description: 'Browser Sign-ins (spec §3.24, ADR-0023).' })),
     shellInitFile: Type.Optional(Type.Object({
         zsh: Type.Optional(Type.String({ minLength: 1 })),
         bash: Type.Optional(Type.String({ minLength: 1 })),
@@ -167,7 +172,7 @@ async function configTarget(file) {
 }
 /**
  * Re-reads the config file, lets `edit` change one top-level `key` (sideby writes only `aliases`, `handoff`,
- * `accounts` and `update`, spec §3.10), and writes the result: every other key and their order kept (with `$schema`), 2-space JSON
+ * `accounts`, `update` and `browser`, spec §3.10), and writes the result: every other key and their order kept (with `$schema`), 2-space JSON
  * with a trailing newline, atomically, keeping the file's mode (0600 for a new file). Refuses, without writing, a
  * file that is not valid JSON or not a valid config, a result that is not a valid config, or a file that changed
  * while sideby wrote it. `edit` returns null to leave the file alone; `dryRun` returns the change without writing.
@@ -239,6 +244,13 @@ export function editConfigHandoff(file, edit, opts = {}) {
 export function editConfigUpdate(file, edit, opts = {}) {
     return editConfigKey(file, 'update', 'change the setting', (current) => edit(current ?? {}), opts);
 }
+/**
+ * `sideby browser --enable|--disable` and the Panel's switch (spec §3.24): changes the config `browser` key with
+ * `edit` (see `editConfigKey` for how the file is written). With `dryRun`, shows the change without writing.
+ */
+export function editConfigBrowser(file, edit, opts = {}) {
+    return editConfigKey(file, 'browser', 'change the setting', (current) => edit(current ?? {}), opts);
+}
 /**
  * `sideby model` (spec §3.19): changes the config `accounts` key with `edit` (see `editConfigKey` for how the file is
  * written). With `dryRun`, shows the change without writing.

package/dist/src/core/create.js

@@ -4,6 +4,7 @@ import { HookError } from '../plugins/bus.js';
 import { ACCOUNT_NAME, accountAt, accountDirOf, mainDirOf } from './accounts.js';
 import { UserError } from './errors.js';
 import { assertInside, lstatOrNull, parseJsonSafely, replaceWithCopy, statOrNull, writeFileAtomic, } from './fs-safe.js';
+import { installHint } from './launch.js';
 import { secretFileTemplate } from './secret-file.js';
 import { itemPaths } from './share-modes.js';
 export class CreateError extends UserError {
@@ -33,7 +34,7 @@ export async function createAccount(opts) {
         throw new CreateError(`"${name}" is not a valid account name: use 1–32 lowercase letters, digits or "-", not "main"`);
     const mainDir = mainDirOf(family, home);
     if (!(await statOrNull(mainDir))?.isDirectory())
-        throw new CreateError(`${family.title} has no main account at ${mainDir}; install ${family.bin} (${family.installUrl}) and run it once first`);
+        throw new CreateError(`${family.title} has no main account at ${mainDir}; install ${family.bin} (${installHint(family)}) and run it once first`);
     const dir = accountDirOf(family, home, name);
     if (await lstatOrNull(dir))
         throw new CreateError(`${dir} already exists; pick another name or run \`sideby doctor\``);

package/dist/src/core/desktop-app.d.ts

@@ -15,6 +15,8 @@ export interface DesktopDeps {
     appDirs: readonly string[];
     /** Runs a program and resolves with its exit code and output; never rejects. */
     exec(cmd: string, args: readonly string[], env?: Env): Promise<ExecResult>;
+    /** On WSL, where Windows drives are mounted (normally `/mnt`, so C: is `/mnt/c`); undefined elsewhere. */
+    wslMount?: string;
 }
 /**
  * Internal: makes every Desktop App call made with this Runtime use `deps` instead of the machine. Only
@@ -108,6 +110,6 @@ export declare function withDesktopApps<T extends {
  * Doctor's extra checks for an Account's App Data (spec §3.20): the Desktop App's shared files under `link` rules,
  * only when that Account's App Data folder exists, never for the Main Account (it uses the app's default) or an API
  * Account. Results are named `app-data/<path>` and are not counted in `shared`. The App Data is the repair boundary:
- * a fix may only add a missing link inside it, never replace a real file.
+ * a fix may only add a missing link inside it or sync a file's `key` there, never replace a real file.
  */
 export declare function checkAppData(plugins: readonly LoadedPlugin[], home: string, account: Account): Promise<CheckResult[]>;

package/dist/src/core/desktop-app.js

@@ -3,6 +3,7 @@
 // program sideby runs here (`open`, `ps`, `osascript`, `plutil`, `mdfind`) goes through `DesktopDeps.exec`, so
 // tests never start a real app.
 import { execFile } from 'node:child_process';
+import { readFileSync } from 'node:fs';
 import { chmod, mkdir, readdir, readFile, symlink } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 import { desktopDef, profileAppFor } from '../families/desktop.js';
@@ -28,12 +29,27 @@ const overrides = new WeakMap();
 export function bindDesktopDeps(rt, deps) {
     overrides.set(rt, deps);
 }
+/** This Linux runs under WSL: `WSL_DISTRO_NAME` is set, or the kernel says Microsoft. */
+function isWsl() {
+    if (process.platform !== 'linux')
+        return false;
+    if (process.env.WSL_DISTRO_NAME)
+        return true;
+    try {
+        return /microsoft/i.test(readFileSync('/proc/sys/kernel/osrelease', 'utf8'));
+    }
+    catch {
+        return false;
+    }
+}
 export function depsFor(rt) {
     const o = overrides.get(rt) ?? {};
+    const wslMount = 'platform' in o || 'wslMount' in o ? o.wslMount : isWsl() ? '/mnt' : undefined;
     return {
         platform: o.platform ?? process.platform,
         appDirs: o.appDirs ?? ['/Applications', join(rt.paths.home, 'Applications')],
         exec: o.exec ?? defaultExec,
+        ...(wslMount ? { wslMount } : {}),
     };
 }
 /** The Desktop App of a Family, only when a built-in Plugin provides that Family (a plugin may not claim one). */
@@ -351,7 +367,7 @@ export async function withDesktopApps(rt, accounts, statuses) {
  * Doctor's extra checks for an Account's App Data (spec §3.20): the Desktop App's shared files under `link` rules,
  * only when that Account's App Data folder exists, never for the Main Account (it uses the app's default) or an API
  * Account. Results are named `app-data/<path>` and are not counted in `shared`. The App Data is the repair boundary:
- * a fix may only add a missing link inside it, never replace a real file.
+ * a fix may only add a missing link inside it or sync a file's `key` there, never replace a real file.
  */
 export async function checkAppData(plugins, home, account) {
     if (account.isMain || account.kind === 'api')
@@ -367,13 +383,18 @@ export async function checkAppData(plugins, home, account) {
         const item = { path: f.path, mode: 'link' };
         const mainPath = join(home, f.mainPath);
         const p = join(dir, item.path);
-        const res = await checkItem({ account, item, mainPath, accountPath: p, accountDir: dir, force: false });
+        const ctx = { account, item, mainPath, accountPath: p, accountDir: dir, force: false };
+        let res = await checkItem(ctx);
+        // The Desktop App writes its own file when the Main Account had none at first open, and replaces the link when
+        // it saves its preferences: not the user's doing, and a new link would be replaced again. With a `key`, only
+        // that key has to match the main file; `--fix` syncs it inside the App Data.
+        const own = res.results.some((r) => r.code === 'link.real-file');
+        if (own && f.key)
+            res = await checkItem({ ...ctx, item: { path: f.path, mode: 'json-key', key: f.key } });
         for (const r of res.results) {
             if (r.level === 'ok')
                 continue;
-            // The Desktop App writes its own file when the Main Account had none at first open, and may replace the link
-            // later: not the user's doing, so a warning with the way to share, never a failure and never replaced.
-            const own = r.code === 'link.real-file'
+            const mine = r.code === 'link.real-file'
                 ? {
                     level: 'warn',
                     message: `${item.path} is ${def.title}'s own copy for this account, not a link to the main account's`,
@@ -382,9 +403,9 @@ export async function checkAppData(plugins, home, account) {
                 : {};
             out.push({
                 ...r,
-                ...own,
-                item: `app-data/${item.path}`,
-                message: `${def.title} data: ${own.message ?? r.message}`,
+                ...mine,
+                item: `app-data/${r.item.startsWith(item.path) ? r.item : item.path}`,
+                message: `${def.title} data: ${mine.message ?? r.message}`,
             });
         }
     }

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

@@ -16,6 +16,13 @@ export interface PreparedLaunch {
 export type HostLaunch = Pick<PreparedLaunch, 'family' | 'bin' | 'args' | 'env' | 'title'>;
 /** Finds an executable on PATH; returns null when the Host is not installed. */
 export declare function which(bin: string, env: Env): Promise<string | null>;
+/**
+ * The first PATH entry named `bin` that exists but cannot run, such as a link left dangling by an interrupted
+ * upgrade; null when there is none. Only meaningful when `which` found nothing.
+ */
+export declare function brokenOnPath(bin: string, env: Env): Promise<string | null>;
+/** What to tell a user whose Host cannot run: the install command when the Family has one, else the page. */
+export declare function installHint(family: Pick<FamilyDef, 'installUrl' | 'installCommand'>): string;
 /**
  * Why a Host could not run `sideby` by name, or null when it can: something the Host runs on its own (the status line
  * tap, the handoff hook) needs sideby installed on PATH, not the npx cache, which can disappear. `why` completes

package/dist/src/core/launch.js

@@ -2,7 +2,7 @@ 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 { realpathOrNull } from './fs-safe.js';
+import { lstatOrNull, realpathOrNull } from './fs-safe.js';
 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) {
@@ -20,6 +20,26 @@ export async function which(bin, env) {
     }
     return null;
 }
+/**
+ * The first PATH entry named `bin` that exists but cannot run, such as a link left dangling by an interrupted
+ * upgrade; null when there is none. Only meaningful when `which` found nothing.
+ */
+export async function brokenOnPath(bin, env) {
+    for (const dir of (env.PATH ?? '').split(delimiter)) {
+        if (!dir)
+            continue;
+        const p = join(dir, bin);
+        if (await lstatOrNull(p))
+            return p;
+    }
+    return null;
+}
+/** What to tell a user whose Host cannot run: the install command when the Family has one, else the page. */
+export function installHint(family) {
+    return family.installCommand
+        ? `\`${family.installCommand}\` (or see ${family.installUrl})`
+        : family.installUrl;
+}
 /**
  * Why a Host could not run `sideby` by name, or null when it can: something the Host runs on its own (the status line
  * tap, the handoff hook) needs sideby installed on PATH, not the npx cache, which can disappear. `why` completes
@@ -141,7 +161,7 @@ export function spawnHost(p) {
         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}`
+                ? `${p.family.title} is not installed (\`${p.bin}\` not found on PATH); install it: ${installHint(p.family)}`
                 : `could not start ${p.bin}: ${err.message}`;
             process.stderr.write(`sideby: ${msg}\n`);
             resolve(1);

package/dist/src/core/leveldb-keys.d.ts

@@ -0,0 +1,14 @@
+/** Files larger than this are skipped and reported. */
+export declare const MAX_LEVELDB_FILE: number;
+/** Snappy raw-format decompression (https://github.com/google/snappy/blob/main/format_description.txt). */
+export declare function snappyDecompress(src: Uint8Array): Uint8Array;
+/**
+ * The Local Storage key names of `origins` (`https://claude.ai`), from a `Local Storage/leveldb` directory. A key
+ * deleted later is left out. `changedAt` is the newest modification time of the files read. Files that are too large
+ * or unreadable go to `problems` (their name only).
+ */
+export declare function localStorageKeys(dir: string, origins: readonly string[]): Promise<{
+    keys: Map<string, Set<string>>;
+    changedAt?: number;
+    problems: string[];
+}>;