sideby 0.13.0 → 0.14.0

package/dist/src/core/quota-fetch.js

@@ -0,0 +1,98 @@
+import { keptQuota, quotaStoreFile, readQuotaStore, writeQuotaStore, } from './quota-store.js';
+import { inCi } from './update.js';
+export const FETCH_TIMEOUT_MS = 20_000;
+/** How long a `background` read waits when nothing is kept yet, so a first Panel load still shows Quota. */
+const FIRST_WAIT_MS = 4_000;
+/** One fetch per Account file at a time, shared by every reader in this process. */
+const inFlight = new Map();
+/** Why fetching is off for `family`, or null when it is on (spec §3.26). */
+export function quotaCheckOff(family, config, env) {
+    if (config.quota?.check?.[family] === false)
+        return `Quota checks are turned off for this tool (config quota.check.${family}); turn them on in the Panel's settings`;
+    if (inCi(env))
+        return 'Quota checks are off in CI';
+    return null;
+}
+const sleep = (ms) => new Promise((resolve) => {
+    setTimeout(() => resolve(null), ms).unref();
+});
+async function runFetch(fq, account, ctx, hostEnv, file) {
+    const kept = await readQuotaStore(file);
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), FETCH_TIMEOUT_MS);
+    const aborted = new Promise((_, reject) => {
+        ac.signal.addEventListener('abort', () => reject(new Error('aborted')), { once: true });
+    });
+    aborted.catch(() => { });
+    let answer;
+    let error;
+    try {
+        answer = await Promise.race([fq.fetch(account, { ...ctx, signal: ac.signal, hostEnv }), aborted]);
+    }
+    catch (err) {
+        error = ac.signal.aborted
+            ? `no answer within ${FETCH_TIMEOUT_MS / 1000} seconds; sideby asks again in ${fq.everyMinutes} minutes`
+            : (err?.message ?? String(err));
+    }
+    finally {
+        clearTimeout(timer);
+        if (!ac.signal.aborted)
+            ac.abort();
+    }
+    if (answer?.status === 'unavailable')
+        error = answer.detail ?? answer.reason;
+    const quota = answer?.status === 'ok' ? keptQuota(answer) : kept?.quota;
+    const entry = {
+        version: 1,
+        attemptedAt: new Date().toISOString(),
+        ...(quota ? { quota } : {}),
+        ...(error ? { error } : {}),
+    };
+    await writeQuotaStore(file, entry).catch(() => { });
+    return entry;
+}
+/** The kept answer for `account`, after asking again when `mode` and its age say so. */
+export async function fetchedQuota(fq, account, ctx, hostEnv, mode) {
+    const file = quotaStoreFile(ctx.stateDir, account.family, account.name);
+    const kept = await readQuotaStore(file);
+    if (mode === 'never')
+        return kept;
+    const at = kept ? Date.parse(kept.attemptedAt) : Number.NaN;
+    const age = ctx.now.getTime() - at;
+    // A time in the future (a changed clock) counts as old, so it cannot stop every later fetch.
+    const stale = !kept || !Number.isFinite(at) || age < -60_000 || age >= fq.everyMinutes * 60_000;
+    if (mode !== 'force' && !stale)
+        return kept;
+    let run = inFlight.get(file);
+    if (!run) {
+        run = runFetch(fq, account, ctx, hostEnv, file).finally(() => inFlight.delete(file));
+        inFlight.set(file, run);
+    }
+    if (mode !== 'background')
+        return run;
+    run.catch(() => { });
+    if (kept)
+        return kept;
+    return Promise.race([run, sleep(FIRST_WAIT_MS)]).then((e) => e ?? kept);
+}
+/**
+ * What sideby shows from a Family that fetches Quota: the newer of the kept answer and the local reading; else why
+ * there is none (`off` is why fetching is off, or null).
+ */
+export function shownQuota(local, kept, off) {
+    const fetched = kept?.quota
+        ? { ...kept.quota, fetched: true, ...(kept.error ? { fetchError: kept.error } : {}) }
+        : null;
+    const own = local?.status === 'ok' ? local : null;
+    if (fetched && own)
+        return Date.parse(own.observedAt) > Date.parse(fetched.observedAt) ? own : fetched;
+    if (fetched)
+        return fetched;
+    if (own)
+        return own;
+    if (off)
+        return { status: 'unavailable', reason: 'not-enabled', detail: off };
+    if (kept?.error)
+        return { status: 'unavailable', reason: 'fetch-failed', detail: kept.error };
+    return local ?? { status: 'unavailable', reason: 'no-session' };
+}

package/dist/src/core/quota-levels.d.ts

@@ -13,7 +13,8 @@ export declare function quotaLevel(usedPercent: number): QuotaLevel;
 export declare function windowReset(resetsAt: string, now: Date): boolean;
 /**
  * Quota Pressure: the used percent of the fullest window that has not reset yet (0 when all have reset),
- * or null when the Account has no Quota. The Panel keeps its own copy (`quotaPressure` in page-logic.ts,
- * -1 for null) because page-logic helpers must be self-contained; a test keeps the two equal.
+ * or null when the Account has no Quota. A window with a `name` covers only some models and never counts (spec
+ * §3.26). The Panel keeps its own copy (`quotaPressure` in page-logic.ts, -1 for null) because page-logic helpers
+ * must be self-contained; a test keeps the two equal.
  */
 export declare function quotaPressure(quota: QuotaResult | undefined, now: Date): number | null;

package/dist/src/core/quota-levels.js

@@ -20,14 +20,18 @@ export function windowReset(resetsAt, now) {
 }
 /**
  * Quota Pressure: the used percent of the fullest window that has not reset yet (0 when all have reset),
- * or null when the Account has no Quota. The Panel keeps its own copy (`quotaPressure` in page-logic.ts,
- * -1 for null) because page-logic helpers must be self-contained; a test keeps the two equal.
+ * or null when the Account has no Quota. A window with a `name` covers only some models and never counts (spec
+ * §3.26). The Panel keeps its own copy (`quotaPressure` in page-logic.ts, -1 for null) because page-logic helpers
+ * must be self-contained; a test keeps the two equal.
  */
 export function quotaPressure(quota, now) {
-    if (quota?.status !== 'ok' || quota.windows.length === 0)
+    if (quota?.status !== 'ok')
+        return null;
+    const windows = quota.windows.filter((w) => !w.name);
+    if (windows.length === 0)
         return null;
     let max = 0;
-    for (const w of quota.windows)
+    for (const w of windows)
         if (!windowReset(w.resetsAt, now))
             max = Math.max(max, Math.min(100, Number(w.usedPercent) || 0));
     return max;

package/dist/src/core/quota-store.d.ts

@@ -0,0 +1,19 @@
+import type { QuotaResult } from '../types.ts';
+export type FetchedQuota = Extract<QuotaResult, {
+    status: 'ok';
+}>;
+export interface QuotaStoreEntry {
+    version: 1;
+    /** When the latest fetch finished, good or not; the next one waits `everyMinutes` from here. */
+    attemptedAt: string;
+    /** The latest good answer, kept while later fetches fail. */
+    quota?: FetchedQuota;
+    /** Why the latest fetch failed, when it did. */
+    error?: string;
+}
+export declare function quotaStoreFile(stateDir: string, family: string, name: string): string;
+/** Only the fields a Quota reading may carry, so a plugin's extra fields never reach the file. */
+export declare function keptQuota(q: FetchedQuota): FetchedQuota;
+/** The kept answer, or null when there is none or the file is not one sideby wrote. */
+export declare function readQuotaStore(file: string): Promise<QuotaStoreEntry | null>;
+export declare function writeQuotaStore(file: string, entry: QuotaStoreEntry): Promise<void>;

package/dist/src/core/quota-store.js

@@ -0,0 +1,62 @@
+// The kept answers of `FamilyDef.fetchQuota` (spec §3.26): one file per Account in sideby's state directory, with the
+// Quota numbers, reset times and plan name only. The handoff hook reads it, so this module imports only Node
+// built-ins and leaf modules (never the Runtime, a Family index or core/accounts.ts).
+import { mkdir, readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { writeFileAtomic } from './fs-safe.js';
+export function quotaStoreFile(stateDir, family, name) {
+    return join(stateDir, 'quota', family, `${name}.fetched.json`);
+}
+const isWindow = (w) => {
+    const v = w;
+    return (typeof v === 'object' &&
+        v !== null &&
+        typeof v.label === 'string' &&
+        (v.name === undefined || typeof v.name === 'string') &&
+        typeof v.windowMinutes === 'number' &&
+        typeof v.usedPercent === 'number' &&
+        typeof v.resetsAt === 'string');
+};
+/** Only the fields a Quota reading may carry, so a plugin's extra fields never reach the file. */
+export function keptQuota(q) {
+    return {
+        status: 'ok',
+        windows: q.windows.filter(isWindow).map((w) => ({
+            label: w.label,
+            ...(w.name ? { name: w.name } : {}),
+            windowMinutes: w.windowMinutes,
+            usedPercent: w.usedPercent,
+            resetsAt: w.resetsAt,
+        })),
+        observedAt: q.observedAt,
+        source: q.source,
+        ...(typeof q.plan === 'string' && q.plan ? { plan: q.plan } : {}),
+    };
+}
+/** The kept answer, or null when there is none or the file is not one sideby wrote. */
+export async function readQuotaStore(file) {
+    let data;
+    try {
+        data = JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    const e = data;
+    if (typeof e !== 'object' || e === null || e.version !== 1 || typeof e.attemptedAt !== 'string')
+        return null;
+    const q = e.quota;
+    const quota = q && q.status === 'ok' && Array.isArray(q.windows) && typeof q.observedAt === 'string'
+        ? keptQuota({ ...q, source: typeof q.source === 'string' ? q.source : '' })
+        : undefined;
+    return {
+        version: 1,
+        attemptedAt: e.attemptedAt,
+        ...(quota ? { quota } : {}),
+        ...(typeof e.error === 'string' ? { error: e.error } : {}),
+    };
+}
+export async function writeQuotaStore(file, entry) {
+    await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+    await writeFileAtomic(file, `${JSON.stringify(entry)}\n`, 0o600);
+}

package/dist/src/core/skill-check.d.ts

@@ -1,7 +1,22 @@
 import type { FamilyDef, Finding } from '../types.ts';
 export declare const SKILL_INSTALL = "npx skills add Adonis0123/sideby -g";
+/** The folder holding `dir` that is a git work tree, if any: a skill there is managed by that repository. */
+export declare function gitRootOf(dir: string): Promise<string | null>;
 /** `metadata.version` from a SKILL.md frontmatter, or null when there is none. */
 export declare function skillVersionOf(text: string): string | null;
+/**
+ * The versions of the sideby skills an agent reads on this machine (`null`: a skill without one): where
+ * `npx skills add -g` puts it (`~/.agents/skills`) and Claude Code's user skills. Read for a `--json` output's
+ * `_notice`, so it looks at two fixed files only; Doctor checks every Family's main directory.
+ */
+export declare function installedSkillVersions(home: string): Promise<(string | null)[]>;
+/** The same skills with the real folder each lives in (for `sideby update`, which may update them). */
+export declare function installedSkills(home: string): Promise<{
+    dir: string;
+    version: string | null;
+}[]>;
+/** The command `sideby update` runs to update an installed sideby skill: it keeps the agents it was installed for. */
+export declare const SKILL_UPDATE: readonly ['npx', '-y', 'skills', 'update', 'sideby', '-g', '-y'];
 /**
  * Checks, for each given Family, the sideby skill its Host reads: `<main>/skills/sideby`, and for Codex also
  * `~/.agents/skills/sideby` (where `npx skills add -g` installs and Codex reads user skills). A file is read

package/dist/src/core/skill-check.js

@@ -1,17 +1,59 @@
 // Doctor's look at an installed sideby Agent Skill (spec §3.11). Read-only: a skill written for another
 // sideby version teaches commands this CLI may not have, so a version mismatch is a warning with the
 // reinstall command. Not installed is not a problem.
-import { readFile, realpath } from 'node:fs/promises';
-import { join } from 'node:path';
+import { readFile, realpath, stat } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
 import { mainDirOf } from './accounts.js';
 import { tildify } from './paths.js';
 export const SKILL_INSTALL = 'npx skills add Adonis0123/sideby -g';
+/** The folder holding `dir` that is a git work tree, if any: a skill there is managed by that repository. */
+export async function gitRootOf(dir) {
+    for (let d = dir;; d = dirname(d)) {
+        try {
+            await stat(join(d, '.git'));
+            return d;
+        }
+        catch {
+            // keep looking up
+        }
+        if (dirname(d) === d)
+            return null;
+    }
+}
 /** `metadata.version` from a SKILL.md frontmatter, or null when there is none. */
 export function skillVersionOf(text) {
     const front = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text)?.[1];
     const meta = front && /^metadata:[ \t]*\r?\n((?:[ \t]+.*(?:\r?\n|$))*)/m.exec(front)?.[1];
     return (meta && /^[ \t]+version:[ \t]*['"]?([^'"\s]+)/m.exec(meta)?.[1]) || null;
 }
+/**
+ * The versions of the sideby skills an agent reads on this machine (`null`: a skill without one): where
+ * `npx skills add -g` puts it (`~/.agents/skills`) and Claude Code's user skills. Read for a `--json` output's
+ * `_notice`, so it looks at two fixed files only; Doctor checks every Family's main directory.
+ */
+export async function installedSkillVersions(home) {
+    return (await installedSkills(home)).map((s) => s.version);
+}
+/** The same skills with the real folder each lives in (for `sideby update`, which may update them). */
+export async function installedSkills(home) {
+    const seen = new Set();
+    const out = [];
+    for (const dir of [join(home, '.agents', 'skills'), join(home, '.claude', 'skills')]) {
+        try {
+            const real = await realpath(join(dir, 'sideby', 'SKILL.md'));
+            if (seen.has(real))
+                continue;
+            seen.add(real);
+            out.push({ dir: dirname(real), version: skillVersionOf(await readFile(real, 'utf8')) });
+        }
+        catch {
+            // not installed there
+        }
+    }
+    return out;
+}
+/** The command `sideby update` runs to update an installed sideby skill: it keeps the agents it was installed for. */
+export const SKILL_UPDATE = ['npx', '-y', 'skills', 'update', 'sideby', '-g', '-y'];
 /**
  * Checks, for each given Family, the sideby skill its Host reads: `<main>/skills/sideby`, and for Codex also
  * `~/.agents/skills/sideby` (where `npx skills add -g` installs and Codex reads user skills). A file is read
@@ -42,13 +84,17 @@ export async function checkInstalledSkills(home, families, version) {
         if (found === version)
             continue;
         const where = tildify(path, home);
+        // `sideby update` brings the skill along, except one a git repository owns (a dotfiles clone, say).
+        const repo = await gitRootOf(dirname(real));
         out.push({
             level: 'warn',
             account: `${family.id}:main`,
             item: where,
             code: 'skill.outdated',
             message: `the sideby skill at ${where} is ${found ? `for sideby ${found}` : 'from before skills had a version'}; this sideby is ${version}`,
-            hint: `update it with \`${SKILL_INSTALL}\`, so agents learn this version's commands`,
+            hint: repo
+                ? `it lives in the git repository ${tildify(repo, home)}: update it where that repository comes from (\`npx skills update sideby -g\` there), so agents learn this version's commands`
+                : `run \`sideby update\`, which updates the skill too (or \`${SKILL_INSTALL}\` by hand), so agents learn this version's commands`,
             source: 'core',
             fixable: false,
         });

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

@@ -114,6 +114,27 @@ export declare function refreshUpdateCheck(paths: Paths, env: Env): Promise<Upda
 export declare function noticeLine(cache: UpdateCache, current: string, now: Date): string | null;
 /** What the CLI says once about the last Auto Update, or null. */
 export declare function autoUpdateLine(cache: UpdateCache): string | null;
+/** The `_notice` of a `--json` output (spec §3.23): what an agent should mention once its task is done. */
+export interface JsonNotice {
+    update?: {
+        current: string;
+        latest: string;
+        command: string;
+        message: string;
+    };
+    skill?: {
+        installed: string | null;
+        current: string;
+        command: string;
+        message: string;
+    };
+}
+/**
+ * The `_notice` for a `--json` output, from the cached Update Check and the versions of the installed sideby skills
+ * (`null` for one written before skills had a version); null when there is nothing to say or checks are off. It
+ * reads no network: an agent sees what the last check found, as a person sees the Update Notice.
+ */
+export declare function jsonNotice(cache: UpdateCache, current: string, config: UpdateSettings, env: Env, skills: readonly (string | null)[], skillCommand: string): JsonNotice | null;
 /**
  * What the CLI does after a command (spec §3.23), decided from the cache: the lines to print (the Auto Update result,
  * then the Update Notice), the change that records them, and whether to start a background check. The caller prints,
@@ -153,6 +174,8 @@ export interface UpdatePlan {
     command: string;
     canRun: boolean;
     releaseNotes: string;
+    /** The installed sideby skill, which an Update brings along (absent when none is installed). */
+    skill?: SkillUpdatePlan;
 }
 export declare function planFrom(method: InstallMethod, current: string, latest: string, env?: Env): UpdatePlan;
 /** The Install Method as outputs show it: no folder of this machine. */
@@ -174,9 +197,28 @@ export declare function shownPlan(plan: UpdatePlan): {
     command: string;
     canRun: boolean;
     releaseNotes: string;
+    skillUpdate?: SkillUpdatePlan | undefined;
 };
+/** What an Update does to the installed sideby skill (spec §3.23, ADR-0021 amendment 2026-10-17). */
+export interface SkillUpdatePlan {
+    /** Versions of the installed skills (`null`: one without a version). */
+    installed: (string | null)[];
+    /** Some installed skill is for another version than the one sideby will run. */
+    outdated: boolean;
+    command: string;
+    /** False when sideby must not run it; `reason` says why and the user runs `command` where it belongs. */
+    canRun: boolean;
+    reason?: string;
+}
+/** The skill part of an Update toward `target`; null when no sideby skill is installed. Reads two files. */
+export declare function skillUpdatePlan(home: string, target: string): Promise<SkillUpdatePlan | null>;
 /** Asks the registry now (whatever the switches say: the user asked) and returns what an Update would do. */
 export declare function planUpdate(paths: Paths, env: Env): Promise<UpdatePlan>;
+/** Updates the installed sideby skill when the plan says it is outdated and sideby may; null when it did nothing. */
+export declare function applySkillUpdate(plan: SkillUpdatePlan | undefined, env: Env, onOutput?: (text: string) => void): Promise<{
+    ok: boolean;
+    message: string;
+} | null>;
 export interface UpdateResult {
     ok: boolean;
     /** Exit code of the install command; absent when it did not run. */
@@ -189,6 +231,9 @@ export interface UpdateResult {
     refreshedApp: 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. */
+    skillUpdated?: boolean;
+    skillMessage?: string;
 }
 /**
  * Runs the Update the plan names, then starts a running background Panel again from the new code and, when the

package/dist/src/core/update.js

@@ -6,6 +6,7 @@ import { access, constants, mkdir, open, readdir, readFile, realpath, rm, stat }
 import { dirname, join, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { writeFileAtomic } from './fs-safe.js';
+import { gitRootOf, installedSkills, SKILL_INSTALL, SKILL_UPDATE } from './skill-check.js';
 import { localBuild, packageVersion, parseLocalBuild } from './version.js';
 export const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
 export const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
@@ -351,6 +352,32 @@ export function autoUpdateLine(cache) {
         ? `sideby updated itself from ${a.from} to ${a.to} (${RELEASE_NOTES(a.to)})`
         : `sideby could not update itself to ${a.to}: ${a.message}`;
 }
+/**
+ * The `_notice` for a `--json` output, from the cached Update Check and the versions of the installed sideby skills
+ * (`null` for one written before skills had a version); null when there is nothing to say or checks are off. It
+ * reads no network: an agent sees what the last check found, as a person sees the Update Notice.
+ */
+export function jsonNotice(cache, current, config, env, skills, skillCommand) {
+    if (checksOff(env, config))
+        return null;
+    const out = {};
+    if (isNewer(cache.latest, current))
+        out.update = {
+            current,
+            latest: cache.latest,
+            command: 'sideby update',
+            message: `sideby ${cache.latest} is available (this is ${current}); \`sideby update\` shows what it runs and updates after --yes`,
+        };
+    const stale = skills.find((v) => v !== current);
+    if (stale !== undefined)
+        out.skill = {
+            installed: stale,
+            current,
+            command: skillCommand,
+            message: `the installed sideby skill is ${stale ? `for sideby ${stale}` : 'from before skills had a version'}; this sideby is ${current}. \`${skillCommand}\` updates it`,
+        };
+    return out.update || out.skill ? out : null;
+}
 /**
  * What the CLI does after a command (spec §3.23), decided from the cache: the lines to print (the Auto Update result,
  * then the Update Notice), the change that records them, and whether to start a background check. The caller prints,
@@ -532,14 +559,55 @@ export function shownPlan(plan) {
         command: plan.command,
         canRun: plan.canRun,
         releaseNotes: plan.releaseNotes,
+        ...(plan.skill ? { skillUpdate: plan.skill } : {}),
+    };
+}
+/** The skill part of an Update toward `target`; null when no sideby skill is installed. Reads two files. */
+export async function skillUpdatePlan(home, target) {
+    const skills = await installedSkills(home);
+    if (!skills.length)
+        return null;
+    const installed = skills.map((s) => s.version);
+    const plan = {
+        installed,
+        outdated: installed.some((v) => v !== target),
+        command: SKILL_UPDATE.join(' '),
+        canRun: true,
     };
+    for (const s of skills) {
+        const root = await gitRootOf(s.dir);
+        if (root) {
+            const at = root.startsWith(home) ? `~${root.slice(home.length)}` : root;
+            return {
+                ...plan,
+                command: SKILL_INSTALL,
+                canRun: false,
+                reason: `the skill is in the git repository ${at}, so sideby leaves it alone; update it where that repository comes from`,
+            };
+        }
+    }
+    return plan;
 }
 /** Asks the registry now (whatever the switches say: the user asked) and returns what an Update would do. */
 export async function planUpdate(paths, env) {
     const latest = await fetchLatest(env);
     const at = deps().now().toISOString();
     await updateUpdateCache(paths, { checkedAt: at, triedAt: at, latest }).catch(() => { });
-    return planFrom(await installMethod(env), packageVersion(), latest, env);
+    const plan = planFrom(await installMethod(env), packageVersion(), latest, env);
+    const skill = await skillUpdatePlan(paths.home, plan.available ? latest : plan.current).catch(() => null);
+    return skill ? { ...plan, skill } : plan;
+}
+/** Updates the installed sideby skill when the plan says it is outdated and sideby may; null when it did nothing. */
+export async function applySkillUpdate(plan, env, onOutput) {
+    if (!plan?.outdated || !plan.canRun)
+        return null;
+    const [file, ...args] = SKILL_UPDATE;
+    const r = await deps()
+        .exec(file, args, { env, ...(onOutput ? { onOutput } : {}) })
+        .catch((e) => ({ code: 1, output: e instanceof Error ? e.message : String(e) }));
+    return r.code === 0
+        ? { ok: true, message: 'updated the sideby skill' }
+        : { ok: false, message: `\`${plan.command}\` failed (exit ${r.code}); run it yourself to see why` };
 }
 /**
  * Runs the Update the plan names, then starts a running background Panel again from the new code and, when the
@@ -582,6 +650,8 @@ 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 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 {
             ok: true,
             code: 0,
@@ -589,6 +659,7 @@ export async function applyUpdate(paths, plan, env, opts = {}) {
             message: `updated sideby from ${plan.current} to ${plan.latest}`,
             restartedPanel: restarted,
             refreshedApp: refreshed,
+            ...(skill ? { skillUpdated: skill.ok, skillMessage: skill.message } : {}),
         };
     }
     finally {

package/dist/src/families/grok/handoff-hook.d.ts

@@ -1,4 +1,10 @@
 import { type HookReader } from '../../handoff/reader.ts';
+import type { Env } from '../../types.ts';
+/** The Account the hook runs for, from `GROK_HOME`: unset or `~/.grok` is `main`, `.grok-<name>` is `<name>`. */
+export declare function grokAccountFromEnv(env: Env): {
+    name: string;
+    dir: string;
+} | null;
 /** Substrings that mean the usage pool or credits are used up. `StopFailure.error` has no class of its own for it. */
 export declare const GROK_USED_UP: string[];
 export declare const grokHookReader: HookReader;

package/dist/src/families/grok/handoff-hook.js

@@ -1,6 +1,28 @@
-// Grok Build for the handoff hook (spec §3.17): no public Quota, so only a turn that failed at the limit starts a
-// Handoff. Leaf module. The wording comes from the grok 1.0.50 binary; check it again when Grok changes.
+// Grok Build for the handoff hook (spec §3.17, §3.26): Quota Pressure from the kept answer of its CLI and the billing
+// lines it writes to its log, and a turn that failed at the limit. Leaf module: the hook runs on every tool call. The
+// wording comes from the grok 1.0.50 binary; check it again when Grok changes.
+import { homedir } from 'node:os';
+import { basename, join, resolve } from 'node:path';
+import { ACCOUNT_NAME } from '../../core/account-name.js';
+import { resolvePaths } from '../../core/paths.js';
+import { quotaPressure } from '../../core/quota-levels.js';
+import { quotaStoreFile, readQuotaStore } from '../../core/quota-store.js';
 import { field } from '../../handoff/reader.js';
+import { grokLogFile, HOOK_LOG_READ_BYTES, lastGrokBilling } from './quota-log.js';
+const MAIN_DIR = '.grok';
+const ACCOUNT_PREFIX = '.grok-';
+/** The Account the hook runs for, from `GROK_HOME`: unset or `~/.grok` is `main`, `.grok-<name>` is `<name>`. */
+export function grokAccountFromEnv(env) {
+    const home = env.HOME || homedir();
+    const dir = env.GROK_HOME;
+    if (!dir || resolve(dir) === join(home, MAIN_DIR))
+        return { name: 'main', dir: join(home, MAIN_DIR) };
+    const base = basename(dir);
+    if (!base.startsWith(ACCOUNT_PREFIX))
+        return null;
+    const name = base.slice(ACCOUNT_PREFIX.length);
+    return name !== 'main' && ACCOUNT_NAME.test(name) ? { name, dir } : null;
+}
 /** Substrings that mean the usage pool or credits are used up. `StopFailure.error` has no class of its own for it. */
 export const GROK_USED_UP = [
     'You hit your weekly limit',
@@ -15,6 +37,27 @@ export const GROK_USED_UP = [
     'status 402',
 ];
 export const grokHookReader = {
+    async pressure(_input, env, now) {
+        const account = grokAccountFromEnv(env);
+        if (!account)
+            return null;
+        try {
+            const [log, kept] = await Promise.all([
+                lastGrokBilling(grokLogFile(account.dir), HOOK_LOG_READ_BYTES),
+                readQuotaStore(quotaStoreFile(resolvePaths(env).stateDir, 'grok', account.name)),
+            ]);
+            const fetched = kept?.quota ?? null;
+            const newer = log && fetched
+                ? Date.parse(log.observedAt) > Date.parse(fetched.observedAt)
+                    ? log
+                    : fetched
+                : (log ?? fetched);
+            return newer ? quotaPressure(newer, now) : null;
+        }
+        catch {
+            return null;
+        }
+    },
     limitHit(input) {
         if (field(input, 'subagentType'))
             return false;

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

@@ -41,7 +41,12 @@ export declare function grokEligibility(policy: ReturnType<typeof grokPolicy>, a
     start: boolean;
     receive: boolean;
 };
-/** The whole file setup writes; teardown removes it only while it is still exactly this. */
+/**
+ * The file sideby 0.13 and earlier wrote: no `PostToolUse`, since Grok had no Quota to prepare a Handoff from then.
+ * Setup replaces it, teardown removes it (spec §3.26).
+ */
+export declare const GROK_HOOK_FILE_V1: string;
+/** The whole file setup writes; teardown removes it only while it is still exactly this (or `GROK_HOOK_FILE_V1`). */
 export declare function grokHookFileText(): string;
 export declare const grokHookSetup: QuotaSetup;
 export declare const grokHandoff: FamilyHandoff;