sideby 0.10.0 → 0.12.0

package/dist/src/desktop/icon.js

@@ -1,78 +1,312 @@
-// 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 two buddies of core/brand-mark.ts on a light rounded tile,
+// rasterised in pure Node and encoded as PNG, SVG or ICNS. Curves are flattened to polylines; fills use the nonzero
+// rule with exact horizontal coverage on 16 sub-rows per pixel, outlines are round-capped, round-joined thick
+// polylines (distance to a segment), ellipses use an analytic distance. Each shape is computed only inside its own
+// bounding box and composited back to front, fill before outline, as an SVG renderer would.
 import { deflateSync } from 'node:zlib';
+import { BUDDY, highlights, MARK, MARK_COLORS, MARK_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); MARK_VIEWBOX maps onto the whole tile square.
 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 };
-function shapes(size) {
-    const tilePx = (size * GRID.tile) / GRID.canvas;
-    const off = (size - tilePx) / 2;
-    const u = tilePx / TILE.size;
+// Sub-rows per pixel row for fills.
+const SUB_ROWS = 16;
+const rgb = (hex) => [1, 3, 5].map((i) => Number.parseInt(hex.slice(i, i + 2), 16));
+function tileRect(size) {
+    const w = (size * GRID.tile) / GRID.canvas;
+    const off = (size - w) / 2;
+    return { x: off, y: off, w, h: w, r: (TILE.radius * w) / TILE.size };
+}
+/** Pixels per mark unit and the map from a buddy's 64-unit grid to pixels. */
+function placement(size, b) {
+    const tile = tileRect(size);
+    const u = tile.w / MARK_VIEWBOX.size;
+    const k = b.scale * 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 })),
+        k,
+        map: (gx, gy) => [
+            tile.x + (b.x + b.scale * gx - MARK_VIEWBOX.x) * u,
+            tile.y + (b.y + b.scale * gy - MARK_VIEWBOX.y) * u,
+        ],
+    };
+}
+/** Parses absolute M, L, H, Q, C, Z path data and flattens it to pixel polylines. */
+function flatten(d, map) {
+    const tokens = d.match(/[MLHQCZ]|-?\d*\.?\d+(?:e-?\d+)?/gi) ?? [];
+    const polys = [];
+    let cur = null;
+    let gx = 0;
+    let gy = 0;
+    let start = [0, 0];
+    let i = 0;
+    const num = () => Number(tokens[i++]);
+    const isNum = () => i < tokens.length && !/^[A-Za-z]$/.test(tokens[i]);
+    const lineTo = (x, y) => {
+        gx = x;
+        gy = y;
+        cur.pts.push(map(x, y));
+    };
+    const curve = (ctrl, end) => {
+        const all = [map(gx, gy), ...ctrl.map(([x, y]) => map(x, y)), map(end[0], end[1])];
+        let len = 0;
+        for (let j = 1; j < all.length; j++)
+            len += Math.hypot(all[j][0] - all[j - 1][0], all[j][1] - all[j - 1][1]);
+        const n = Math.max(4, Math.ceil(len / 2));
+        for (let s = 1; s <= n; s++) {
+            const t = s / n;
+            // De Casteljau on the pixel control points.
+            let p = all.map((q) => [q[0], q[1]]);
+            while (p.length > 1)
+                p = p.slice(1).map((q, j) => [p[j][0] + (q[0] - p[j][0]) * t, p[j][1] + (q[1] - p[j][1]) * t]);
+            cur.pts.push([p[0][0], p[0][1]]);
+        }
+        gx = end[0];
+        gy = end[1];
     };
+    let cmd = '';
+    while (i < tokens.length) {
+        if (!isNum())
+            cmd = tokens[i++].toUpperCase();
+        switch (cmd) {
+            case 'M':
+                gx = num();
+                gy = num();
+                start = [gx, gy];
+                cur = { pts: [map(gx, gy)], closed: false };
+                polys.push(cur);
+                cmd = 'L'; // further pairs after M are lines
+                break;
+            case 'L':
+                lineTo(num(), num());
+                break;
+            case 'H':
+                lineTo(num(), gy);
+                break;
+            case 'Q': {
+                const c = [num(), num()];
+                curve([c], [num(), num()]);
+                break;
+            }
+            case 'C': {
+                const c1 = [num(), num()];
+                const c2 = [num(), num()];
+                curve([c1, c2], [num(), num()]);
+                break;
+            }
+            case 'Z':
+                cur.closed = true;
+                gx = start[0];
+                gy = start[1];
+                break;
+            default:
+                throw new Error(`icon: unsupported path command ${cmd}`);
+        }
+    }
+    return polys;
+}
+function box(size, x0, y0, x1, y1) {
+    const bx0 = Math.max(0, Math.floor(x0));
+    const by0 = Math.max(0, Math.floor(y0));
+    const bx1 = Math.min(size, Math.ceil(x1));
+    const by1 = Math.min(size, Math.ceil(y1));
+    if (bx1 <= bx0 || by1 <= by0)
+        return null;
+    const w = bx1 - bx0;
+    const h = by1 - by0;
+    return { x0: bx0, y0: by0, w, h, a: new Float32Array(w * h) };
+}
+/** Nonzero fill of the polylines (each closed implicitly), exact in x and sampled on SUB_ROWS rows per pixel. */
+function fillMask(size, polys) {
+    const edges = [];
+    let x0 = Infinity;
+    let y0 = Infinity;
+    let x1 = -Infinity;
+    let y1 = -Infinity;
+    for (const { pts } of polys)
+        for (let j = 0; j < pts.length; j++) {
+            const p = pts[j];
+            const q = pts[(j + 1) % pts.length];
+            if (p[1] !== q[1])
+                edges.push([p[0], p[1], q[0], q[1]]);
+            x0 = Math.min(x0, p[0]);
+            y0 = Math.min(y0, p[1]);
+            x1 = Math.max(x1, p[0]);
+            y1 = Math.max(y1, p[1]);
+        }
+    const m = box(size, x0, y0, x1, y1);
+    if (!m)
+        return null;
+    const hits = [];
+    for (let row = 0; row < m.h; row++)
+        for (let s = 0; s < SUB_ROWS; s++) {
+            const sy = m.y0 + row + (s + 0.5) / SUB_ROWS;
+            hits.length = 0;
+            for (const [ax, ay, bx, by] of edges) {
+                if (sy < Math.min(ay, by) || sy >= Math.max(ay, by))
+                    continue;
+                hits.push([ax + ((sy - ay) * (bx - ax)) / (by - ay), by > ay ? 1 : -1]);
+            }
+            if (hits.length < 2)
+                continue;
+            hits.sort((p, q) => p[0] - q[0]);
+            let wind = 0;
+            for (let h = 0; h < hits.length - 1; h++) {
+                wind += hits[h][1];
+                if (wind === 0)
+                    continue;
+                const xa = Math.max(hits[h][0], m.x0);
+                const xb = Math.min(hits[h + 1][0], m.x0 + m.w);
+                for (let px = Math.floor(xa); px < xb; px++) {
+                    const cover = Math.min(xb, px + 1) - Math.max(xa, px);
+                    if (cover > 0)
+                        m.a[row * m.w + px - m.x0] += cover / SUB_ROWS;
+                }
+            }
+        }
+    return m;
+}
+/** Round-capped, round-joined line of width `w` along the polylines: distance to the nearest segment ≤ w/2. */
+function strokeMask(size, polys, w) {
+    const r = w / 2;
+    const segs = [];
+    let x0 = Infinity;
+    let y0 = Infinity;
+    let x1 = -Infinity;
+    let y1 = -Infinity;
+    for (const { pts, closed } of polys) {
+        const n = closed ? pts.length : pts.length - 1;
+        for (let j = 0; j < Math.max(n, 1); j++) {
+            const p = pts[j];
+            const q = pts[(j + 1) % pts.length] ?? p;
+            segs.push([p[0], p[1], q[0], q[1]]);
+            x0 = Math.min(x0, p[0], q[0]);
+            y0 = Math.min(y0, p[1], q[1]);
+            x1 = Math.max(x1, p[0], q[0]);
+            y1 = Math.max(y1, p[1], q[1]);
+        }
+    }
+    const m = box(size, x0 - r - 1, y0 - r - 1, x1 + r + 1, y1 + r + 1);
+    if (!m)
+        return null;
+    const dist = new Float32Array(m.w * m.h).fill(Infinity);
+    for (const [ax, ay, bx, by] of segs) {
+        const dx = bx - ax;
+        const dy = by - ay;
+        const len2 = dx * dx + dy * dy;
+        const sx0 = Math.max(m.x0, Math.floor(Math.min(ax, bx) - r - 1));
+        const sx1 = Math.min(m.x0 + m.w, Math.ceil(Math.max(ax, bx) + r + 1));
+        const sy0 = Math.max(m.y0, Math.floor(Math.min(ay, by) - r - 1));
+        const sy1 = Math.min(m.y0 + m.h, Math.ceil(Math.max(ay, by) + r + 1));
+        for (let py = sy0; py < sy1; py++)
+            for (let px = sx0; px < sx1; px++) {
+                const cx = px + 0.5 - ax;
+                const cy = py + 0.5 - ay;
+                const t = len2 === 0 ? 0 : Math.min(1, Math.max(0, (cx * dx + cy * dy) / len2));
+                const d = Math.hypot(cx - t * dx, cy - t * dy);
+                const i = (py - m.y0) * m.w + px - m.x0;
+                if (d < dist[i])
+                    dist[i] = d;
+            }
+    }
+    for (let i = 0; i < dist.length; i++)
+        m.a[i] = Math.min(1, Math.max(0, r + 0.5 - dist[i]));
+    return m;
+}
+/** Filled ellipse with an approximate signed distance (exact on the axes, good near the edge). */
+function ellipseMask(size, cx, cy, rx, ry) {
+    const m = box(size, cx - rx - 1, cy - ry - 1, cx + rx + 1, cy + ry + 1);
+    if (!m)
+        return null;
+    for (let py = 0; py < m.h; py++)
+        for (let px = 0; px < m.w; px++) {
+            const x = m.x0 + px + 0.5 - cx;
+            const y = m.y0 + py + 0.5 - cy;
+            const k0 = Math.hypot(x / rx, y / ry);
+            const k1 = Math.hypot(x / (rx * rx), y / (ry * ry));
+            const d = k1 === 0 ? -Math.min(rx, ry) : (k0 * (k0 - 1)) / k1;
+            m.a[py * m.w + px] = Math.min(1, Math.max(0, 0.5 - d));
+        }
+    return m;
 }
 /** Signed distance from (px, py) to a rounded rectangle; negative inside. */
-function roundedRectDistance(px, py, s) {
+function roundedRectMask(size, s) {
+    const m = box(size, s.x - 1, s.y - 1, s.x + s.w + 1, s.y + s.h + 1);
+    if (!m)
+        return null;
     const hx = s.w / 2;
     const hy = s.h / 2;
-    const qx = Math.abs(px - (s.x + hx)) - (hx - s.r);
-    const qy = Math.abs(py - (s.y + hy)) - (hy - s.r);
-    const outside = Math.hypot(Math.max(qx, 0), Math.max(qy, 0));
-    return outside + Math.min(Math.max(qx, qy), 0) - s.r;
+    for (let py = 0; py < m.h; py++)
+        for (let px = 0; px < m.w; px++) {
+            const qx = Math.abs(m.x0 + px + 0.5 - (s.x + hx)) - (hx - s.r);
+            const qy = Math.abs(m.y0 + py + 0.5 - (s.y + hy)) - (hy - s.r);
+            const d = Math.hypot(Math.max(qx, 0), Math.max(qy, 0)) + Math.min(Math.max(qx, qy), 0) - s.r;
+            m.a[py * m.w + px] = Math.min(1, Math.max(0, 0.5 - d));
+        }
+    return m;
 }
-/** 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);
+/** The shapes of one placed buddy, back to front, each with its colour. */
+function buddyLayers(size, b) {
+    const { k, map } = placement(size, b);
+    const ink = rgb(MARK_COLORS.ink);
+    const fills = {
+        body: b.colors.body,
+        shade: b.colors.shade,
+    };
+    const layers = [];
+    for (const p of BUDDY.paths) {
+        const polys = flatten(p.d, map);
+        if (p.fill !== 'none')
+            layers.push({ mask: fillMask(size, polys), color: rgb(fills[p.fill]) });
+        const stroke = p.stroke === 'chevron' ? rgb(b.colors.chevron) : ink;
+        layers.push({ mask: strokeMask(size, polys, (p.width ?? MARK.placedLine) * k), color: stroke });
+    }
+    const dots = [...BUDDY.eyes, ...highlights(b.look)];
+    for (const e of dots) {
+        const [cx, cy] = map(e.cx, e.cy);
+        layers.push({
+            mask: ellipseMask(size, cx, cy, e.rx * k, e.ry * k),
+            color: rgb(e.fill === 'ink' ? MARK_COLORS.ink : MARK_COLORS.light),
+        });
+    }
+    return layers;
 }
 /** RGBA pixels (straight alpha) of the icon at `size`×`size`. */
 export function renderIcon(size) {
-    const { tile, halves } = shapes(size);
     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],
-        })),
+        { mask: roundedRectMask(size, tileRect(size)), color: TILE.color },
+        ...buddyLayers(size, MARK.back),
+        ...buddyLayers(size, { ...MARK.front, colors: { ...MARK.front.colors, body: MARK_COLORS.blue.body } }),
     ];
-    const px = new Uint8Array(size * size * 4);
-    for (let y = 0; y < size; y++)
-        for (let x = 0; x < size; x++) {
-            // Premultiplied "over" compositing; coverage from the distance at the pixel centre.
-            let r = 0;
-            let g = 0;
-            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;
-                if (la === 0)
+    // Premultiplied "over" compositing, layer by layer inside each mask's box.
+    const acc = new Float32Array(size * size * 4);
+    for (const { mask: m, color } of layers) {
+        if (!m)
+            continue;
+        const [cr, cg, cb] = color.map((c) => c / 255);
+        for (let y = 0; y < m.h; y++)
+            for (let x = 0; x < m.w; x++) {
+                const la = Math.min(1, m.a[y * m.w + x]);
+                if (la <= 0)
                     continue;
-                r = (l.color[0] / 255) * la + r * (1 - la);
-                g = (l.color[1] / 255) * la + g * (1 - la);
-                b = (l.color[2] / 255) * la + b * (1 - la);
-                a = la + a * (1 - la);
+                const i = ((m.y0 + y) * size + m.x0 + x) * 4;
+                acc[i] = cr * la + acc[i] * (1 - la);
+                acc[i + 1] = cg * la + acc[i + 1] * (1 - la);
+                acc[i + 2] = cb * la + acc[i + 2] * (1 - la);
+                acc[i + 3] = la + acc[i + 3] * (1 - la);
             }
-            const i = (y * size + x) * 4;
-            if (a > 0) {
-                px[i] = Math.round((r / a) * 255);
-                px[i + 1] = Math.round((g / a) * 255);
-                px[i + 2] = Math.round((b / a) * 255);
-                px[i + 3] = Math.round(a * 255);
-            }
-        }
+    }
+    const px = new Uint8Array(size * size * 4);
+    for (let i = 0; i < px.length; i += 4) {
+        const a = acc[i + 3];
+        if (a <= 0)
+            continue;
+        px[i] = Math.round((acc[i] / a) * 255);
+        px[i + 1] = Math.round((acc[i + 1] / a) * 255);
+        px[i + 2] = Math.round((acc[i + 2] / a) * 255);
+        px[i + 3] = Math.round(a * 255);
+    }
     return px;
 }
 const CRC_TABLE = (() => {
@@ -157,17 +391,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 = tileRect(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_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(MARK_COLORS.blue.body)}</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);

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

@@ -12,4 +12,8 @@ declare const WHY: {
 };
 /** The next session's first prompt: the Brief's path only, never its text (it would show in a process list). */
 export declare function firstPrompt(fromRef: string, brief: string, trigger: keyof typeof WHY): string;
+/** For the user, not the model (ADR-0018): this session will wait for the reset, and how to move on now instead. */
+export declare function waitNotice(ref: string, until: string, pressure?: number): string;
+/** A desktop notification through the Host (OSC 9 and OSC 777), the only output `StopFailure` keeps. */
+export declare function notifySequence(text: string): string;
 export {};

package/dist/src/handoff/messages.js

@@ -34,3 +34,15 @@ const WHY = {
 export function firstPrompt(fromRef, brief, trigger) {
     return `This task was handed over from ${fromRef} by sideby because ${WHY[trigger]}. Read ${brief} first, then continue the task it describes. If the user asks to move the task to another account (back to ${fromRef}, say), run \`sideby handoff ready --to <account>\` and end your turn.`;
 }
+const clock = (iso) => new Date(iso).toLocaleTimeString(undefined, { hour: '2-digit', minute: '2-digit' });
+/** For the user, not the model (ADR-0018): this session will wait for the reset, and how to move on now instead. */
+export function waitNotice(ref, until, pressure) {
+    const now = pressure === undefined ? 'hit its limit' : `is at ${Math.round(pressure)}%`;
+    const then = pressure === undefined ? 'this session waits' : 'when it runs out this session waits';
+    return `sideby: ${ref} ${now}; its quota is back at ${clock(until)}, so ${then} and goes on by itself instead of moving to another account. To move on now, type: ! sideby handoff ready`;
+}
+/** A desktop notification through the Host (OSC 9 and OSC 777), the only output `StopFailure` keeps. */
+export function notifySequence(text) {
+    const safe = [...text].map((ch) => (ch < ' ' || ch === '\u007f' ? ' ' : ch)).join('');
+    return `\u001b]9;${safe}\u0007\u001b]777;notify;sideby;${safe}\u0007`;
+}

package/dist/src/panel/background.d.ts

@@ -16,6 +16,8 @@ export declare const logFilePath: (p: Paths) => string;
 export declare function readPidFile(p: Paths): Promise<PanelPidFile | undefined>;
 /** When `pid` started, as `ps` prints it; with the pid it names one process, which a reused pid does not match. */
 export declare const processStartTime: (pid: number) => Promise<string | undefined>;
+/** The port of this state directory's background Panel when it runs and answers as itself, else null. */
+export declare function backgroundPanelPort(p: Paths): Promise<number | null>;
 /** URL of a running background Panel, or of any sideby Panel on `port`; removes a stale pid file. */
 export declare function findRunningPanel(p: Paths, port: number): Promise<string | undefined>;
 export interface StartBackgroundOptions {

package/dist/src/panel/background.js

@@ -68,6 +68,13 @@ async function checkPanel(rec) {
         return stale(`the panel on port ${rec.port} is not the one it names`);
     return { status: 'ours', ...(id.build ? { build: id.build } : {}) };
 }
+/** The port of this state directory's background Panel when it runs and answers as itself, else null. */
+export async function backgroundPanelPort(p) {
+    const rec = await readPidFile(p);
+    if (!rec)
+        return null;
+    return (await checkPanel(rec)).status === 'ours' ? rec.port : null;
+}
 /** URL of a running background Panel, or of any sideby Panel on `port`; removes a stale pid file. */
 export async function findRunningPanel(p, port) {
     const rec = await readPidFile(p);