sideby 0.16.0 → 0.17.0

package/dist/src/core/terminal.js

@@ -0,0 +1,371 @@
+import { constants, realpathSync } from 'node:fs';
+import { access, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Supported macOS terminals; custom templates have no app bundle or environment marker. */
+export const TERMINALS = [
+    {
+        id: 'terminal',
+        name: 'Terminal',
+        bundleId: 'com.apple.Terminal',
+        app: 'Terminal.app',
+        termPrograms: ['Apple_Terminal'],
+    },
+    {
+        id: 'iterm2',
+        name: 'iTerm2',
+        bundleId: 'com.googlecode.iterm2',
+        app: 'iTerm.app',
+        termPrograms: ['iTerm.app'],
+    },
+    {
+        id: 'ghostty',
+        name: 'Ghostty',
+        bundleId: 'com.mitchellh.ghostty',
+        app: 'Ghostty.app',
+        termPrograms: ['ghostty'],
+    },
+    {
+        id: 'orca',
+        name: 'Orca',
+        bundleId: 'com.stablyai.orca',
+        app: 'Orca.app',
+        termPrograms: ['Orca'],
+        binary: 'orca',
+    },
+    {
+        id: 'wezterm',
+        name: 'WezTerm',
+        bundleId: 'com.github.wez.wezterm',
+        app: 'WezTerm.app',
+        termPrograms: ['WezTerm'],
+        binary: 'wezterm',
+    },
+    {
+        id: 'kitty',
+        name: 'kitty',
+        bundleId: 'net.kovidgoyal.kitty',
+        app: 'kitty.app',
+        termPrograms: [],
+        marker: 'KITTY_WINDOW_ID',
+        binary: 'kitty',
+    },
+    {
+        id: 'alacritty',
+        name: 'Alacritty',
+        bundleId: 'org.alacritty',
+        app: 'Alacritty.app',
+        termPrograms: [],
+        marker: 'ALACRITTY_WINDOW_ID',
+    },
+    { id: 'custom', name: 'Custom', bundleId: null, app: null, termPrograms: [] },
+];
+/** Finds bundles and command line launchers without opening apps or reading user files. */
+export async function installedTerminals(deps) {
+    if ((deps.platform ?? process.platform) !== 'darwin')
+        return [];
+    const fs = deps.fs ?? { stat, access };
+    const dirs = deps.appDirs ?? [
+        '/Applications',
+        join(deps.home, 'Applications'),
+        '/System/Applications/Utilities',
+        '/Applications/Utilities',
+    ];
+    const found = [];
+    for (const terminal of TERMINALS) {
+        if (!terminal.app)
+            continue;
+        let appPath;
+        for (const dir of dirs) {
+            const path = join(dir, terminal.app);
+            if (await fs.stat(path).then((s) => s.isDirectory(), () => false)) {
+                appPath = path;
+                break;
+            }
+        }
+        let executable;
+        if (terminal.binary) {
+            for (const dir of (deps.env.PATH ?? '').split(':').filter(Boolean)) {
+                const path = join(dir, terminal.binary);
+                if ((await fs.stat(path).then((s) => s.isFile(), () => false)) &&
+                    (await fs.access(path, constants.X_OK).then(() => true, () => false))) {
+                    executable = path;
+                    break;
+                }
+            }
+            if (!executable && appPath)
+                executable = join(appPath, terminal.id === 'orca' ? 'Contents/Resources/bin' : 'Contents/MacOS', terminal.binary);
+        }
+        if (appPath || (terminal.id === 'orca' && executable))
+            found.push({ id: terminal.id, ...(appPath ? { appPath } : {}), ...(executable ? { executable } : {}) });
+    }
+    return found;
+}
+/** Chooses an installed preference, then the launching environment, then macOS Terminal. */
+export function guessTerminal(opts) {
+    const has = (id) => opts.installed.some((t) => t.id === id);
+    if (opts.preferred && has(opts.preferred))
+        return { id: opts.preferred, source: 'config' };
+    const match = TERMINALS.find((t) => has(t.id) &&
+        (t.termPrograms.includes(opts.env.TERM_PROGRAM ?? '') || Boolean(t.marker && opts.env[t.marker])));
+    return match ? { id: match.id, source: 'env' } : { id: 'terminal', source: 'default' };
+}
+/** This process's Node and the real path of the CLI entry next to this module (`main.ts` from source, `main.js` from dist). */
+export function askLauncher() {
+    const ext = import.meta.url.endsWith('.ts') ? 'ts' : 'js';
+    const entry = fileURLToPath(new URL(`../cli/main.${ext}`, import.meta.url));
+    let real = entry;
+    try {
+        real = realpathSync(entry);
+    }
+    catch {
+        // Keep the unresolved path; the terminal reports it if it is missing.
+    }
+    return { node: process.execPath, entry: real };
+}
+// A path the terminal's shell reads exactly: absolute, and no control character, newline or backslash
+// (fish treats a backslash inside single quotes as an escape).
+// Built from a string: a regex literal with control characters reads as a typo to linters.
+const CONTROL = new RegExp(String.raw `[\x00-\x1f\x7f]`);
+const safePath = (path) => path.startsWith('/') && !path.includes('\\') && !CONTROL.test(path);
+/** Why the terminal cannot run this launcher, or null when it can. */
+export function launcherProblem(launcher, stateDir) {
+    if (!safePath(launcher.node) ||
+        !safePath(launcher.entry) ||
+        (stateDir !== undefined && !safePath(stateDir)))
+        return {
+            ok: false,
+            reason: 'unsafe-path',
+            detail: 'sideby, Node or its state folder is in a folder whose name a terminal cannot run safely; install sideby with `npm i -g sideby`, or paste the task command into your terminal.',
+        };
+    if (launcher.entry.includes('/_npx/'))
+        return {
+            ok: false,
+            reason: 'npx-cache',
+            detail: 'sideby runs from the npx cache, which can disappear; install it with `npm i -g sideby` and try again, or paste the task command into your terminal now.',
+        };
+    return null;
+}
+/**
+ * Builds the only shell command accepted by the AI Task terminal launcher: the quoted Node and CLI entry, or
+ * `sideby` by name when `launcher` is null (a command for the user to paste where sideby is on PATH). It carries the
+ * state folder the task was written to, so a terminal whose environment differs from the Panel's still finds it.
+ */
+export function askRunCommand(taskId, stateDir, launcher = askLauncher()) {
+    if (!/^[a-f0-9]{16}$/.test(taskId))
+        throw new Error('Invalid task id; create the AI task again.');
+    if (!launcher)
+        // Pasted by hand: a state folder a shell cannot take safely is left out, and `ask --run` uses the environment's.
+        return `sideby ask --run '${taskId}'${safePath(stateDir) ? ` --state-dir ${quote(stateDir)}` : ''}`;
+    if (!safePath(launcher.node) || !safePath(launcher.entry) || !safePath(stateDir))
+        throw new Error('Unsafe sideby path; install sideby with `npm i -g sideby` and try again.');
+    return `${quote(launcher.node)} ${quote(launcher.entry)} ask --run '${taskId}' --state-dir ${quote(stateDir)}`;
+}
+function quote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+// AppleScript string literals know only \\ and \" as escapes; a control character is refused, not encoded.
+function appleString(value) {
+    if (CONTROL.test(value))
+        throw new Error('Invalid task command; create the AI task again.');
+    return `"${value.replace(/[\\"]/g, (c) => `\\${c}`)}"`;
+}
+// The quoted launcher and state paths, as askRunCommand writes them: single-quoted runs joined by \' (an escaped quote).
+const QUOTED = String.raw `(?:'[^'\\\x00-\x1f\x7f]*'|\\')+`;
+const TASK_COMMAND = new RegExp(`^${QUOTED} ${QUOTED} ask --run '[a-f0-9]{16}' --state-dir ${QUOTED}$`);
+/** For `sh -c`: when the command fails, the window waits for Return instead of closing on its error. */
+function holdOnFailure(command) {
+    return `${command} || { echo; echo "sideby: press Return to close"; read _; }`;
+}
+// Tokenize before substitution: paths and commands remain one argument, even with quotes or newlines.
+function customArgs(template) {
+    const args = [];
+    let word = '', quoted = '', started = false;
+    for (let i = 0; i < template.length; i++) {
+        const c = template[i];
+        if (c === '\\' && quoted !== "'") {
+            if (++i === template.length)
+                throw new Error('Incomplete escape; fix the custom terminal template.');
+            word += template[i];
+            started = true;
+        }
+        else if (quoted) {
+            if (c === quoted)
+                quoted = '';
+            else
+                word += c;
+        }
+        else if (c === '"' || c === "'") {
+            quoted = c;
+            started = true;
+        }
+        else if (/\s/.test(c)) {
+            if (started) {
+                args.push(word);
+                word = '';
+                started = false;
+            }
+        }
+        else {
+            word += c;
+            started = true;
+        }
+    }
+    if (quoted)
+        throw new Error('Unclosed quote; fix the custom terminal template.');
+    if (started)
+        args.push(word);
+    return args;
+}
+/**
+ * Splits a custom terminal template into argv, throwing unless it names a program first and has both `{cmd}` and
+ * `{cwd}` in its arguments.
+ */
+export function validateCustomTemplate(template) {
+    const args = customArgs(template);
+    const file = args[0];
+    const rest = args.slice(1);
+    if (!file ||
+        file.includes('{') ||
+        !rest.some((a) => a.includes('{cmd}')) ||
+        !rest.some((a) => a.includes('{cwd}')) ||
+        template.includes('\0'))
+        throw new Error("Set a custom terminal executable and both {cmd} and {cwd} placeholders, such as `sideby terminal --custom 'my-term --cwd {cwd} -e {cmd}'`.");
+    return [file, ...rest];
+}
+/** Builds argv only. The caller supplies discovered bundle/binary paths when available. */
+export function launchArgs(id, opts) {
+    if (!TASK_COMMAND.test(opts.command))
+        throw new Error('Invalid task command; create the AI task again.');
+    if (opts.cwd.includes('\0'))
+        throw new Error('Invalid working directory; choose another folder.');
+    // `ask --run` changes to the task's directory itself, so cwd goes only where a terminal takes it as an argument.
+    const { cwd, command } = opts;
+    const held = holdOnFailure(command);
+    switch (id) {
+        case 'terminal':
+            return {
+                file: '/usr/bin/osascript',
+                args: [
+                    '-e',
+                    `tell application id "com.apple.Terminal"
+if not running then launch
+do script ${appleString(command)}
+activate
+end tell`,
+                ],
+            };
+        case 'iterm2':
+            return {
+                file: '/usr/bin/osascript',
+                args: [
+                    '-e',
+                    // Always a new window of its own: "current window" can be iTerm2's updater or settings window, and a
+                    // just-started iTerm2 may open no window at all.
+                    `tell application id "com.googlecode.iterm2"
+activate
+set taskWindow to (create window with default profile)
+tell current session of taskWindow to write text ${appleString(command)}
+end tell`,
+                ],
+            };
+        // Use the CLI for both running and stopped Ghostty; AppleScript new window needs newer versions.
+        case 'ghostty':
+            return {
+                file: '/usr/bin/open',
+                args: [
+                    '-na',
+                    opts.appPath ?? 'Ghostty',
+                    '--args',
+                    `--working-directory=${cwd}`,
+                    '-e',
+                    '/bin/sh',
+                    '-lc',
+                    held,
+                ],
+            };
+        case 'orca':
+            return {
+                file: opts.executable ?? 'orca',
+                args: [
+                    'terminal',
+                    'create',
+                    '--worktree',
+                    'active',
+                    '--command',
+                    command,
+                    '--title',
+                    'sideby',
+                    '--focus',
+                    '--json',
+                ],
+            };
+        case 'wezterm':
+            return {
+                file: opts.executable ?? join(opts.appPath ?? '/Applications/WezTerm.app', 'Contents/MacOS/wezterm'),
+                args: ['start', '--cwd', cwd, '--', '/bin/sh', '-lc', held],
+            };
+        case 'kitty':
+            return {
+                file: opts.executable ?? join(opts.appPath ?? '/Applications/kitty.app', 'Contents/MacOS/kitty'),
+                args: ['--single-instance', '--directory', cwd, '/bin/sh', '-lc', held],
+            };
+        case 'alacritty':
+            return {
+                file: '/usr/bin/open',
+                args: [
+                    '-na',
+                    opts.appPath ?? 'Alacritty',
+                    '--args',
+                    '--working-directory',
+                    cwd,
+                    '-e',
+                    '/bin/sh',
+                    '-lc',
+                    held,
+                ],
+            };
+        case 'custom': {
+            const [file, ...args] = validateCustomTemplate(opts.custom ?? '');
+            return {
+                file,
+                args: args.map((a) => a.replace(/\{(cmd|cwd)\}/g, (_, key) => (key === 'cmd' ? command : cwd))),
+            };
+        }
+        default:
+            throw new Error('Unknown terminal; choose an installed terminal in Settings.');
+    }
+}
+/** Opens through the injected Desktop exec boundary, returning safe, actionable failures only. */
+export async function openTerminal(id, opts, exec) {
+    if ((opts.platform ?? process.platform) !== 'darwin')
+        return { ok: false, reason: 'unsupported-platform' };
+    const installed = opts.installed.find((t) => t.id === id);
+    if (!installed && id !== 'custom')
+        return {
+            ok: false,
+            reason: 'not-installed',
+            detail: 'Install this terminal or choose another in Settings; paste the task command into your terminal.',
+        };
+    try {
+        const launch = launchArgs(id, { ...opts, ...installed });
+        const result = await exec(launch.file, launch.args);
+        if (result.code === 0)
+            return { ok: true };
+        if (launch.file === '/usr/bin/osascript' &&
+            (result.code === -1743 || /-1743|Not authorized to send Apple events/i.test(result.stderr)))
+            return {
+                ok: false,
+                reason: 'automation-denied',
+                detail: 'Allow Automation in System Settings > Privacy & Security > Automation, then try again; or paste the task command into your terminal.',
+            };
+    }
+    catch {
+        // Never expose process output or thrown messages: they may contain private data.
+    }
+    return {
+        ok: false,
+        reason: 'failed',
+        detail: 'Could not open the terminal; check its settings or paste the task command into your terminal.',
+    };
+}

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

@@ -66,7 +66,14 @@ export interface InstallMethod {
     /** npm only: the prefix whose `lib/node_modules` holds sideby. */
     prefix?: string;
 }
+/** Whether a Linux `/proc/<pid>/stat` line is of a zombie: the state after the parenthesised command name is `Z`. */
+export declare function isZombieStat(stat: string): boolean;
 /** Swapped in tests through `bindUpdateDeps`; the real machine otherwise. */
+/**
+ * Whether `sideby autostart --refresh --json` rewrote the login item: it exits 0 also when nothing changed or the
+ * rewrite was refused, so only its `changed: true` counts.
+ */
+export declare function autostartRefreshed(code: number | null, stdout: string): boolean;
 export interface UpdateDeps {
     fetch: typeof fetch;
     now: () => Date;
@@ -84,10 +91,16 @@ export interface UpdateDeps {
     }>;
     /** Starts `sideby ui --background --no-open --port <port>` from the newly installed code, detached; false when it could not start. */
     restartPanel: (env: Env, port: number) => Promise<boolean>;
+    /** Starts a program detached, nothing kept of its output; false when it could not start. */
+    startDetached: (file: string, args: readonly string[], env: Env) => Promise<boolean>;
     /** Whether `sideby app install` put a desktop app in this home (its files carry the app marker). */
     appInstalled: (home: string, env: Env) => Promise<boolean>;
     /** Runs `sideby app install --json` from the newly installed code and waits; false when it failed. */
     refreshApp: (env: Env) => Promise<boolean>;
+    /** Whether `sideby autostart on` put a login item in this home (its file carries the sideby marker). */
+    autostartInstalled: (home: string) => Promise<boolean>;
+    /** Runs `sideby autostart --refresh --json` from the newly installed code and waits; false when it failed. */
+    refreshAutostart: (env: Env) => Promise<boolean>;
 }
 /** Internal, for tests: replaces parts of the machine. Not part of the plugin or Portal contract. */
 export declare function bindUpdateDeps(deps: Partial<UpdateDeps>): () => void;
@@ -95,6 +108,8 @@ export declare function bindUpdateDeps(deps: Partial<UpdateDeps>): () => void;
 export declare const runProgram: UpdateDeps['exec'];
 /** Starts the background Panel again from the code `sideby` now names; see `UpdateDeps.restartPanel`. */
 export declare const restartPanelByName: (env: Env, port: number) => Promise<boolean>;
+/** Starts a program detached through the swappable machine; see `UpdateDeps.startDetached`. */
+export declare const startDetached: (file: string, args: readonly string[], env: Env) => Promise<boolean>;
 /** The lock every install shares (`update-install.lock`), so a Local Build switch never races an Update. */
 export declare const takeInstallLock: (paths: Paths) => Promise<(() => Promise<void>) | null>;
 /** -1, 0 or 1 like a sort comparator; a prerelease sorts before its release. Null when either is not a version. */
@@ -301,6 +316,8 @@ export interface UpdateResult {
     restartedPanel: boolean;
     /** The desktop app was installed and `sideby app install` ran again from the new code. */
     refreshedApp: boolean;
+    /** A login item was installed (spec §3.29) and `sideby autostart --refresh` ran from the new code; absent without one. */
+    refreshedAutostart?: boolean;
     /** Another Update held the lock; nothing ran. */
     busy?: boolean;
     /** The installed sideby skill was updated too (true), or that failed (false); absent when it was not tried. */

package/dist/src/core/update.js

@@ -2,6 +2,7 @@
 // only network request sideby makes on its own: one GET for the `latest` dist-tag, carrying nothing about the user.
 // Everything it learns goes to one state file shared by the CLI and every Panel.
 import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
 import { access, constants, mkdir, open, readdir, readFile, realpath, rm, stat } from 'node:fs/promises';
 import { dirname, join, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -17,6 +18,25 @@ export const RETRY_INTERVAL_MS = 60 * 60 * 1000;
 export const AUTO_RETRY_MS = 24 * 60 * 60 * 1000;
 const FETCH_TIMEOUT_MS = 5000;
 export const RELEASE_NOTES = (v) => `https://github.com/Adonis0123/sideby/releases/tag/v${v}`;
+/** Whether a Linux `/proc/<pid>/stat` line is of a zombie: the state after the parenthesised command name is `Z`. */
+export function isZombieStat(stat) {
+    return /\)\s+Z\s/.test(stat.slice(stat.lastIndexOf(')')));
+}
+/** Swapped in tests through `bindUpdateDeps`; the real machine otherwise. */
+/**
+ * Whether `sideby autostart --refresh --json` rewrote the login item: it exits 0 also when nothing changed or the
+ * rewrite was refused, so only its `changed: true` counts.
+ */
+export function autostartRefreshed(code, stdout) {
+    if (code !== 0)
+        return false;
+    try {
+        return JSON.parse(stdout)?.changed === true;
+    }
+    catch {
+        return false;
+    }
+}
 /** The folder of the sideby package this module belongs to: two levels above src/, three above dist/src/. */
 async function ownPackageDir() {
     const here = dirname(fileURLToPath(import.meta.url));
@@ -41,11 +61,18 @@ const realDeps = {
     alive(pid) {
         try {
             process.kill(pid, 0);
-            return true;
         }
         catch (err) {
             return err.code === 'EPERM';
         }
+        // An exited process nobody waited for (its parent went first) still answers signal 0 on Linux: a zombie holds
+        // no lock and runs no session.
+        try {
+            return !isZombieStat(readFileSync(`/proc/${pid}/stat`, 'utf8'));
+        }
+        catch {
+            return true; // no /proc (macOS): signal 0 is the answer
+        }
     },
     exec: (file, args, opts) => new Promise((resolve) => {
         let output = '';
@@ -77,6 +104,14 @@ const realDeps = {
         });
         child.once('error', () => resolve(false));
     }),
+    startDetached: (file, args, env) => new Promise((resolve) => {
+        const child = spawn(file, args, { env: env, detached: true, stdio: 'ignore' });
+        child.once('spawn', () => {
+            child.unref();
+            resolve(true);
+        });
+        child.once('error', () => resolve(false));
+    }),
     appInstalled: async (home, env) => {
         const { appInstalled } = await import('../desktop/app.js');
         return appInstalled({ home, env, platform: process.platform });
@@ -91,6 +126,25 @@ const realDeps = {
         child.once('error', () => resolve(false));
         child.once('close', (code) => resolve(code === 0));
     }),
+    autostartInstalled: async (home) => {
+        const { autostartInstalled } = await import('./autostart.js');
+        return autostartInstalled(home);
+    },
+    refreshAutostart: (env) => new Promise((resolve) => {
+        // By name, like refreshApp: the new code records its own Node and entry; it never creates a login item.
+        const child = spawn('sideby', ['autostart', '--refresh', '--json'], {
+            env: env,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 60_000,
+        });
+        let out = '';
+        child.stdout?.on('data', (d) => {
+            if (out.length < 65_536)
+                out += d.toString();
+        });
+        child.once('error', () => resolve(false));
+        child.once('close', (code) => resolve(autostartRefreshed(code, out)));
+    }),
 };
 let override = {};
 /** Internal, for tests: replaces parts of the machine. Not part of the plugin or Portal contract. */
@@ -108,6 +162,10 @@ export const runProgram = (file, args, opts) => deps().exec(file, args, opts);
 export const restartPanelByName = (env, port) => deps()
     .restartPanel(env, port)
     .catch(() => false);
+/** Starts a program detached through the swappable machine; see `UpdateDeps.startDetached`. */
+export const startDetached = (file, args, env) => deps()
+    .startDetached(file, args, env)
+    .catch(() => false);
 /** The lock every install shares (`update-install.lock`), so a Local Build switch never races an Update. */
 export const takeInstallLock = (paths) => takeLock(paths, 'update-install.lock').catch(() => null);
 // Build metadata is limited to what semver allows, so a version never carries a terminal escape into the notice.
@@ -759,6 +817,9 @@ export async function applyUpdate(paths, plan, env, opts = {}) {
         // the new code writes it again. Only where one is installed; a failure here never fails the Update.
         const installed = await d.appInstalled(paths.home, env).catch(() => false);
         const refreshed = installed && (await d.refreshApp(env).catch(() => false));
+        // The login item records the Node and entry it starts, like the app (ADR-0029); never created here.
+        const autostart = await d.autostartInstalled(paths.home).catch(() => false);
+        const refreshedAutostart = autostart ? await d.refreshAutostart(env).catch(() => false) : undefined;
         // The skill teaches agents this version's commands, so it follows the CLI; a failure there keeps the Update.
         const skill = await applySkillUpdate(plan.skill, env, opts.onOutput);
         return {
@@ -768,6 +829,7 @@ export async function applyUpdate(paths, plan, env, opts = {}) {
             message: `updated sideby from ${plan.current} to ${plan.latest}`,
             restartedPanel: restarted,
             refreshedApp: refreshed,
+            ...(refreshedAutostart !== undefined ? { refreshedAutostart } : {}),
             ...(skill ? { skillUpdated: skill.ok, skillMessage: skill.message } : {}),
         };
     }

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

@@ -105,6 +105,9 @@ export const claudeFamily = {
         'ANTHROPIC_DEFAULT_OPUS_MODEL',
     ],
     apiVars: ['ANTHROPIC_BASE_URL', 'ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_MODEL'],
+    secretVar: 'ANTHROPIC_AUTH_TOKEN',
+    // `-p` is one non-interactive prompt (Claude Code 2.1.301 --help, 2026-10-17).
+    probe: { args: ['-p', 'Reply with OK'] },
     sharedItems: [
         ...LINKED.map((path) => ({ path, mode: 'link' })),
         { path: '.claude.json', mode: 'json-key', key: 'mcpServers', mainPath: '.claude.json', credential: true },

package/dist/src/families/claude/quota-cache.d.ts

@@ -4,27 +4,44 @@ export interface ClaudeQuotaCache {
     /** When the status line last reported these windows. */
     observedAt: string;
     windows: QuotaWindow[];
+    /**
+     * Per status line session id: a hash of the windows it last reported and when that changed. Only these two values
+     * are kept for a session (at most {@link MAX_SESSIONS}, none older than {@link SESSION_DAYS} days). Files written
+     * before sessions were tracked have none.
+     */
+    sessions?: Record<string, SessionSeen>;
+}
+export interface SessionSeen {
+    hash: string;
+    seenAt: string;
+}
+/** A status line reading: the cache fields and, when Claude Code sent one, the session that reported it. */
+export interface QuotaReading extends ClaudeQuotaCache {
+    sessionId?: string;
 }
 export declare function claudeQuotaCacheFile(stateDir: string, name: string): string;
 /** sideby's state directory for this environment (same rule as the Runtime). */
 export declare function cacheStateDir(env: Env): string;
 /** Account name from CLAUDE_CONFIG_DIR: unset or `~/.claude` is `main`, `.claude-<name>` is `<name>`, else null. */
 export declare function accountNameFromEnv(env: Env): string | null;
-/** Extracts the 5h and 7d windows from status line JSON; null when there is nothing usable. */
-export declare function parseRateLimits(input: string, observedAt: Date): ClaudeQuotaCache | null;
+/** Extracts the 5h and 7d windows and the session id from status line JSON; null when there is nothing usable. */
+export declare function parseRateLimits(input: string, observedAt: Date): QuotaReading | null;
 /**
- * Merges a status line reading into the cached windows. Each session reports the Quota of its own last request, so an
- * idle session of the same Account reports older numbers, sometimes of a window that has already reset: within one
- * window the higher use wins, otherwise the later reset; a window the reading lacks is kept. Null when the reading
- * only repeats older numbers, so nothing is written and `observedAt` keeps the time of the newer reading.
+ * Merges a status line reading into the cache (spec §3.7). Each session reports the Quota of its own last request, so
+ * an idle session of the same Account keeps repeating older numbers. A reading whose session reported exactly these
+ * windows before carries nothing new: null, so nothing is written. A reading that changed, or the first of a session,
+ * is a fresh request result and wins for every window it has, the vendor's resets included; a window it lacks is
+ * kept. A reading without a session id falls back to: within one window the higher use wins, otherwise the reading
+ * wins; null when that only repeats the cache.
  */
-export declare function mergeQuotaCache(cached: readonly QuotaWindow[], next: ClaudeQuotaCache): ClaudeQuotaCache | null;
+export declare function mergeQuotaCache(cached: Pick<ClaudeQuotaCache, 'windows' | 'sessions'> | null, next: QuotaReading): ClaudeQuotaCache | null;
 /** Writes the cache atomically; creates the private parent directory first (writeFileAtomic does not). */
 export declare function writeQuotaCache(stateDir: string, name: string, cache: ClaudeQuotaCache): Promise<void>;
 export type CacheRead = {
     status: 'ok';
     observedAt: string;
     windows: QuotaWindow[];
+    sessions?: Record<string, SessionSeen>;
 } | {
     status: 'missing';
 } | {