sideby 0.9.3 → 0.11.0

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

@@ -132,9 +132,12 @@ export function hookEntryWorks(env) {
     });
 }
 /** The decision, or `none` with the reason when sideby cannot tell (an account removed mid-chain, say). */
-async function decide(rt, account, used, to) {
+async function decide(rt, account, used, to, manual = false) {
     try {
-        return await rt.handoffDecision(account, used, to !== undefined ? { to } : {});
+        return await rt.handoffDecision(account, used, {
+            ...(to !== undefined ? { to } : {}),
+            ...(manual ? { manual: true } : {}),
+        });
     }
     catch (err) {
         return { kind: 'none', reason: err.message };
@@ -230,6 +233,7 @@ opts = {}) {
                         at: new Date().toISOString(),
                         decision: d.kind,
                         ...(d.kind === 'pick' ? { pick: d.ref } : {}),
+                        ...(d.kind === 'wait' ? { until: d.until } : {}),
                         prepareAt: settings.prepareAt,
                         threshold: settings.threshold,
                         ...(elig.agentBrief === false ? { agentBrief: false } : {}),
@@ -246,27 +250,48 @@ opts = {}) {
         await writePlan();
         const refresh = setInterval(() => void writePlan(), PLAN_REFRESH_MS);
         const host = spawnHost({ ...launch, args, env });
-        const watcher = watchReady(dir, runId);
-        const outcome = await Promise.race([
-            host.exited.then((code) => ({ kind: 'exit', code })),
-            watcher.ready.then((ready) => ({ kind: 'ready', ready })),
-        ]);
+        const exited = host.exited.then((code) => ({ kind: 'exit', code }));
+        // Nothing to move on to (or better to wait): leave the session alone, keep listening (the user may still ask to
+        // move on while it waits, ADR-0018), and say why once it ends.
+        let kept;
+        let outcome;
+        for (;;) {
+            const watcher = watchReady(dir, runId);
+            const got = await Promise.race([
+                exited,
+                watcher.ready.then((ready) => ({ kind: 'ready', ready })),
+            ]);
+            watcher.stop();
+            if (got.kind === 'exit') {
+                outcome = got;
+                break;
+            }
+            const d = await decide(rt, account, used, got.ready.to, got.ready.trigger === 'manual');
+            if (d.kind === 'pick') {
+                outcome = { ...got, decision: d };
+                break;
+            }
+            await rm(join(dir, FILES.ready), { force: true });
+            if (d.kind === 'wait')
+                await writeJsonFile(join(dir, FILES.waiting), {
+                    runId,
+                    until: d.until,
+                    at: new Date().toISOString(),
+                });
+            kept = d;
+        }
         clearInterval(refresh);
-        watcher.stop();
         stopped = true;
         await pending;
+        await rm(join(dir, FILES.waiting), { force: true });
         if (outcome.kind === 'exit') {
-            await noteUnhandedHighQuota(rt, account, used, settings.threshold, io);
+            if (kept)
+                io.err(`sideby: ${account.ref} did not hand over: ${explain(kept)}`);
+            else
+                await noteUnhandedHighQuota(rt, account, used, settings.threshold, io);
             return outcome.code;
         }
-        // Nothing to move on to (or better to wait): leave the session alone and say why once it ends.
-        const decision = await decide(rt, account, used, outcome.ready.to);
-        if (decision.kind !== 'pick') {
-            await rm(join(dir, FILES.ready), { force: true });
-            const code = await host.exited;
-            io.err(`sideby: ${account.ref} did not hand over: ${explain(decision)}`);
-            return code;
-        }
+        const decision = outcome.decision;
         // The session is ready: end the Host, give it time to save, never kill it.
         host.child.kill('SIGTERM');
         const ended = await Promise.race([
@@ -356,5 +381,5 @@ export async function readyDecision(rt, env, to) {
     }
     const account = await rt.resolve(ref);
     const chain = await readJsonFile(join(dir, FILES.chain));
-    return decide(rt, account, chain?.hops.map((h) => h.ref) ?? [account.ref], to);
+    return decide(rt, account, chain?.hops.map((h) => h.ref) ?? [account.ref], to, true);
 }

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

@@ -15,6 +15,8 @@ export interface SelectCandidate {
     installed: boolean;
     /** Whether its Family can start as the next Account (has `handoff`, and the run would be eligible). */
     receive: boolean;
+    /** A session stopped at the limit continues by itself at the reset (`FamilyHandoff.resumesAtReset`); set for the origin. */
+    resumesAtReset?: boolean;
 }
 /** An Account the Handoff Order lists that was left out, and why (spec §3.21). */
 export interface SkippedAccount {
@@ -55,4 +57,6 @@ export declare function selectNext(input: {
      * an Account whose Quota came back); every other rule still applies.
      */
     to?: string;
+    /** The user asked to hand over (`sideby handoff ready`): never wait for a reset (ADR-0018). */
+    manual?: boolean;
 }): HandoffDecision;

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

@@ -15,7 +15,8 @@ export function sameOrganization(a, b) {
  * reaches the threshold (spec §3.17 "选号" 1: plan.json and the Panel, decided before the moment comes).
  */
 function waitUntil(origin, s, now, ahead) {
-    if (origin.quota.status !== 'ok' || s.waitIfResetWithinMinutes <= 0)
+    // Waiting only makes sense when the session goes on by itself at the reset (ADR-0018).
+    if (origin.quota.status !== 'ok' || s.waitIfResetWithinMinutes <= 0 || origin.resumesAtReset !== true)
         return undefined;
     const open = origin.quota.windows.filter((w) => !windowReset(w.resetsAt, now));
     const top = Math.max(0, ...open.map((w) => w.usedPercent));
@@ -60,7 +61,7 @@ export function selectNext(input) {
             return { kind: 'none', reason: `${input.to} is not an account sideby can find` };
         return toTarget(origin, target, s, new Set(s.crossOrganization.map(refOf)), now);
     }
-    const until = waitUntil(origin, s, now, input.ahead === true);
+    const until = input.manual ? undefined : waitUntil(origin, s, now, input.ahead === true);
     if (until)
         return { kind: 'wait', until };
     const allowed = new Set(s.crossOrganization.map(refOf));

package/dist/src/core/remote-control.d.ts

@@ -0,0 +1,45 @@
+import type { Account, ReadContext } from '../types.ts';
+export declare const RC_KEY = "remoteControlAtStartup";
+/**
+ * `on`: every session connects by itself; `default`: no key, so the organization's or Claude Code's default decides
+ * (it may connect); `off`: never by itself; `missing`: the Account has no `settings.json`; `blocked`: see `reason`.
+ */
+export type RemoteControlState = 'on' | 'default' | 'off' | 'missing' | 'blocked';
+export interface RemoteControlGroup {
+    /** The real settings file (canonical); for `missing`, where it would be. */
+    file: string;
+    /** Refs of the Accounts whose `settings.json` is `file`, in discovery order. */
+    accounts: string[];
+    state: RemoteControlState;
+    /** For `blocked` and `missing`: why, and what to do. */
+    reason?: string;
+    /** sideby turned it off here and can put the earlier value back. */
+    undo: boolean;
+}
+export interface RemoteControlUndoRecord {
+    file: string;
+    /** The value before sideby wrote `false`, or null when the key was not there. */
+    previous: boolean | null;
+    at: string;
+}
+export interface RemoteControlChange {
+    ok: boolean;
+    /** One line per group that was meant to change. */
+    results: {
+        file: string;
+        accounts: string[];
+        ok: boolean;
+        message: string;
+    }[];
+    message: string;
+}
+/** Every Claude Account's setting, grouped by the file it lives in. Writes nothing. */
+export declare function remoteControlGroups(accounts: readonly Account[], ctx: ReadContext): Promise<RemoteControlGroup[]>;
+/** The groups `off` would change: those that are on, or follow a default that may be on. */
+export declare function groupsToTurnOff(groups: readonly RemoteControlGroup[]): RemoteControlGroup[];
+/** Sets `remoteControlAtStartup` to false in every group that is on or follows the default, remembering each old value. */
+export declare function turnRemoteControlOff(accounts: readonly Account[], ctx: ReadContext): Promise<RemoteControlChange>;
+/** Groups sideby can put back: it wrote `false` there and the key still holds it. */
+export declare function groupsToUndo(groups: readonly RemoteControlGroup[]): RemoteControlGroup[];
+/** Puts back what each file had before `off`, only while the key is still `false`. */
+export declare function undoRemoteControlOff(accounts: readonly Account[], ctx: ReadContext): Promise<RemoteControlChange>;

package/dist/src/core/remote-control.js

@@ -0,0 +1,157 @@
+// Remote Control off by default (spec §3.22, ADR-0017): reads and writes one key, `remoteControlAtStartup`, of each
+// Claude Account's `settings.json`. Accounts that share a file (a link to the Main Account's) form one group and one
+// write. Nothing but that key is ever read out of the file into an output, an error or the undo record; writes go
+// through `writeIfUnchanged`, keep every other key, and never create, replace or retarget a link.
+import { mkdir, readFile, rm, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { locate, readObject, render } from './claude-settings-file.js';
+import { sha256, writeFileAtomic, writeIfUnchanged } from './fs-safe.js';
+export const RC_KEY = 'remoteControlAtStartup';
+const NO_SETTINGS = 'this account has no settings.json; run `sideby doctor --fix` so it shares the main one, then try again';
+function stateOf(v) {
+    return v === true ? 'on' : v === false ? 'off' : 'default';
+}
+function recordPath(ctx, file) {
+    return join(ctx.stateDir, 'remote-control', `${sha256(file).slice(0, 16)}.json`);
+}
+async function readRecord(ctx, file) {
+    try {
+        const r = JSON.parse(await readFile(recordPath(ctx, file), 'utf8'));
+        if (r.file === file && (r.previous === null || typeof r.previous === 'boolean'))
+            return r;
+    }
+    catch {
+        // no record
+    }
+    return null;
+}
+/** Every Claude Account's setting, grouped by the file it lives in. Writes nothing. */
+export async function remoteControlGroups(accounts, ctx) {
+    const byFile = new Map();
+    for (const account of accounts) {
+        if (account.family !== 'claude')
+            continue;
+        const where = await locate(account);
+        const have = byFile.get(where.file);
+        if (have) {
+            have.accounts.push(account.ref);
+            continue;
+        }
+        const group = {
+            file: where.file,
+            accounts: [account.ref],
+            state: 'missing',
+            undo: false,
+        };
+        byFile.set(where.file, group);
+        if (where.broken) {
+            group.state = 'blocked';
+            group.reason =
+                'settings.json is a link to a file that does not exist; run `sideby doctor` to see how to fix it';
+        }
+        else if (!where.exists) {
+            group.reason = NO_SETTINGS;
+        }
+        else {
+            const read = await readObject(where.file);
+            if ('error' in read) {
+                group.state = 'blocked';
+                group.reason = `settings.json cannot be changed safely: ${read.error}. Fix or move the file, then try again`;
+            }
+            else {
+                group.state = stateOf(read.obj[RC_KEY]);
+                group.undo = group.state === 'off' && (await readRecord(ctx, where.file)) !== null;
+            }
+        }
+    }
+    return [...byFile.values()];
+}
+/** The groups `off` would change: those that are on, or follow a default that may be on. */
+export function groupsToTurnOff(groups) {
+    return groups.filter((g) => g.state === 'on' || g.state === 'default');
+}
+async function writeKey(file, change, expect) {
+    const read = await readObject(file);
+    if ('error' in read)
+        return `settings.json cannot be changed safely: ${read.error}.`;
+    const refused = expect(read.obj);
+    if (refused)
+        return refused;
+    const mode = (await stat(file)).mode & 0o777;
+    const wrote = await writeIfUnchanged(file, sha256(read.text), render(change({ ...read.obj }), read.text), mode);
+    return wrote ? null : 'settings.json changed while sideby was writing, so nothing was changed. Try again.';
+}
+/** Sets `remoteControlAtStartup` to false in every group that is on or follows the default, remembering each old value. */
+export async function turnRemoteControlOff(accounts, ctx) {
+    const groups = await remoteControlGroups(accounts, ctx);
+    const todo = groupsToTurnOff(groups);
+    if (todo.length === 0) {
+        const stuck = groups.find((g) => g.state === 'blocked');
+        return stuck
+            ? { ok: false, results: [], message: `Nothing was changed: ${stuck.reason}` }
+            : {
+                ok: true,
+                results: [],
+                message: 'Remote Control already does not start by itself; nothing changed.',
+            };
+    }
+    const results = [];
+    for (const g of todo) {
+        let previous = null;
+        const failed = await writeKey(g.file, (obj) => {
+            previous = typeof obj[RC_KEY] === 'boolean' ? obj[RC_KEY] : null;
+            obj[RC_KEY] = false;
+            return obj;
+        }, (obj) => (obj[RC_KEY] === false ? 'It was turned off meanwhile; nothing changed.' : null));
+        if (failed) {
+            results.push({ file: g.file, accounts: g.accounts, ok: false, message: failed });
+            continue;
+        }
+        const record = { file: g.file, previous, at: new Date().toISOString() };
+        await mkdir(join(ctx.stateDir, 'remote-control'), { recursive: true });
+        await writeFileAtomic(recordPath(ctx, g.file), `${JSON.stringify(record, null, 2)}\n`, 0o600);
+        results.push({ file: g.file, accounts: g.accounts, ok: true, message: 'Turned off.' });
+    }
+    const ok = results.every((r) => r.ok);
+    return {
+        ok,
+        results,
+        message: ok
+            ? 'Done. New sessions no longer connect to claude.ai by themselves; restart sessions that are already running. You can still start it in a session with /remote-control.'
+            : 'Some files could not be changed; see each line.',
+    };
+}
+/** Groups sideby can put back: it wrote `false` there and the key still holds it. */
+export function groupsToUndo(groups) {
+    return groups.filter((g) => g.undo);
+}
+/** Puts back what each file had before `off`, only while the key is still `false`. */
+export async function undoRemoteControlOff(accounts, ctx) {
+    const todo = groupsToUndo(await remoteControlGroups(accounts, ctx));
+    if (todo.length === 0)
+        return { ok: false, results: [], message: 'There is nothing from sideby to undo.' };
+    const results = [];
+    for (const g of todo) {
+        const record = await readRecord(ctx, g.file);
+        if (!record)
+            continue;
+        const failed = await writeKey(g.file, (obj) => {
+            if (record.previous === null)
+                delete obj[RC_KEY];
+            else
+                obj[RC_KEY] = record.previous;
+            return obj;
+        }, (obj) => obj[RC_KEY] === false ? null : 'The setting was changed after sideby set it, so it was left alone.');
+        if (!failed)
+            await rm(recordPath(ctx, g.file), { force: true });
+        results.push({ file: g.file, accounts: g.accounts, ok: !failed, message: failed ?? 'Put back.' });
+    }
+    const ok = results.length > 0 && results.every((r) => r.ok);
+    return {
+        ok,
+        results,
+        message: ok
+            ? 'Undone. New sessions go back to the previous setting.'
+            : 'Some files could not be put back; see each line.',
+    };
+}

package/dist/src/core/tuning-apply.js

@@ -5,49 +5,19 @@
 // shares it; a link is never created, replaced or retargeted.
 import { mkdir, readFile, rm, stat } from 'node:fs/promises';
 import { join } from 'node:path';
+import { isObj, locate, readObject, render } from './claude-settings-file.js';
 import { UserError } from './errors.js';
-import { fileHash, lstatOrNull, realpathOrNull, sha256, writeFileAtomic, writeIfUnchanged, } from './fs-safe.js';
+import { fileHash, sha256, writeFileAtomic, writeIfUnchanged } from './fs-safe.js';
 import { MAX_COMPACT_WINDOW, MIN_COMPACT_WINDOW } from './tuning.js';
 export const TUNE_KEY = 'autoCompactWindow';
 export const MIN_WINDOW = MIN_COMPACT_WINDOW;
 export const MAX_WINDOW = MAX_COMPACT_WINDOW;
-const MAX_BYTES = 5_000_000;
-const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
 function checkValue(value) {
     if (value === null)
         return;
     if (!Number.isInteger(value) || value < MIN_WINDOW || value > MAX_WINDOW)
         throw new UserError(`${value} is not a usable size: give a whole number of tokens from ${MIN_WINDOW} to ${MAX_WINDOW}, for example 160000`, { code: 'bad-value' });
 }
-function detectIndent(text) {
-    const m = /^([ \t]+)"/m.exec(text);
-    if (!m)
-        return 2;
-    const lead = m[1];
-    return lead.startsWith('\t') ? '\t' : lead.length;
-}
-function render(obj, original) {
-    const out = JSON.stringify(obj, null, detectIndent(original));
-    return original.endsWith('\n') || original === '' ? `${out}\n` : out;
-}
-async function readObject(file) {
-    const st = await stat(file).catch(() => null);
-    if (!st?.isFile())
-        return { error: 'it is not a regular file' };
-    if (st.size > MAX_BYTES)
-        return { error: 'it is too large to be a settings file' };
-    const text = await readFile(file, 'utf8');
-    let parsed;
-    try {
-        parsed = JSON.parse(text);
-    }
-    catch {
-        return { error: 'it is not valid JSON' };
-    }
-    if (!isObj(parsed))
-        return { error: 'it is not a JSON object' };
-    return { text, obj: parsed };
-}
 /** The sizes models save for themselves under `modelSettings`: only those `autoCompactWindow` numbers are read. */
 function overridesOf(obj) {
     const ms = obj.modelSettings;
@@ -61,23 +31,6 @@ function overridesOf(obj) {
     }
     return out;
 }
-/** Where the Account's settings really live, and whether `settings.json` is a link to it. */
-async function locate(account) {
-    const path = join(account.dir, 'settings.json');
-    const lst = await lstatOrNull(path);
-    // Every path is canonical (no link anywhere in it), so two Accounts that share a file compare equal and the undo
-    // record is found from either of them, even when HOME itself sits behind a link.
-    if (!lst) {
-        const dir = (await realpathOrNull(account.dir)) ?? account.dir;
-        return { file: join(dir, 'settings.json'), link: false, exists: false };
-    }
-    const real = await realpathOrNull(path);
-    if (!lst.isSymbolicLink())
-        return { file: real ?? path, link: false, exists: true };
-    return real
-        ? { file: real, link: true, exists: true }
-        : { file: path, link: true, exists: false, broken: true };
-}
 function recordPath(ctx, file) {
     return join(ctx.stateDir, 'tune', `${sha256(file).slice(0, 16)}.json`);
 }

package/dist/src/desktop/icon.js

@@ -1,26 +1,32 @@
-// The sideby mark drawn without dependencies: the Panel header's logo (a dark rounded tile with a light disc
-// split into two halves, offset along the diagonal, the second at 55% opacity) rasterised with analytic
-// antialiasing and encoded as PNG, SVG or ICNS.
+// The sideby mark drawn without dependencies: the Panel header's logo (two faces side by side on a light rounded
+// tile, core/brand-mark.ts) rasterised with analytic antialiasing and encoded as PNG, SVG or ICNS.
 import { deflateSync } from 'node:zlib';
+import { MARK, MARK_COLORS, MARK_TILE_VIEWBOX, markSvgBody } from '../core/brand-mark.js';
 /** Text stored in every generated file, so `sideby app uninstall` deletes only what it wrote. */
 export const APP_MARKER = 'sideby-app-install';
-// Geometry in the Panel's 40-unit logo box (page.ts: .logo 40×40, radius 10; halves of radius 10.5 centred at
-// 18.5,18.5 facing left and 21.5,21.5 facing right, so they sit 3 apart and mirror through the centre).
+// The Panel's logo tile (page-styles.ts: .logo 40×40, radius 10), with the mark in MARK_TILE_VIEWBOX units on it.
 const TILE = { size: 40, radius: 10, color: [0xe5, 0xf2, 0xfb] };
-const MARK = { color: [0x3f, 0x8f, 0xc4], opacities: [1, 0.55] };
-const HALVES = [
-    { cx: 18.5, cy: 18.5, r: 10.5, side: -1 },
-    { cx: 21.5, cy: 21.5, r: 10.5, side: 1 },
-];
 // The tile sits on the macOS icon grid: 824 of 1024 units, centred.
 const GRID = { canvas: 1024, tile: 824 };
+const rgb = (hex) => [1, 3, 5].map((i) => Number.parseInt(hex.slice(i, i + 2), 16));
 function shapes(size) {
     const tilePx = (size * GRID.tile) / GRID.canvas;
     const off = (size - tilePx) / 2;
-    const u = tilePx / TILE.size;
+    const u = tilePx / MARK_TILE_VIEWBOX.size;
+    const place = ([x, y, w, h, r]) => ({
+        x: off + (x - MARK_TILE_VIEWBOX.x) * u,
+        y: off + (y - MARK_TILE_VIEWBOX.y) * u,
+        w: w * u,
+        h: h * u,
+        r: r * u,
+    });
     return {
-        tile: { x: off, y: off, w: tilePx, h: tilePx, r: TILE.radius * u },
-        halves: HALVES.map((h) => ({ cx: off + h.cx * u, cy: off + h.cy * u, r: h.r * u, side: h.side })),
+        tile: { x: off, y: off, w: tilePx, h: tilePx, r: (TILE.radius * tilePx) / TILE.size },
+        back: place(MARK.back),
+        front: place(MARK.front),
+        gap: place(MARK.gap),
+        backEyes: MARK.backEyes.map(place),
+        frontEyes: MARK.frontEyes.map(place),
     };
 }
 /** Signed distance from (px, py) to a rounded rectangle; negative inside. */
@@ -32,20 +38,18 @@ function roundedRectDistance(px, py, s) {
     const outside = Math.hypot(Math.max(qx, 0), Math.max(qy, 0));
     return outside + Math.min(Math.max(qx, qy), 0) - s.r;
 }
-/** Signed distance from (px, py) to a half disc: the disc intersected with the half-plane on its side. */
-function halfDistance(px, py, h) {
-    return Math.max(Math.hypot(px - h.cx, py - h.cy) - h.r, (px - h.cx) * -h.side);
-}
 /** RGBA pixels (straight alpha) of the icon at `size`×`size`. */
 export function renderIcon(size) {
-    const { tile, halves } = shapes(size);
+    const sh = shapes(size);
+    const d = (r) => (x, y) => roundedRectDistance(x, y, r);
+    // Inside `r` and outside the gap around the front face.
+    const cut = (r) => (x, y) => Math.max(roundedRectDistance(x, y, r), -roundedRectDistance(x, y, sh.gap));
     const layers = [
-        { dist: (x, y) => roundedRectDistance(x, y, tile), color: TILE.color, opacity: 1 },
-        ...halves.map((h, i) => ({
-            dist: (x, y) => halfDistance(x, y, h),
-            color: MARK.color,
-            opacity: MARK.opacities[i],
-        })),
+        { dist: d(sh.tile), color: TILE.color },
+        { dist: cut(sh.back), color: rgb(MARK_COLORS.back) },
+        ...sh.backEyes.map((e) => ({ dist: cut(e), color: rgb(MARK_COLORS.eye) })),
+        { dist: d(sh.front), color: rgb(MARK_COLORS.front) },
+        ...sh.frontEyes.map((e) => ({ dist: d(e), color: rgb(MARK_COLORS.eye) })),
     ];
     const px = new Uint8Array(size * size * 4);
     for (let y = 0; y < size; y++)
@@ -56,8 +60,7 @@ export function renderIcon(size) {
             let b = 0;
             let a = 0;
             for (const l of layers) {
-                const cover = Math.min(1, Math.max(0, 0.5 - l.dist(x + 0.5, y + 0.5)));
-                const la = cover * l.opacity;
+                const la = Math.min(1, Math.max(0, 0.5 - l.dist(x + 0.5, y + 0.5)));
                 if (la === 0)
                     continue;
                 r = (l.color[0] / 255) * la + r * (1 - la);
@@ -157,17 +160,14 @@ export function encodeIcns(pngs) {
 }
 /** The same mark as an SVG (1024-unit canvas), for Linux icon themes. */
 export function iconSvg() {
-    const { tile, halves } = shapes(GRID.canvas);
+    const { tile } = shapes(GRID.canvas);
     const hex = (c) => `#${c.map((v) => v.toString(16).padStart(2, '0')).join('')}`;
-    const opacityAttr = (opacity) => (opacity === 1 ? '' : ` fill-opacity="${opacity}"`);
-    const rect = (s, fill) => `  <rect x="${s.x}" y="${s.y}" width="${s.w}" height="${s.h}" rx="${s.r}" fill="${fill}"/>`;
-    // From the top of the cut to its bottom, bulging to the half's side.
-    const half = (h, fill, opacity) => `  <path d="M${h.cx} ${h.cy - h.r}A${h.r} ${h.r} 0 0 ${h.side > 0 ? 1 : 0} ${h.cx} ${h.cy + h.r}Z" fill="${fill}"${opacityAttr(opacity)}/>`;
+    const V = MARK_TILE_VIEWBOX;
     return [
         `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${GRID.canvas} ${GRID.canvas}" width="${GRID.canvas}" height="${GRID.canvas}">`,
         `  <!-- ${APP_MARKER} -->`,
-        rect(tile, hex(TILE.color)),
-        ...halves.map((h, i) => half(h, hex(MARK.color), MARK.opacities[i])),
+        `  <rect x="${tile.x}" y="${tile.y}" width="${tile.w}" height="${tile.h}" rx="${tile.r}" fill="${hex(TILE.color)}"/>`,
+        `  <svg x="${tile.x}" y="${tile.y}" width="${tile.w}" height="${tile.h}" viewBox="${V.x} ${V.y} ${V.size} ${V.size}">${markSvgBody('gap', MARK_COLORS.front)}</svg>`,
         '</svg>',
         '',
     ].join('\n');

package/dist/src/families/claude/handoff.js

@@ -2,6 +2,7 @@
 // Account's own settings hooks (verified 2026-10-09), and the Brief's directory through `--add-dir`.
 import { mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
+import { locate, readObject } from '../../core/claude-settings-file.js';
 import { writeFileAtomic } from '../../core/fs-safe.js';
 import { carryArgs, hasOption, promptAfterDashes } from '../shared/handoff-args.js';
 import { claudeBrief } from './brief.js';
@@ -113,4 +114,13 @@ export const claudeHandoff = {
         return { start: true, receive: true };
     },
     briefFromSession: claudeBrief,
+    // Only `autoContinueAtUsageLimit` is read (ADR-0018); Claude Code's default is true. Managed and project settings
+    // and `--settings` can set it too; sideby does not read them.
+    async resumesAtReset(account) {
+        const where = await locate(account);
+        if (!where.exists)
+            return true;
+        const read = await readObject(where.file);
+        return 'error' in read || read.obj.autoContinueAtUsageLimit !== false;
+    },
 };

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

@@ -25,3 +25,28 @@ export interface DesktopAppDef {
 }
 /** The Desktop App of a built-in Family id, if it has one. */
 export declare function desktopDef(familyId: string): DesktopAppDef | undefined;
+/**
+ * A desktop app that signs in apart from every Account (Grok Bot), so each of its windows is an App Profile with its
+ * own App Data, named by the user (ADR-0019).
+ */
+export interface ProfileAppDef {
+    /** The ref prefix: `<id>:<name>`, and `<id>` alone for the Main Profile. */
+    id: string;
+    title: string;
+    bundleId: string;
+    bundleNames: readonly string[];
+    installUrl: string;
+    /** `open` arguments for a non-main Profile; `app` is the bundle path, `appData` the Profile's folder. */
+    openArgs(app: string, appData: string): string[];
+    /** Inherited variables cleared before `open`, which would point the app at other data. */
+    clearVars: readonly string[];
+    /** The Main Profile's app data folder, relative to HOME. */
+    mainUserData: string;
+    /** The app's own status file in an app data folder, whose boolean `signedIn` sideby reads. */
+    statusFile: string;
+    /** The Family whose users may look for this app under an Account (grok), for a pointer in its error. */
+    relatedFamily: string;
+}
+export declare const PROFILE_APPS: readonly ProfileAppDef[];
+/** The app with App Profiles related to a Family id, if any. */
+export declare function profileAppFor(familyId: string): ProfileAppDef | undefined;

package/dist/src/families/desktop.js

@@ -1,9 +1,15 @@
-// Desktop Apps of the built-in Families (spec §3.20, ADR-0015). Internal on purpose: not part of the public
-// FamilyDef, so plugin Families cannot declare one in v1.
+// Desktop Apps of the built-in Families (spec §3.20, ADR-0015) and apps with App Profiles (ADR-0019). Internal on
+// purpose: not part of the public FamilyDef, so plugin Families cannot declare one in v1.
 import { claudeDesktop } from './claude/desktop.js';
 import { codexDesktop } from './codex/desktop.js';
+import { grokBot } from './grok/bot.js';
 const DESKTOP_APPS = new Map([claudeDesktop, codexDesktop].map((d) => [d.family, d]));
 /** The Desktop App of a built-in Family id, if it has one. */
 export function desktopDef(familyId) {
     return DESKTOP_APPS.get(familyId);
 }
+export const PROFILE_APPS = [grokBot];
+/** The app with App Profiles related to a Family id, if any. */
+export function profileAppFor(familyId) {
+    return PROFILE_APPS.find((p) => p.relatedFamily === familyId);
+}

package/dist/src/families/grok/bot.d.ts

@@ -0,0 +1,8 @@
+import type { ProfileAppDef } from '../desktop.ts';
+/**
+ * Grok Bot (spec §3.20 "Grok Bot 窗口", ADR-0019). It signs in with a Cursor account, apart from every grok Account,
+ * so its windows are App Profiles. `--user-data-dir` is the app's isolated mode: userData and its data root
+ * (`<dir>/sand-data`) move there. SAND_DATA_ROOT and SAND_USER_DATA_DIR would override it; all of this is internal to
+ * the app and may change.
+ */
+export declare const grokBot: ProfileAppDef;

package/dist/src/families/grok/bot.js

@@ -0,0 +1,18 @@
+/**
+ * Grok Bot (spec §3.20 "Grok Bot 窗口", ADR-0019). It signs in with a Cursor account, apart from every grok Account,
+ * so its windows are App Profiles. `--user-data-dir` is the app's isolated mode: userData and its data root
+ * (`<dir>/sand-data`) move there. SAND_DATA_ROOT and SAND_USER_DATA_DIR would override it; all of this is internal to
+ * the app and may change.
+ */
+export const grokBot = {
+    id: 'grok-bot',
+    title: 'Grok Bot',
+    bundleId: 'com.anysphere.sand',
+    bundleNames: ['Grok Bot.app'],
+    installUrl: 'https://x.ai/bot/',
+    openArgs: (app, appData) => ['-n', '-a', app, '--args', `--user-data-dir=${appData}`],
+    clearVars: ['SAND_DATA_ROOT', 'SAND_USER_DATA_DIR'],
+    mainUserData: 'Library/Application Support/Grok Bot',
+    statusFile: 'desktop-status.json',
+    relatedFamily: 'grok',
+};