sideby 0.6.0 → 0.8.0

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

@@ -0,0 +1,382 @@
+// Opens a Family's Desktop App for one Account (spec §3.20, ADR-0015): macOS only, built-in claude and codex only.
+// The app bundle is started unchanged with `open`; another Account's instance gets its own App Data folder. Every
+// 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 { chmod, mkdir, readdir, readFile, symlink } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { desktopDef } from '../families/desktop.js';
+import { UserError } from './errors.js';
+import { lstatOrNull, statOrNull } from './fs-safe.js';
+import { checkItem } from './share-modes.js';
+const OPEN = '/usr/bin/open';
+const PS = '/bin/ps';
+const OSASCRIPT = '/usr/bin/osascript';
+const PLUTIL = '/usr/bin/plutil';
+const MDFIND = '/usr/bin/mdfind';
+function defaultExec(cmd, args, env) {
+    return new Promise((resolve) => execFile(cmd, [...args], { timeout: 15_000, maxBuffer: 16 * 1024 * 1024, ...(env ? { env: env } : {}) }, (err, stdout, stderr) => {
+        const code = err ? (typeof err.code === 'number' ? err.code : 1) : 0;
+        resolve({ code, stdout: String(stdout ?? ''), stderr: String(stderr ?? '') });
+    }));
+}
+const overrides = new WeakMap();
+/**
+ * Internal: makes every Desktop App call made with this Runtime use `deps` instead of the machine. Only
+ * `createRuntime` calls it, from its `desktop` option, which is the one way to replace the machine (tests).
+ */
+export function bindDesktopDeps(rt, deps) {
+    overrides.set(rt, deps);
+}
+function depsFor(rt) {
+    const o = overrides.get(rt) ?? {};
+    return {
+        platform: o.platform ?? process.platform,
+        appDirs: o.appDirs ?? ['/Applications', join(rt.paths.home, 'Applications')],
+        exec: o.exec ?? defaultExec,
+    };
+}
+/** The Desktop App of a Family, only when a built-in Plugin provides that Family (a plugin may not claim one). */
+export function desktopAppOf(plugins, familyId) {
+    const builtin = plugins.some((p) => p.source === 'builtin' && p.families.includes(familyId));
+    return builtin ? desktopDef(familyId) : undefined;
+}
+/** Where a non-main Account's App Data lives: `~/Library/Application Support/sideby/<family>/<name>`. */
+export function appDataDir(home, account) {
+    return join(home, 'Library', 'Application Support', 'sideby', account.family, account.name);
+}
+const plistString = (xml, key) => {
+    const m = new RegExp(`<key>${key}</key>\\s*<string>([^<]*)</string>`).exec(xml);
+    return m?.[1];
+};
+/** Reads string keys of an app's Info.plist: XML directly, a binary plist through `plutil`. */
+async function bundleInfo(deps, app) {
+    const file = join(app, 'Contents', 'Info.plist');
+    let text;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch {
+        return {};
+    }
+    if (text.startsWith('<?xml') || text.includes('<plist'))
+        return { id: plistString(text, 'CFBundleIdentifier'), exe: plistString(text, 'CFBundleExecutable') };
+    const read = async (key) => {
+        const r = await deps.exec(PLUTIL, ['-extract', key, 'raw', '-o', '-', file]);
+        return r.code === 0 ? r.stdout.trim() || undefined : undefined;
+    };
+    return { id: await read('CFBundleIdentifier'), exe: await read('CFBundleExecutable') };
+}
+/**
+ * Finds the app by bundle id: the usual names in the app folders first, then (with `spotlight`) Spotlight. Listing
+ * Accounts leaves Spotlight out to stay fast; opening one asks it too.
+ */
+export async function findApp(def, deps, opts = {}) {
+    const check = async (path) => {
+        if (!(await statOrNull(path))?.isDirectory())
+            return null;
+        const info = await bundleInfo(deps, path);
+        if (info.id !== def.bundleId)
+            return null;
+        return { path, executable: info.exe || basename(path, '.app') };
+    };
+    for (const dir of deps.appDirs)
+        for (const name of def.bundleNames) {
+            const found = await check(join(dir, name));
+            if (found)
+                return found;
+        }
+    if (!opts.spotlight)
+        return null;
+    const r = await deps.exec(MDFIND, [`kMDItemCFBundleIdentifier == "${def.bundleId}"`]);
+    if (r.code !== 0)
+        return null;
+    for (const line of r.stdout.split('\n')) {
+        const p = line.trim();
+        if (!p.endsWith('.app') || p.includes('/.Trash/'))
+            continue;
+        const found = await check(p);
+        if (found)
+            return found;
+    }
+    return null;
+}
+/** Every process with its command line, or null when `ps` failed (then nothing is known to run). */
+async function processes(deps) {
+    const r = await deps.exec(PS, ['-axo', 'pid=,command=']);
+    if (r.code !== 0)
+        return null;
+    const out = [];
+    for (const line of r.stdout.split('\n')) {
+        const m = /^\s*(\d+)\s+(.*)$/.exec(line);
+        if (m)
+            out.push({ pid: Number(m[1]), command: m[2].trimEnd() });
+    }
+    return out;
+}
+/** The arguments after the app's own executable, when `p` is the app's main process (not a helper). */
+function mainArgs(app, p) {
+    const exe = `/${basename(app.path)}/Contents/MacOS/${app.executable}`;
+    const at = p.command.indexOf(exe);
+    if (at === -1)
+        return null;
+    const rest = p.command.slice(at + exe.length);
+    return rest === '' || rest.startsWith(' ') ? rest : null;
+}
+/** The running instance of this Account: the one with its App Data, or for the Main Account the one without any. */
+export function instanceOf(app, appData, procs) {
+    return procs.find((p) => {
+        const args = mainArgs(app, p);
+        if (args === null)
+            return false;
+        if (appData === null)
+            return !args.includes('--user-data-dir=');
+        const flag = ` --user-data-dir=${appData}`;
+        const at = args.indexOf(flag);
+        if (at === -1)
+            return false;
+        const after = args.slice(at + flag.length);
+        return after === '' || after.startsWith(' ') || after === '/' || after.startsWith('/ ');
+    });
+}
+/**
+ * Brings a running app to the front as a Dock click does: a reopen event (`aevt/rapp`) to that one process, so an
+ * app whose windows were all closed opens one again, then NSRunningApplication activation. Activation alone makes
+ * such an app frontmost with nothing on screen (seen 2026-10-14 with the Codex app). Neither needs the Automation
+ * permission.
+ */
+async function activate(deps, pid) {
+    const p = Math.trunc(pid);
+    const script = [
+        "ObjC.import('AppKit');",
+        `const app = $.NSRunningApplication.runningApplicationWithProcessIdentifier(${p});`,
+        'if (!app.isNil()) {',
+        `  const target = $.NSAppleEventDescriptor.descriptorWithProcessIdentifier(${p});`,
+        '  const reopen = $.NSAppleEventDescriptor.appleEventWithEventClassEventIDTargetDescriptorReturnIDTransactionID(0x61657674, 0x72617070, target, -1, 0);',
+        '  reopen.sendEventWithOptionsTimeoutError(1, 5, null);',
+        '}',
+        "app.isNil() ? 'missing' : (app.activateWithOptions($.NSApplicationActivateAllWindows | $.NSApplicationActivateIgnoringOtherApps) ? 'ok' : 'refused')",
+    ].join(' ');
+    const r = await deps.exec(OSASCRIPT, ['-l', 'JavaScript', '-e', script]);
+    return r.code === 0 && r.stdout.trim() === 'ok';
+}
+/** The environment `open` runs with: the caller's, without anything that would pick another Account (spec §3.5). */
+function openEnv(base, family, def) {
+    const env = { ...base };
+    for (const v of family.hijackVars)
+        delete env[v];
+    delete env[family.selectVar];
+    for (const v of def.clearVars)
+        delete env[v];
+    for (const k of Object.keys(env))
+        if (k.startsWith('SIDEBY_') || isSessionVar(k))
+            delete env[k];
+    return env;
+}
+/**
+ * Variables an agent session sets for its own children; a Desktop App started from that session must not inherit
+ * them. Named one by one, so a user setting such as `CLAUDE_CODE_USE_BEDROCK` still reaches the app.
+ */
+const SESSION_PREFIXES = ['CODEX_COMPANION_', 'CODEX_SANDBOX'];
+const SESSION_VARS = new Set([
+    'CLAUDE_CODE_SESSION_ID',
+    'CLAUDE_CODE_MESSAGING_TOKEN',
+    'CLAUDE_CODE_ENTRYPOINT',
+    'CLAUDE_CODE_CHILD_SESSION',
+    'CLAUDE_PID',
+    'CLAUDE_PLUGIN_DATA',
+    'CLAUDECODE',
+    'CODEX_THREAD_ID',
+]);
+function isSessionVar(k) {
+    return SESSION_VARS.has(k) || SESSION_PREFIXES.some((p) => k.startsWith(p));
+}
+function notMac(platform) {
+    return new UserError(`opening a desktop app per account works on macOS only for now (this is ${platform}); use \`sideby run <account>\` for the terminal`, { code: 'not-macos' });
+}
+function notInstalled(def, deps) {
+    return new UserError(`${def.title} is not installed (looked in ${deps.appDirs.join(' and ')}); install it from ${def.installUrl}, then try again`, { code: 'app-not-installed' });
+}
+/**
+ * Opens the Account's Desktop App, or brings its running instance to the front. Never starts a second instance of the
+ * same Account, never ends a process, never touches the app bundle or the Host account directory.
+ */
+export async function openDesktopApp(rt, ref) {
+    const deps = depsFor(rt);
+    const account = await rt.resolve(ref);
+    const family = rt.families.get(account.family);
+    const def = family ? desktopAppOf(rt.plugins, account.family) : undefined;
+    if (!family || !def) {
+        const have = [...rt.families.keys()].filter((id) => desktopAppOf(rt.plugins, id));
+        throw new UserError(`${account.ref}: ${family?.title ?? account.family} has no desktop app sideby can open${have.length ? ` (only ${have.join(' and ')} accounts do)` : ''}; use \`sideby run ${account.ref}\``, { code: 'no-desktop-app' });
+    }
+    if (account.kind === 'api')
+        throw new UserError(`${account.ref} is an API account; ${def.title} signs in with a subscription only, so open it for a subscription account, or use \`sideby run ${account.ref}\``, { code: 'api-account' });
+    if (deps.platform !== 'darwin')
+        throw notMac(deps.platform);
+    const app = await findApp(def, deps, { spotlight: true });
+    if (!app)
+        throw notInstalled(def, deps);
+    const home = rt.paths.home;
+    const appData = account.isMain ? null : appDataDir(home, account);
+    const listed = await processes(deps);
+    const procs = listed ?? [];
+    const base = {
+        ref: account.ref,
+        family: account.family,
+        app: def.title,
+        appPath: app.path,
+        ...(appData ? { appData } : {}),
+        createdAppData: false,
+        linked: [],
+        notices: [],
+    };
+    const running = instanceOf(app, appData, procs);
+    if (running) {
+        const focused = await activate(deps, running.pid);
+        return {
+            ...base,
+            action: focused ? 'focused' : 'already-running',
+            notices: focused
+                ? []
+                : [
+                    `${def.title} is already open for ${account.ref}; switch to it from the Dock (sideby does not start a second one)`,
+                ],
+        };
+    }
+    let created = false;
+    let fresh = false;
+    const linked = [];
+    if (appData) {
+        const st = await lstatOrNull(appData);
+        if (st && !st.isDirectory())
+            throw new UserError(`${appData} is not a folder; move it away, then try again (sideby keeps ${def.title}'s data for ${account.ref} there)`, { code: 'app-data-invalid' });
+        if (!st) {
+            await mkdir(appData, { recursive: true, mode: 0o700 });
+            await chmod(appData, 0o700);
+            created = true;
+        }
+        const shared = new Set(def.sharedFiles.map((f) => f.path));
+        fresh = created || (await readdir(appData)).every((e) => shared.has(e));
+        if (fresh)
+            for (const f of def.sharedFiles) {
+                const target = join(appData, f.path);
+                const main = join(home, f.mainPath);
+                // Never replace anything: link only where nothing is, and only to a file the Main Account has.
+                if ((await lstatOrNull(target)) || !(await statOrNull(main))?.isFile())
+                    continue;
+                await symlink(main, target);
+                linked.push(f.path);
+            }
+    }
+    const notices = [];
+    if (!account.isMain && def.signInInApp && fresh) {
+        const others = procs.some((p) => mainArgs(app, p) !== null);
+        notices.push(others
+            ? `First time for ${account.ref}: sign in inside ${def.title} with the account you use for ${account.ref}, not one it suggests from another window. Close the other ${def.title} windows while you sign in, because the browser may send the sign-in back to one of them`
+            : `First time for ${account.ref}: sign in inside ${def.title} with the account you use for ${account.ref}, not one it suggests from another window`);
+    }
+    if (!def.signInInApp) {
+        const login = await Promise.resolve()
+            .then(() => family.loginState?.(account))
+            .catch(() => undefined);
+        if (login === 'logged-out')
+            notices.push(`${account.ref} is not signed in yet; run \`sideby login ${account.ref}\` first. If ${def.title} offers "Welcome back" with your main account's email, do not pick it: that signs this account in as the main one. Choose to use another account`);
+    }
+    // The Main Account needs `-n` too: without it, `open` brings forward whichever instance runs, often another
+    // Account's window. A second Main instance cannot start here, since a running one was found above.
+    // Without a process list a running Main instance cannot be ruled out, so plain `open -a` (no second instance).
+    const mainArgsList = listed ? ['-n', '-a', app.path] : ['-a', app.path];
+    const args = appData ? def.openArgs(app.path, account.dir, appData) : mainArgsList;
+    const r = await deps.exec(OPEN, args, openEnv(rt.env, family, def));
+    if (r.code !== 0)
+        throw new UserError(`could not open ${def.title} for ${account.ref}: ${r.stderr.trim() || `open exited with ${r.code}`}; try opening ${app.path} once by hand, then try again`, { code: 'open-failed' });
+    return { ...base, action: 'started', createdAppData: created, linked, command: [OPEN, ...args], notices };
+}
+/**
+ * Desktop App state per Account ref for `sideby list` and the Panel: only on macOS, only Subscription Accounts of a
+ * Family that has one. One process listing for all of them; never throws.
+ */
+export async function desktopStatuses(rt, accounts) {
+    const out = new Map();
+    const deps = depsFor(rt);
+    if (deps.platform !== 'darwin')
+        return out;
+    try {
+        const eligible = accounts.filter((a) => a.kind !== 'api' && desktopAppOf(rt.plugins, a.family));
+        if (!eligible.length)
+            return out;
+        const apps = new Map();
+        for (const id of new Set(eligible.map((a) => a.family)))
+            apps.set(id, await findApp(desktopDef(id), deps));
+        const procs = [...apps.values()].some(Boolean) ? ((await processes(deps)) ?? []) : [];
+        for (const a of eligible) {
+            const app = apps.get(a.family) ?? null;
+            out.set(a.ref, {
+                app: desktopDef(a.family).title,
+                installed: app !== null,
+                running: app
+                    ? Boolean(instanceOf(app, a.isMain ? null : appDataDir(rt.paths.home, a), procs))
+                    : false,
+            });
+        }
+    }
+    catch {
+        // A display nicety: a failure leaves the field out.
+    }
+    return out;
+}
+/**
+ * Adds `desktopApp` to each status whose Account has one, for `sideby list` and the Panel. The process listing runs
+ * while `statuses` is still being built; the order of the statuses is kept.
+ */
+export async function withDesktopApps(rt, accounts, statuses) {
+    const [list, desktop] = await Promise.all([statuses, desktopStatuses(rt, accounts)]);
+    return list.map((s) => {
+        const d = desktop.get(s.ref);
+        return d ? { ...s, desktopApp: d } : s;
+    });
+}
+/**
+ * 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.
+ */
+export async function checkAppData(plugins, home, account) {
+    if (account.isMain || account.kind === 'api')
+        return [];
+    const def = desktopAppOf(plugins, account.family);
+    if (!def?.sharedFiles.length)
+        return [];
+    const dir = appDataDir(home, account);
+    if (!(await lstatOrNull(dir))?.isDirectory())
+        return [];
+    const out = [];
+    for (const f of def.sharedFiles) {
+        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 });
+        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'
+                ? {
+                    level: 'warn',
+                    message: `${item.path} is ${def.title}'s own copy for this account, not a link to the main account's`,
+                    hint: `${def.title} made it itself; that is fine. To share the main account's instead, quit that window, then: mv "${p}" "${p}.local" && ln -s "${mainPath}" "${p}"`,
+                }
+                : {};
+            out.push({
+                ...r,
+                ...own,
+                item: `app-data/${item.path}`,
+                message: `${def.title} data: ${own.message ?? r.message}`,
+            });
+        }
+    }
+    return out;
+}

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

@@ -1,5 +1,5 @@
 import type { HookBus } from '../plugins/bus.ts';
-import type { Account, FamilyDef, Finding } from '../types.ts';
+import type { Account, CheckResult, FamilyDef, Finding } from '../types.ts';
 export interface AccountReport {
     ref: string;
     family: string;
@@ -35,6 +35,11 @@ export interface DoctorInput {
     force?: boolean;
     /** This sideby's version: when set, installed sideby skills of the checked Families are compared with it. */
     skillVersion?: string;
+    /**
+     * More core checks for an Account that is not the Main Account, merged after its Shared Items. They are not
+     * counted in `shared`; a result's `fix` runs with the others under `--fix` and must stay within what it checked.
+     */
+    extraChecks?: (account: Account) => Promise<CheckResult[]>;
 }
 export declare function runDoctor(input: DoctorInput): Promise<DoctorReport>;
 /** Applies every fixable Finding once, in order; one failing fix never stops the others. */

package/dist/src/core/doctor.js

@@ -43,6 +43,25 @@ async function checkAccount(input, family, account) {
                 if (r.level !== 'ok')
                     findings.push(toFinding(r, account.ref, 'core'));
         }
+        // Extra checks (for example a Desktop App's data folder) add Findings but never count toward `shared`.
+        // A failing extra check costs only its own Findings, never the whole run.
+        try {
+            for (const r of (await input.extraChecks?.(account)) ?? [])
+                if (r.level !== 'ok')
+                    findings.push(toFinding(r, account.ref, 'core'));
+        }
+        catch (e) {
+            findings.push({
+                level: 'warn',
+                account: account.ref,
+                item: 'extra',
+                code: 'extra-check.error',
+                message: `could not finish an extra check of ${account.ref}: ${e instanceof Error ? e.message : String(e)}`,
+                hint: 'run sideby doctor again; if it keeps failing, check that the folder it names is readable',
+                fixable: false,
+                source: 'core',
+            });
+        }
         if (looksLikeBackup(account.name))
             findings.push({
                 level: 'warn',

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

@@ -10,6 +10,8 @@ export interface HandoffIo {
 }
 /** How long the Host gets to exit after SIGTERM (time for its SessionEnd hooks) before sideby gives up. */
 export declare const EXIT_GRACE_MS = 10000;
+/** Accounts the decision left out and why (spec §3.21), as `; skipped claude:main (…)`, or ''. */
+export declare function skippedText(d: HandoffDecision): string;
 export declare function explain(d: HandoffDecision): string;
 /** `args` with `extra` before the first `--`, so a user's own `--` cannot turn sideby's options into prompt text. */
 export declare function beforeDashes(args: readonly string[], extra: readonly string[]): string[];

package/dist/src/core/handoff-run.js

@@ -18,14 +18,20 @@ const PLAN_REFRESH_MS = 60_000;
 const READY_POLL_MS = 1000;
 const hookCommand = (family) => (event) => `sideby handoff-hook ${family} ${event}`;
 const clock = (iso) => new Date(iso).toLocaleTimeString(undefined, { hour: '2-digit', minute: '2-digit' });
+/** Accounts the decision left out and why (spec §3.21), as `; skipped claude:main (…)`, or ''. */
+export function skippedText(d) {
+    if (d.kind === 'wait' || !d.skipped?.length)
+        return '';
+    return `; skipped ${d.skipped.map((x) => `${x.ref} (${x.reason})`).join(', ')}`;
+}
 export function explain(d) {
     if (d.kind === 'wait')
         return `the full window resets at ${clock(d.until)}, so waiting beats moving on`;
     if (d.kind === 'none')
-        return d.earliestReset
+        return `${d.earliestReset
             ? `${d.reason}; ${d.earliestReset.ref} is back first, at ${clock(d.earliestReset.at)}`
-            : d.reason;
-    return `next: ${d.ref}`;
+            : d.reason}${skippedText(d)}`;
+    return `next: ${d.ref}${skippedText(d)}`;
 }
 /** Resolves with the ready file once the hook writes one for `runId`; `stop()` ends the watch. */
 function watchReady(dir, runId) {
@@ -287,7 +293,7 @@ opts = {}) {
         await writeJsonFile(join(dir, FILES.chain), hops);
         await rm(join(dir, FILES.ready), { force: true });
         await rm(join(dir, FILES.request), { force: true });
-        io.err(`sideby: ${account.ref} saved its session and is handing over because ${WHY[ready.trigger]}; next is ${decision.ref}. Brief: ${done.path}`);
+        io.err(`sideby: ${account.ref} saved its session and is handing over because ${WHY[ready.trigger]}; next is ${decision.ref}${skippedText(decision)}. Brief: ${done.path}`);
         if (settings.countdownSeconds > 0 &&
             (await countdown(io, settings.countdownSeconds, decision.ref, account.ref))) {
             io.err(`sideby: staying in ${account.ref}`);

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

@@ -9,14 +9,22 @@ export interface SelectCandidate {
     login: LoginState | 'not-needed';
     quota: QuotaResult;
     identity?: AccountIdentity;
+    /** The other Accounts of its Same Login (spec §3.21); they share its Quota. */
+    sameLogin?: readonly string[];
     /** Whether the Account's Host is on PATH. */
     installed: boolean;
     /** Whether its Family can start as the next Account (has `handoff`, and the run would be eligible). */
     receive: boolean;
 }
+/** An Account the Handoff Order lists that was left out, and why (spec §3.21). */
+export interface SkippedAccount {
+    ref: string;
+    reason: string;
+}
 export type HandoffDecision = {
     kind: 'pick';
     ref: string;
+    skipped?: SkippedAccount[];
 } | {
     kind: 'wait';
     until: string;
@@ -27,6 +35,7 @@ export type HandoffDecision = {
         ref: string;
         at: string;
     };
+    skipped?: SkippedAccount[];
 };
 /** Organizations when both have one, else email domains when both have one, else the same. */
 export declare function sameOrganization(a?: AccountIdentity, b?: AccountIdentity): boolean;

package/dist/src/core/handoff-select.js

@@ -70,7 +70,14 @@ export function selectNext(input) {
         const ranked = planHandoff(origin.family, own, now, { includeApi: true }).accounts.map((e) => byRef.get(e.ref));
         list = [...ranked, ...input.candidates.filter((c) => c.family !== origin.family && c.kind === 'api')];
     }
-    const eligible = list.filter((c) => !used.has(c.ref) &&
+    // The same login shares the origin's Quota, so taking over there gains nothing (spec §3.21).
+    const sameLogin = new Set(origin.sameLogin ?? []);
+    const skipped = list
+        .filter((c) => sameLogin.has(c.ref))
+        .map((c) => ({ ref: c.ref, reason: `same login as ${origin.ref}, so it shares the same quota` }));
+    const withSkipped = skipped.length ? { skipped } : {};
+    const eligible = list.filter((c) => !sameLogin.has(c.ref) &&
+        !used.has(c.ref) &&
         c.installed &&
         c.receive &&
         // An API account pays per request, so it gets past no vendor's limit: sameFamily does not apply to it.
@@ -80,7 +87,7 @@ export function selectNext(input) {
     const first = states.find(({ e }) => e.state === 'ready' || e.state === 'unknown') ??
         states.find(({ e }) => e.state === 'api');
     if (first)
-        return { kind: 'pick', ref: first.c.ref };
+        return { kind: 'pick', ref: first.c.ref, ...withSkipped };
     const full = states
         .filter(({ e }) => e.state === 'full' && e.resetsAt)
         .sort((a, b) => Date.parse(a.e.resetsAt) - Date.parse(b.e.resetsAt))[0];
@@ -90,5 +97,6 @@ export function selectNext(input) {
             ? 'every account that may take over is full or signed out'
             : 'no account may take over',
         ...(full ? { earliestReset: { ref: full.c.ref, at: full.e.resetsAt } } : {}),
+        ...withSkipped,
     };
 }

package/dist/src/core/handoff-status.js

@@ -68,6 +68,18 @@ export async function handoffStatus(rt) {
         }
         if (unknown.length)
             notes.push(`order names ${unknown.join(', ')}, which sideby cannot find; they are skipped`);
+        // Same Login (spec §3.21): one note per group, so a skipped account in the order is no surprise.
+        const seen = new Set();
+        for (const a of accounts.filter((x) => x.family === f.id)) {
+            if (seen.has(a.ref))
+                continue;
+            const peers = await rt.sameLogin(a);
+            if (!peers.length)
+                continue;
+            for (const r of [a.ref, ...peers])
+                seen.add(r);
+            notes.push(`${[a.ref, ...peers].join(', ')} are signed in as the same login and share one quota; a handoff from one never goes to another`);
+        }
         families.push({
             family: f.id,
             starts,

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

@@ -7,6 +7,8 @@ export interface HandoffCandidate {
     kind: Account['kind'];
     login: LoginState | 'not-needed';
     quota: QuotaResult;
+    /** The other Accounts of its Same Login (spec §3.21). */
+    sameLogin?: readonly string[];
 }
 export interface HandoffEntry {
     ref: string;
@@ -18,9 +20,18 @@ export interface HandoffEntry {
     resetsAt?: string;
     /** When the Quota was recorded; it is only as fresh as the Account's last session. */
     observedAt?: string;
+    /** The Account the Quota was read from, when it is another Account of the same login (spec §3.21). */
+    quotaFrom?: string;
+    /**
+     * The current Account, when this one is signed in as the same login (spec §3.21): it shares that Quota, so it is
+     * never picked.
+     */
+    sameLoginAs?: string;
 }
 export interface HandoffPlan {
     family: string;
+    /** The Account this process runs in (`SIDEBY_ACCOUNT`), when it belongs to the Family. */
+    from?: 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. */
@@ -38,4 +49,5 @@ export interface HandoffPlan {
 }
 export declare function planHandoff(family: string, candidates: readonly HandoffCandidate[], now: Date, opts?: {
     includeApi?: boolean;
+    from?: string;
 }): HandoffPlan;

package/dist/src/core/handoff.js

@@ -9,6 +9,7 @@ function entry(c, now) {
         kind: c.kind,
         pressure,
         ...(c.quota.status === 'ok' ? { observedAt: c.quota.observedAt } : {}),
+        ...(c.quota.status === 'ok' && c.quota.from ? { quotaFrom: c.quota.from } : {}),
     };
     if (c.kind === 'api')
         return { ...base, state: 'api' };
@@ -29,6 +30,7 @@ function entry(c, now) {
     return { ...base, state: 'full', ...(last === undefined ? {} : { resetsAt: new Date(last).toISOString() }) };
 }
 export function planHandoff(family, candidates, now, opts = {}) {
+    const current = opts.from ? candidates.find((c) => c.ref === opts.from) : undefined;
     const byRef = new Map(candidates.map((c) => [c.ref, c]));
     const tie = (a, b) => {
         const x = byRef.get(a.ref);
@@ -36,15 +38,22 @@ export function planHandoff(family, candidates, now, opts = {}) {
         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] ||
+        .map((c) => {
+        const e = entry(c, now);
+        return current?.sameLogin?.includes(c.ref) ? { ...e, sameLoginAs: current.ref } : e;
+    })
+        .sort((a, b) => 
+    // A Same Login partner of the current Account can never be picked, so it goes with the others that cannot.
+    Number(Boolean(a.sameLoginAs)) - Number(Boolean(b.sameLoginAs)) ||
+        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 usable = (e) => !e.sameLoginAs &&
+        (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 };
+    const plan = { family, ...(current ? { from: current.ref } : {}), pick, accounts, hasQuota };
     if (pick === null) {
         const first = accounts.find((e) => e.state === 'full' && e.resetsAt);
         if (first?.resetsAt)

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

@@ -0,0 +1,24 @@
+import type { Account, AccountIdentity, QuotaResult } from '../types.ts';
+/**
+ * Families whose Identity tells one Quota apart. Codex is left out: its Identity is an email only, and one email can
+ * belong to several ChatGPT workspaces, each with its own Quota (ADR-0016).
+ */
+export declare const SAME_LOGIN_FAMILIES: ReadonlySet<string>;
+export interface LoginMember {
+    ref: string;
+    family: string;
+    kind: Account['kind'];
+    identity?: AccountIdentity;
+}
+/**
+ * Whether two Accounts are the same login: same Family (one that groups), both subscriptions, the same email, and the
+ * same organization (both have one and it is equal, or neither has one). Without an email nothing groups.
+ */
+export declare function isSameLogin(a: LoginMember, b: LoginMember): boolean;
+/** Ref → the other refs of its Same Login, in the order given; Accounts without one are left out. */
+export declare function sameLoginGroups(members: readonly LoginMember[]): Map<string, string[]>;
+/**
+ * The Quota an Account of a Same Login shows: the freshest `ok` reading of the group (its own wins a tie), marked
+ * with `from` when it is another member's. Without any `ok` reading the Account keeps its own result.
+ */
+export declare function sharedQuota(ref: string, readings: ReadonlyMap<string, QuotaResult>, peers: readonly string[]): QuotaResult;