sideby 0.9.3 → 0.11.0

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

@@ -0,0 +1,206 @@
+// App Profiles (spec §3.20 "Grok Bot 窗口", ADR-0019): named windows of a desktop app that signs in apart from every
+// Account, each with its own App Data under ~/Library/Application Support/sideby/<app>/<name>/. Opening and focusing
+// work as for a Family's Desktop App (core/desktop-app.ts); every program still goes through `DesktopDeps.exec`.
+import { chmod, mkdir, readdir, readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { PROFILE_APPS } from '../families/desktop.js';
+import { ACCOUNT_NAME } from './account-name.js';
+import { activate, cleanEnv, depsFor, findApp, instanceOf, mainArgs, notInstalled, notMac, processes, } from './desktop-app.js';
+import { UserError } from './errors.js';
+import { lstatOrNull } from './fs-safe.js';
+const MAIN = 'main';
+/** The app and Profile name a ref names, or undefined when it is not an App Profile ref. */
+export function parseProfileRef(ref) {
+    for (const def of PROFILE_APPS) {
+        if (ref === def.id)
+            return { def, name: MAIN };
+        if (ref.startsWith(`${def.id}:`))
+            return { def, name: ref.slice(def.id.length + 1) };
+    }
+    return undefined;
+}
+/** Where the App Profiles of an app live: `~/Library/Application Support/sideby/<app>`. */
+export function profilesRoot(home, def) {
+    return join(home, 'Library', 'Application Support', 'sideby', def.id);
+}
+function appDataOf(home, def, name) {
+    return name === MAIN ? null : join(profilesRoot(home, def), name);
+}
+/** `signedIn` from the app's own status file: a boolean next to a version, a pid and a start time, not a credential. */
+async function signedIn(file) {
+    try {
+        const v = JSON.parse(await readFile(file, 'utf8'));
+        const s = v && typeof v === 'object' ? v.signedIn : undefined;
+        return typeof s === 'boolean' ? s : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Profile names: the real folders under the app's root with a valid name, sorted. Links and files are skipped. */
+async function profileNames(root) {
+    let entries;
+    try {
+        entries = await readdir(root);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const e of entries)
+        if (e !== MAIN && ACCOUNT_NAME.test(e) && (await lstatOrNull(join(root, e)))?.isDirectory())
+            out.push(e);
+    return out.sort();
+}
+function checkName(def, name) {
+    if (name !== MAIN && !ACCOUNT_NAME.test(name))
+        throw new UserError(`"${name}" is not a valid ${def.title} window name; use lowercase letters, digits and dashes, starting with a letter or digit (for example \`sideby desktop ${def.id}:work\`)`, { code: 'invalid-name' });
+}
+/**
+ * Every App Profile with its state, for `sideby list` and the Panel: only on macOS, and per app only when it is
+ * installed or has Profiles. The Main Profile first. Never throws.
+ */
+export async function listAppProfiles(rt) {
+    const deps = depsFor(rt);
+    if (deps.platform !== 'darwin')
+        return [];
+    const home = rt.paths.home;
+    const out = [];
+    try {
+        let procs = null;
+        for (const def of PROFILE_APPS) {
+            const app = await findApp(def, deps);
+            const names = await profileNames(profilesRoot(home, def));
+            if (!app && !names.length)
+                continue;
+            if (app && !procs)
+                procs = (await processes(deps)) ?? [];
+            for (const name of [MAIN, ...names]) {
+                const appData = appDataOf(home, def, name);
+                const status = join(appData ?? join(home, def.mainUserData), def.statusFile);
+                const s = await signedIn(status);
+                out.push({
+                    ref: `${def.id}:${name}`,
+                    app: def.title,
+                    name,
+                    isMain: name === MAIN,
+                    ...(appData ? { appData } : {}),
+                    installed: app !== null,
+                    running: app ? Boolean(instanceOf(app, appData, procs ?? [])) : false,
+                    ...(s === undefined ? {} : { signedIn: s }),
+                });
+            }
+        }
+    }
+    catch {
+        // A display nicety: a failure shows no Profiles.
+    }
+    return out;
+}
+async function located(rt, ref) {
+    const parsed = parseProfileRef(ref);
+    if (!parsed)
+        throw new UserError(`${ref} is not an app window; use \`sideby desktop grok-bot:<name>\``);
+    const { def, name } = parsed;
+    checkName(def, name);
+    const deps = depsFor(rt);
+    if (deps.platform !== 'darwin')
+        throw notMac(deps.platform);
+    const app = await findApp(def, deps, { spotlight: true });
+    if (!app)
+        throw notInstalled(def, deps);
+    return { deps, def, name, app, appData: appDataOf(rt.paths.home, def, name) };
+}
+/**
+ * Opens an App Profile's window, creating its folder first when it is new, or brings its running window to the front.
+ * Never starts a second window for the same Profile and never ends a process.
+ */
+export async function openAppProfile(rt, ref) {
+    const { deps, def, name, app, appData } = await located(rt, ref);
+    const listed = await processes(deps);
+    const procs = listed ?? [];
+    const base = {
+        ref: `${def.id}:${name}`,
+        family: def.id,
+        app: def.title,
+        appPath: app.path,
+        ...(appData ? { appData } : {}),
+        createdAppData: false,
+        linked: [],
+        notices: [],
+    };
+    const running = instanceOf(app, appData, procs);
+    if (running) {
+        const focused = await activate(deps, running.pid);
+        return {
+            ...base,
+            action: focused ? 'focused' : 'already-running',
+            notices: focused
+                ? []
+                : [
+                    `${def.title} is already open as ${base.ref}; switch to it from the Dock (sideby does not start a second one)`,
+                ],
+        };
+    }
+    let created = false;
+    const notices = [];
+    if (appData) {
+        const st = await lstatOrNull(appData);
+        if (st && !st.isDirectory())
+            throw new UserError(`${appData} is not a folder; move it away, then try again (sideby keeps the ${def.title} window ${base.ref} there)`, { code: 'app-data-invalid' });
+        if (!st) {
+            await mkdir(appData, { recursive: true, mode: 0o700 });
+            await chmod(appData, 0o700);
+            created = true;
+        }
+        if (created || !(await readdir(appData)).length) {
+            const others = procs.some((p) => mainArgs(app, p) !== null);
+            notices.push(`New ${def.title} window ${base.ref}: sign in inside it with the account you want for this window.${others ? ` Close the other ${def.title} windows while you sign in, because the browser may send the sign-in back to one of them.` : ''}`);
+        }
+    }
+    // As for a Desktop App: `-n` also for the Main Profile, unless a running one cannot be ruled out.
+    const args = appData ? def.openArgs(app.path, appData) : listed ? ['-n', '-a', app.path] : ['-a', app.path];
+    const r = await deps.exec('/usr/bin/open', args, cleanEnv(rt.env, def.clearVars));
+    if (r.code !== 0)
+        throw new UserError(`could not open ${def.title} as ${base.ref}: ${r.stderr.trim() || `open exited with ${r.code}`}; try opening ${app.path} once by hand, then try again`, { code: 'open-failed' });
+    return { ...base, action: 'started', createdAppData: created, command: ['/usr/bin/open', ...args], notices };
+}
+/**
+ * Removes a non-main App Profile's folder, which signs that window out and deletes its local data. Without `yes` it
+ * only returns what would go. Refuses the Main Profile, a running window, a missing folder and anything that is not a
+ * real folder inside sideby's own; never follows a link.
+ */
+export async function removeAppProfile(rt, ref, opts) {
+    const parsed = parseProfileRef(ref);
+    if (!parsed)
+        throw new UserError(`${ref} is not an app window; use \`sideby desktop grok-bot:<name> --remove\``);
+    const { def, name } = parsed;
+    checkName(def, name);
+    const full = `${def.id}:${name}`;
+    if (name === MAIN)
+        throw new UserError(`${full} is ${def.title}'s own data, which sideby does not remove; sign out inside ${def.title} instead`, { code: 'main-profile' });
+    const deps = depsFor(rt);
+    if (deps.platform !== 'darwin')
+        throw notMac(deps.platform);
+    const appData = appDataOf(rt.paths.home, def, name);
+    const st = await lstatOrNull(appData);
+    if (!st)
+        throw new UserError(`there is no ${def.title} window ${full}; \`sideby list\` shows the ones there are`, {
+            code: 'no-profile',
+        });
+    if (!st.isDirectory())
+        throw new UserError(`${appData} is not a folder sideby made; it was left alone, move it away by hand`, {
+            code: 'app-data-invalid',
+        });
+    const app = await findApp(def, deps, { spotlight: true });
+    // Without a process list an open window cannot be ruled out, and deleting under a running app breaks it.
+    const procs = app ? await processes(deps) : [];
+    if (procs === null || (app && instanceOf(app, appData, procs)))
+        throw new UserError(procs === null
+            ? `could not check whether ${def.title} is open as ${full}; quit that window, then try again`
+            : `${def.title} is open as ${full}; quit that window first, then remove it`, { code: 'app-running' });
+    if (!opts.yes)
+        return { ref: full, app: def.title, appData, removed: false };
+    await rm(appData, { recursive: true, force: true });
+    return { ref: full, app: def.title, appData, removed: true };
+}

package/dist/src/core/brand-mark.d.ts

@@ -0,0 +1,29 @@
+export type RoundedRect = readonly [x: number, y: number, w: number, h: number, r: number];
+export declare const MARK: {
+    readonly back: readonly [12, 82, 128, 104, 44];
+    readonly front: readonly [116, 70, 128, 116, 46];
+    /** Cut out of the back face (and its eyes) so the two faces never touch. */
+    readonly gap: readonly [104, 58, 152, 140, 58];
+    readonly backEyes: readonly [readonly [45, 119, 14, 26, 7], readonly [83, 119, 14, 26, 7]];
+    readonly frontEyes: readonly [readonly [155, 111, 14, 26, 7], readonly [193, 111, 14, 26, 7]];
+};
+export declare const MARK_COLORS: {
+    readonly front: '#3f8fc4';
+    readonly back: '#f2b35e';
+    readonly eye: '#1e2a44';
+};
+/** The square the mark is drawn in when it sits on a tile (about 78% of the tile is mark). */
+export declare const MARK_TILE_VIEWBOX: {
+    readonly x: -20.5;
+    readonly y: -20.5;
+    readonly size: 297;
+};
+export declare function roundedRectPath([x, y, w, h, r]: RoundedRect): string;
+/**
+ * The mark as SVG children (no outer <svg>). The front face has no fill of its own, so it takes the surrounding
+ * `fill` (the Panel's `--logo-fg`, which Portals can set with `logoColor`); the back face and the eyes are fixed.
+ * `id` names the gap mask; keep it unique per document.
+ */
+export declare function markSvgBody(id: string, front?: string): string;
+/** The Panel's header logo: the mark sized for its 40 px tile. */
+export declare const MARK_SVG: string;

package/dist/src/core/brand-mark.js

@@ -0,0 +1,42 @@
+// The sideby mark: two friendly faces side by side, the amber one behind and the blue one in front, cut apart by a
+// gap that follows the front face (ADR-0020). One source for the Panel header, the empty state and the app icon.
+// Geometry is on a 256-unit grid centred on (128, 128); rounded rectangles are [x, y, width, height, radius].
+export const MARK = {
+    back: [12, 82, 128, 104, 44],
+    front: [116, 70, 128, 116, 46],
+    /** Cut out of the back face (and its eyes) so the two faces never touch. */
+    gap: [104, 58, 152, 140, 58],
+    backEyes: [
+        [45, 119, 14, 26, 7],
+        [83, 119, 14, 26, 7],
+    ],
+    frontEyes: [
+        [155, 111, 14, 26, 7],
+        [193, 111, 14, 26, 7],
+    ],
+};
+export const MARK_COLORS = { front: '#3f8fc4', back: '#f2b35e', eye: '#1e2a44' };
+/** The square the mark is drawn in when it sits on a tile (about 78% of the tile is mark). */
+export const MARK_TILE_VIEWBOX = { x: -20.5, y: -20.5, size: 297 };
+export function roundedRectPath([x, y, w, h, r]) {
+    return (`M${x + r} ${y}H${x + w - r}A${r} ${r} 0 0 1 ${x + w} ${y + r}V${y + h - r}A${r} ${r} 0 0 1 ${x + w - r} ${y + h}` +
+        `H${x + r}A${r} ${r} 0 0 1 ${x} ${y + h - r}V${y + r}A${r} ${r} 0 0 1 ${x + r} ${y}Z`);
+}
+/**
+ * The mark as SVG children (no outer <svg>). The front face has no fill of its own, so it takes the surrounding
+ * `fill` (the Panel's `--logo-fg`, which Portals can set with `logoColor`); the back face and the eyes are fixed.
+ * `id` names the gap mask; keep it unique per document.
+ */
+export function markSvgBody(id, front) {
+    const eyes = (list) => list.map(roundedRectPath).join('');
+    const frontFill = front ? ` fill="${front}"` : '';
+    return (`<mask id="${id}" maskUnits="userSpaceOnUse" x="0" y="0" width="256" height="256">` +
+        `<rect width="256" height="256" fill="#fff"/><path fill="#000" d="${roundedRectPath(MARK.gap)}"/></mask>` +
+        `<g mask="url(#${id})"><path fill="${MARK_COLORS.back}" d="${roundedRectPath(MARK.back)}"/>` +
+        `<path fill="${MARK_COLORS.eye}" d="${eyes(MARK.backEyes)}"/></g>` +
+        `<path${frontFill} d="${roundedRectPath(MARK.front)}"/>` +
+        `<path fill="${MARK_COLORS.eye}" d="${eyes(MARK.frontEyes)}"/>`);
+}
+const V = MARK_TILE_VIEWBOX;
+/** The Panel's header logo: the mark sized for its 40 px tile. */
+export const MARK_SVG = `<svg viewBox="${V.x} ${V.y} ${V.size} ${V.size}">${markSvgBody('sideby-mark-gap')}</svg>`;

package/dist/src/core/claude-settings-file.d.ts

@@ -0,0 +1,17 @@
+import type { Account } from '../types.ts';
+export type Json = Record<string, unknown>;
+export declare const isObj: (v: unknown) => v is Json;
+export declare function render(obj: Json, original: string): string;
+export declare function readObject(file: string): Promise<{
+    text: string;
+    obj: Json;
+} | {
+    error: string;
+}>;
+/** Where the Account's settings really live, and whether `settings.json` is a link to it. */
+export declare function locate(account: Account): Promise<{
+    file: string;
+    link: boolean;
+    exists: boolean;
+    broken?: boolean;
+}>;

package/dist/src/core/claude-settings-file.js

@@ -0,0 +1,53 @@
+// One Claude Account's `settings.json`, as the writers of a single key use it (tune apply, ADR-0012; Remote Control,
+// ADR-0017): where it really lives, a safe read, and rendering it back with the file's own indentation.
+import { readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { lstatOrNull, realpathOrNull } from './fs-safe.js';
+const MAX_BYTES = 5_000_000;
+export const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+function detectIndent(text) {
+    const m = /^([ \t]+)"/m.exec(text);
+    if (!m)
+        return 2;
+    const lead = m[1];
+    return lead.startsWith('\t') ? '\t' : lead.length;
+}
+export function render(obj, original) {
+    const out = JSON.stringify(obj, null, detectIndent(original));
+    return original.endsWith('\n') || original === '' ? `${out}\n` : out;
+}
+export 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 };
+}
+/** Where the Account's settings really live, and whether `settings.json` is a link to it. */
+export 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 };
+}

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 };
 }