sideby 0.10.0 → 0.11.0

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

@@ -2,6 +2,7 @@ import { type DesktopAppDef } from '../families/desktop.ts';
 import type { LoadedPlugin } from '../plugins/loader.ts';
 import type { Runtime } from '../runtime.ts';
 import type { Account, CheckResult, Env } from '../types.ts';
+import { UserError } from './errors.ts';
 export interface ExecResult {
     code: number;
     stdout: string;
@@ -20,6 +21,7 @@ export interface DesktopDeps {
  * `createRuntime` calls it, from its `desktop` option, which is the one way to replace the machine (tests).
  */
 export declare function bindDesktopDeps(rt: Runtime, deps: Partial<DesktopDeps>): void;
+export declare function depsFor(rt: Runtime): DesktopDeps;
 /** The Desktop App of a Family, only when a built-in Plugin provides that Family (a plugin may not claim one). */
 export declare function desktopAppOf(plugins: readonly LoadedPlugin[], familyId: string): DesktopAppDef | undefined;
 /** Where a non-main Account's App Data lives: `~/Library/Application Support/sideby/<family>/<name>`. */
@@ -33,15 +35,28 @@ export interface FoundApp {
  * 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 declare function findApp(def: DesktopAppDef, deps: DesktopDeps, opts?: {
+export declare function findApp(def: Pick<DesktopAppDef, 'bundleId' | 'bundleNames'>, deps: DesktopDeps, opts?: {
     spotlight?: boolean;
 }): Promise<FoundApp | null>;
 export interface Proc {
     pid: number;
     command: string;
 }
+/** Every process with its command line, or null when `ps` failed (then nothing is known to run). */
+export declare function processes(deps: DesktopDeps): Promise<Proc[] | null>;
+/** The arguments after the app's own executable, when `p` is the app's main process (not a helper). */
+export declare function mainArgs(app: FoundApp, p: Proc): string | null;
 /** The running instance of this Account: the one with its App Data, or for the Main Account the one without any. */
 export declare function instanceOf(app: FoundApp, appData: string | null, procs: readonly Proc[]): Proc | undefined;
+/**
+ * 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.
+ */
+export declare function activate(deps: DesktopDeps, pid: number): Promise<boolean>;
+/** The caller's environment without `clear`, `SIDEBY_*` and the variables of the agent session it may run in. */
+export declare function cleanEnv(base: Env, clear: readonly string[]): Env;
 export interface DesktopOpenResult {
     ref: string;
     family: string;
@@ -61,6 +76,8 @@ export interface DesktopOpenResult {
     /** What the user should know: sign in first, close other windows while signing in. */
     notices: string[];
 }
+export declare function notMac(platform: string): UserError;
+export declare function notInstalled(def: Pick<DesktopAppDef, 'title' | 'installUrl'>, deps: DesktopDeps): UserError;
 /**
  * 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.

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

@@ -5,7 +5,7 @@
 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 { desktopDef, profileAppFor } from '../families/desktop.js';
 import { UserError } from './errors.js';
 import { lstatOrNull, statOrNull } from './fs-safe.js';
 import { checkItem } from './share-modes.js';
@@ -28,7 +28,7 @@ const overrides = new WeakMap();
 export function bindDesktopDeps(rt, deps) {
     overrides.set(rt, deps);
 }
-function depsFor(rt) {
+export function depsFor(rt) {
     const o = overrides.get(rt) ?? {};
     return {
         platform: o.platform ?? process.platform,
@@ -102,7 +102,7 @@ export async function findApp(def, deps, opts = {}) {
     return null;
 }
 /** Every process with its command line, or null when `ps` failed (then nothing is known to run). */
-async function processes(deps) {
+export async function processes(deps) {
     const r = await deps.exec(PS, ['-axo', 'pid=,command=']);
     if (r.code !== 0)
         return null;
@@ -115,7 +115,7 @@ async function processes(deps) {
     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) {
+export function mainArgs(app, p) {
     const exe = `/${basename(app.path)}/Contents/MacOS/${app.executable}`;
     const at = p.command.indexOf(exe);
     if (at === -1)
@@ -145,7 +145,7 @@ export function instanceOf(app, appData, procs) {
  * 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) {
+export async function activate(deps, pid) {
     const p = Math.trunc(pid);
     const script = [
         "ObjC.import('AppKit');",
@@ -162,11 +162,12 @@ async function activate(deps, pid) {
 }
 /** The environment `open` runs with: the caller's, without anything that would pick another Account (spec §3.5). */
 function openEnv(base, family, def) {
+    return cleanEnv(base, [...family.hijackVars, family.selectVar, ...def.clearVars]);
+}
+/** The caller's environment without `clear`, `SIDEBY_*` and the variables of the agent session it may run in. */
+export function cleanEnv(base, clear) {
     const env = { ...base };
-    for (const v of family.hijackVars)
-        delete env[v];
-    delete env[family.selectVar];
-    for (const v of def.clearVars)
+    for (const v of clear)
         delete env[v];
     for (const k of Object.keys(env))
         if (k.startsWith('SIDEBY_') || isSessionVar(k))
@@ -191,10 +192,19 @@ const SESSION_VARS = new Set([
 function isSessionVar(k) {
     return SESSION_VARS.has(k) || SESSION_PREFIXES.some((p) => k.startsWith(p));
 }
-function notMac(platform) {
+/** `a`, `a and b`, `a, b and c`. */
+function joinNames(ids) {
+    return ids.length < 2 ? ids.join('') : `${ids.slice(0, -1).join(', ')} and ${ids.at(-1)}`;
+}
+/** For a Family whose people use a separate app with App Profiles (grok: Grok Bot), how to open that instead. */
+function profileHint(familyId) {
+    const p = profileAppFor(familyId);
+    return p ? `; for ${p.title}, which signs in on its own, use \`sideby desktop ${p.id}:<name>\`` : '';
+}
+export 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) {
+export 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' });
 }
 /**
@@ -208,7 +218,7 @@ export async function openDesktopApp(rt, ref) {
     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' });
+        throw new UserError(`${account.ref}: ${family?.title ?? account.family} has no desktop app sideby can open${have.length ? ` (only ${joinNames(have)} accounts do)` : ''}; use \`sideby run ${account.ref}\`${profileHint(account.family)}`, { 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' });

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

@@ -14,6 +14,8 @@ export interface PlanFile {
     at: string;
     decision: 'pick' | 'wait' | 'none';
     pick?: string;
+    /** For `wait`: when the full window resets and the session goes on by itself. */
+    until?: string;
     prepareAt: number;
     threshold: number;
     /** False when the session cannot write its Brief: no preparing step, and the threshold only ends the turn. */
@@ -26,6 +28,8 @@ export interface RunState {
     prepareSentAt?: string;
     thresholdSentAt?: string;
     stopBlocked?: boolean;
+    /** The user was told this run waits for a reset instead of moving on (ADR-0018). */
+    waitNoticeSentAt?: string;
     sessionId?: string;
     transcriptPath?: string;
 }
@@ -42,6 +46,12 @@ export interface ReadyFile {
     sessionId?: string;
     transcriptPath?: string;
 }
+/** The parent kept a session that hit its limit, to wait for the reset at `until` (ADR-0018). */
+export interface WaitingFile {
+    runId: string;
+    until: string;
+    at: string;
+}
 export interface ChainHop {
     ref: string;
     startedAt: string;
@@ -57,6 +67,7 @@ export declare const FILES: {
     readonly plan: 'plan.json';
     readonly ready: 'ready.json';
     readonly request: 'request.json';
+    readonly waiting: 'waiting.json';
     readonly chain: 'chain.json';
     readonly run: (runId: string) => string;
 };
@@ -73,7 +84,10 @@ export declare function writeJsonFile(path: string, value: unknown): Promise<voi
 /**
  * `sideby handoff ready` (spec §3.17): asks the parent to hand over after this turn. Works only inside a run sideby
  * started with Auto Handoff; `briefFile`, when given, is copied into the chain directory (mode 600); `to` is the
- * Account ref to hand over to.
+ * Account ref to hand over to. While the session waits for a reset (`waiting.json`, typed as `! sideby handoff ready`),
+ * no turn will end to pick up a request, so it writes `ready.json` at once (`now`).
  * Returns the request, or null outside such a run.
  */
-export declare function requestHandoff(env: Readonly<Record<string, string | undefined>>, briefFile?: string, to?: string): Promise<ReadyFile | null>;
+export declare function requestHandoff(env: Readonly<Record<string, string | undefined>>, briefFile?: string, to?: string, now?: Date): Promise<(ReadyFile & {
+    now: boolean;
+}) | null>;

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

@@ -1,7 +1,8 @@
 // The files one Handoff chain keeps under `<state>/handoffs/<chain>/` (spec §3.17). The handoff hook runs on every
 // tool call, so this module imports only Node built-ins and leaf modules (never the Runtime or a Family index).
-// The parent `sideby run` writes `plan.json` and `chain.json`; the hook writes `run-<id>.json` and `ready.json`;
-// `sideby handoff ready` writes `request.json`. Every file is mode 600 in a mode 700 directory.
+// The parent `sideby run` writes `plan.json`, `chain.json` and, while a session waits for a reset, `waiting.json`; the
+// hook writes `run-<id>.json` and `ready.json`; `sideby handoff ready` writes `request.json` (`ready.json` while the
+// session waits). Every file is mode 600 in a mode 700 directory.
 import { randomBytes } from 'node:crypto';
 import { chmod, mkdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
@@ -16,6 +17,7 @@ export const FILES = {
     plan: 'plan.json',
     ready: 'ready.json',
     request: 'request.json',
+    waiting: 'waiting.json',
     chain: 'chain.json',
     run: (runId) => `run-${runId}.json`,
 };
@@ -51,10 +53,11 @@ export async function writeJsonFile(path, value) {
 /**
  * `sideby handoff ready` (spec §3.17): asks the parent to hand over after this turn. Works only inside a run sideby
  * started with Auto Handoff; `briefFile`, when given, is copied into the chain directory (mode 600); `to` is the
- * Account ref to hand over to.
+ * Account ref to hand over to. While the session waits for a reset (`waiting.json`, typed as `! sideby handoff ready`),
+ * no turn will end to pick up a request, so it writes `ready.json` at once (`now`).
  * Returns the request, or null outside such a run.
  */
-export async function requestHandoff(env, briefFile, to) {
+export async function requestHandoff(env, briefFile, to, now = new Date()) {
     const runId = env[HANDOFF_ENV.run];
     const dir = env[HANDOFF_ENV.dir];
     if (!runId || !dir)
@@ -66,11 +69,21 @@ export async function requestHandoff(env, briefFile, to) {
     }
     const request = {
         runId,
-        at: new Date().toISOString(),
+        at: now.toISOString(),
         trigger: 'manual',
         ...(brief ? { brief, briefSource: 'user' } : {}),
         ...(to ? { to } : {}),
     };
+    const waiting = await readJsonFile(join(dir, FILES.waiting));
+    if (waiting && waiting.runId === runId && Date.parse(waiting.until) > now.getTime()) {
+        const state = (await readJsonFile(join(dir, FILES.run(runId)))) ?? {};
+        await writeJsonFile(join(dir, FILES.ready), {
+            ...request,
+            ...(state.sessionId ? { sessionId: state.sessionId } : {}),
+            ...(state.transcriptPath ? { transcriptPath: state.transcriptPath } : {}),
+        });
+        return { ...request, now: true };
+    }
     await writeJsonFile(join(dir, FILES.request), request);
-    return request;
+    return { ...request, now: false };
 }

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/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',
+};

package/dist/src/handoff/hook.js

@@ -7,7 +7,7 @@ import { FILES, HANDOFF_ENV, readJsonFile, writeJsonFile, } from '../core/handof
 import { claudeHookReader } from '../families/claude/handoff-hook.js';
 import { codexHookReader } from '../families/codex/handoff-hook.js';
 import { grokHookReader } from '../families/grok/handoff-hook.js';
-import { endTurnMessage, prepareMessage, sessionStartMessage, stopMessage, thresholdMessage, } from './messages.js';
+import { endTurnMessage, notifySequence, prepareMessage, sessionStartMessage, stopMessage, thresholdMessage, waitNotice, } from './messages.js';
 import { field } from './reader.js';
 export const HOOK_COMMAND = 'sideby handoff-hook';
 const READERS = {
@@ -77,10 +77,21 @@ export async function decide(opts) {
     }
     const threshold = usable?.threshold ?? 95;
     const pressure = reader.pressure ? await reader.pressure(input, env, now) : null;
+    const ref = env.SIDEBY_ACCOUNT ?? family;
+    const waiting = usable?.decision === 'wait' && usable.until ? usable.until : undefined;
+    // Once per run, shown to the user (not the model): sideby will wait for the reset, and how to move on now.
+    const waitOutput = async () => {
+        if (!waiting || pressure === null || pressure < threshold || state.waitNoticeSentAt)
+            return undefined;
+        await save({ ...state, waitNoticeSentAt: now.toISOString() });
+        return { systemMessage: waitNotice(ref, waiting, pressure) };
+    };
     if (event === 'StopFailure') {
-        if (reader.limitHit?.(input, pressure, threshold))
-            await ready({ trigger: 'limit' });
-        return {};
+        if (!reader.limitHit?.(input, pressure, threshold))
+            return {};
+        await ready({ trigger: 'limit' });
+        // The Host keeps only `terminalSequence` of a StopFailure hook's output.
+        return waiting ? { output: { terminalSequence: notifySequence(waitNotice(ref, waiting)) } } : {};
     }
     if (event === 'Stop') {
         // Grok also fires Stop when the session ends; only a finished turn counts.
@@ -95,6 +106,9 @@ export async function decide(opts) {
         }
         if (!usable)
             return {};
+        const notice = await waitOutput();
+        if (notice)
+            return { output: notice };
         if (state.thresholdSentAt && usable.agentBrief === false) {
             await ready({ trigger: 'threshold' });
             return {};
@@ -125,6 +139,9 @@ export async function decide(opts) {
     // PostToolUse
     if (!usable || pressure === null)
         return {};
+    const notice = await waitOutput();
+    if (notice)
+        return { output: notice };
     if (pressure >= usable.threshold && usable.decision === 'pick' && !state.thresholdSentAt) {
         await save({ ...state, thresholdSentAt: now.toISOString() });
         const text = usable.agentBrief === false ? endTurnMessage(pressure) : thresholdMessage(usable.brief, pressure);