sideby 0.13.1 → 0.15.0

package/dist/src/core/update.js

@@ -6,7 +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 { installedSkills, SKILL_INSTALL, SKILL_UPDATE } from './skill-check.js';
+import { installedSkills, SKILL_UPDATE, SKILL_UPDATE_SHOWN, skillOwnerRepo } 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;
@@ -151,21 +151,25 @@ export function sameLine(from, to) {
 const set = (v) => v !== undefined && v !== '' && v !== '0' && v.toLowerCase() !== 'false';
 /** True in CI, where a notice is noise and a check is a request nobody reads. */
 export const inCi = (env) => set(env.CI) || set(env.CONTINUOUS_INTEGRATION) || set(env.BUILD_NUMBER);
-/** Why Update Checks are off, or null when they are on (spec §3.23). */
-export function checksOff(env, config, local = localBuild() !== null) {
+/** Why Update Checks are off, with a code for the Panel, or null when they are on (spec §3.23). */
+export function checksOffWhy(env, config, local = localBuild() !== null) {
     // A Local Build (ADR-0024) follows the checkout: a notice or an Auto Update would only replace it with npm's.
     if (local)
-        return 'this is a local build (pnpm local)';
+        return { code: 'local-build', text: 'this is a local build (pnpm local)' };
     if (set(env.SIDEBY_NO_UPDATE_NOTIFIER))
-        return 'SIDEBY_NO_UPDATE_NOTIFIER is set';
+        return { code: 'env', text: 'SIDEBY_NO_UPDATE_NOTIFIER is set' };
     if (set(env.NO_UPDATE_NOTIFIER))
-        return 'NO_UPDATE_NOTIFIER is set';
+        return { code: 'env', text: 'NO_UPDATE_NOTIFIER is set' };
     if (config.update?.check === false)
-        return 'config update.check is false';
+        return { code: 'config', text: 'config update.check is false' };
     if (inCi(env))
-        return 'running in CI';
+        return { code: 'ci', text: 'running in CI' };
     return null;
 }
+/** Why Update Checks are off, or null when they are on (spec §3.23). */
+export function checksOff(env, config, local = localBuild() !== null) {
+    return checksOffWhy(env, config, local)?.text ?? null;
+}
 // ---- registry
 /** The registry checks and installs use: `SIDEBY_UPDATE_REGISTRY` (http or https only), else npm's. */
 function registryOf(env) {
@@ -217,6 +221,18 @@ export async function readUpdateCache(paths) {
                 message: a.message,
                 ...(a.shown ? { shown: true } : {}),
             };
+        const sn = d.skillNotified;
+        if (sn && str(sn.version) && str(sn.at))
+            out.skillNotified = { version: sn.version, at: sn.at };
+        const sa = d.skillAuto;
+        if (sa && str(sa.to) && str(sa.at) && typeof sa.ok === 'boolean' && str(sa.message))
+            out.skillAuto = {
+                to: sa.to,
+                at: sa.at,
+                ok: sa.ok,
+                message: sa.message,
+                ...(sa.shown ? { shown: true } : {}),
+            };
         return out;
     }
     catch {
@@ -352,6 +368,44 @@ 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}`;
 }
+/** What the CLI says once about the skill Auto Update brought up to date alone, or null. */
+export function skillAutoLine(cache) {
+    const a = cache.skillAuto;
+    if (!a || a.shown)
+        return null;
+    return a.ok
+        ? `sideby updated the sideby skill agents read to ${a.to}`
+        : `sideby could not update the sideby skill to ${a.to}: ${a.message}`;
+}
+/** The skill part of a `SkillUpdatePlan` toward the running version, as `afterCommandPlan` takes it. */
+export const skillBehind = (plan, current) => plan?.outdated
+    ? { installed: plan.installed.find((v) => v !== current) ?? null, canRun: plan.canRun }
+    : null;
+/**
+ * The line about a skill behind this version the CLI may print now (spec §3.23), or null: once a day per CLI version,
+ * and never while Auto Update is on (the background check brings the skill along) and sideby may update it.
+ */
+export function skillNoticeLine(cache, current, config, skill, now) {
+    if (!skill || (config.update?.auto === true && skill.canRun))
+        return null;
+    const n = cache.skillNotified;
+    if (n && n.version === current && age(n.at, now) < NOTICE_INTERVAL_MS)
+        return null;
+    return `the sideby skill agents read is for ${skill.installed ?? 'an older sideby'} (this sideby is ${current}) · run \`sideby update\``;
+}
+/**
+ * Auto Update is on, the CLI is the newest version the cache knows, and the skill is behind it where sideby may
+ * update it, not tried for this version yet (or a failed try a day ago). A newer CLI waiting is left to the Update
+ * of the CLI: the skills tool fetches the default branch, which would put the skill ahead of this CLI.
+ */
+export function skillAutoPending(cache, current, config, skill, now) {
+    if (config.update?.auto !== true || !skill?.canRun || isNewer(cache.latest, current))
+        return false;
+    const a = cache.skillAuto;
+    if (!a || a.to !== current)
+        return true;
+    return !a.ok && !(age(a.at, now) < AUTO_RETRY_MS);
+}
 /**
  * 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
@@ -383,27 +437,40 @@ export function jsonNotice(cache, current, config, env, skills, skillCommand) {
  * then the Update Notice), the change that records them, and whether to start a background check. The caller prints,
  * writes `record` with `updateUpdateCache` and starts the check; nothing here touches the machine.
  */
-export function afterCommandPlan(cache, current, config, env, now) {
+export function afterCommandPlan(cache, current, config, env, now, skill = null) {
     if (checksOff(env, config))
         return { lines: [], record: null, startCheck: false };
     const lines = [];
     const auto = autoUpdateLine(cache);
+    const skillAuto = skillAutoLine(cache);
     const notice = noticeLine(cache, current, now);
-    if (auto)
-        lines.push(auto);
-    if (notice)
-        lines.push(notice);
+    // A newer CLI's notice already leads to `sideby update`, which brings the skill along.
+    const skillNotice = notice ? null : skillNoticeLine(cache, current, config, skill, now);
+    for (const l of [auto, skillAuto, notice, skillNotice])
+        if (l)
+            lines.push(l);
     const shownAuto = cache.auto;
+    const shownSkillAuto = cache.skillAuto;
     const record = lines.length
         ? (cur) => ({
             // Mark only the Auto Update that was printed; a newer one written meanwhile stays to be said.
             ...(auto && cur.auto && cur.auto.at === shownAuto?.at && cur.auto.to === shownAuto.to
                 ? { auto: { ...cur.auto, shown: true } }
                 : {}),
+            ...(skillAuto && cur.skillAuto && cur.skillAuto.at === shownSkillAuto?.at
+                ? { skillAuto: { ...cur.skillAuto, shown: true } }
+                : {}),
             ...(notice ? { notified: { version: cache.latest, at: now.toISOString() } } : {}),
+            ...(skillNotice ? { skillNotified: { version: current, at: now.toISOString() } } : {}),
         })
         : null;
-    return { lines, record, startCheck: checkDue(cache, now) || autoPending(cache, current, config, now) };
+    return {
+        lines,
+        record,
+        startCheck: checkDue(cache, now) ||
+            autoPending(cache, current, config, now) ||
+            skillAutoPending(cache, current, config, skill, now),
+    };
 }
 // ---- Install Method
 /** Where the running copy comes from (spec §3.23 table); reads only paths. */
@@ -421,16 +488,20 @@ export async function installMethod(env) {
         if (parseLocalBuild(JSON.parse(await readFile(join(packageDir, 'dist', 'build.json'), 'utf8'))))
             return at('local', {
                 reason: 'it is a local build; run `pnpm local --off` in the sideby checkout to go back to npm',
+                reasonCode: 'local-build',
             });
     }
     catch {
         // no build file: not a Local Build
     }
     if (p.includes('/_npx/'))
-        return at('npx', { reason: 'it runs from the npx cache, which fetches a version per call' });
+        return at('npx', {
+            reason: 'it runs from the npx cache, which fetches a version per call',
+            reasonCode: 'npx',
+        });
     // Volta keeps a global package under its own npm prefix; installing there behind its back breaks its records.
     if (p.includes('/.volta/'))
-        return at('volta', { reason: 'Volta manages this install' });
+        return at('volta', { reason: 'Volta manages this install', reasonCode: 'volta' });
     const npm = /^(.*)\/lib\/node_modules\/sideby$/.exec(p);
     if (npm) {
         const prefix = npm[1];
@@ -442,7 +513,11 @@ export async function installMethod(env) {
             prefix,
             canUpdate: !blocked.length,
             ...(blocked.length
-                ? { reason: `${blocked.join(' and ')} ${blocked.length > 1 ? 'are' : 'is'} not writable by you` }
+                ? {
+                    reason: `${blocked.join(' and ')} ${blocked.length > 1 ? 'are' : 'is'} not writable by you`,
+                    reasonCode: 'not-writable',
+                    reasonAt: blocked.join(', '),
+                }
                 : {}),
         });
     }
@@ -452,8 +527,8 @@ export async function installMethod(env) {
     if (p.includes('/.bun/install/global/'))
         return at('bun', { canUpdate: true });
     if (p.includes('/node_modules/'))
-        return at('project', { reason: 'it is a dependency of a project' });
-    return at('source', { reason: 'it runs from a source checkout' });
+        return at('project', { reason: 'it is a dependency of a project', reasonCode: 'project' });
+    return at('source', { reason: 'it runs from a source checkout', reasonCode: 'source' });
 }
 /**
  * The command an Update runs (or that the user runs) for `version`; `run` is set only when sideby may run it. With
@@ -548,6 +623,8 @@ export const shownMethod = (m) => ({
     kind: m.kind,
     canUpdate: m.canUpdate,
     ...(m.reason ? { reason: m.reason } : {}),
+    ...(m.reasonCode ? { reasonCode: m.reasonCode } : {}),
+    ...(m.reasonAt ? { reasonAt: m.reasonAt } : {}),
 });
 /** The plan as `sideby update --json` and the Panel show it (schemas/update.json). */
 export function shownPlan(plan) {
@@ -562,20 +639,6 @@ export function shownPlan(plan) {
         ...(plan.skill ? { skillUpdate: plan.skill } : {}),
     };
 }
-/** The folder holding `dir` that is a git work tree, if any: a skill there is managed by that repository. */
-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;
-    }
-}
 /** 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);
@@ -589,14 +652,17 @@ export async function skillUpdatePlan(home, target) {
         canRun: true,
     };
     for (const s of skills) {
-        const root = await gitRootOf(s.dir);
+        // A git repository owns the skill unless the skills tool records installing it there (spec §3.23).
+        const root = await skillOwnerRepo(s.dir);
         if (root) {
             const at = root.startsWith(home) ? `~${root.slice(home.length)}` : root;
             return {
                 ...plan,
-                command: SKILL_INSTALL,
+                command: SKILL_UPDATE_SHOWN,
                 canRun: false,
                 reason: `the skill is in the git repository ${at}, so sideby leaves it alone; update it where that repository comes from`,
+                reasonCode: 'skill-in-git',
+                reasonAt: at,
             };
         }
     }
@@ -623,6 +689,27 @@ export async function applySkillUpdate(plan, env, onOutput) {
         ? { ok: true, message: 'updated the sideby skill' }
         : { ok: false, message: `\`${plan.command}\` failed (exit ${r.code}); run it yourself to see why` };
 }
+/**
+ * Updates only the sideby skill, for a CLI that is already current (`sideby update`, the Panel, Auto Update). Holds
+ * the same lock as an Update, so a skill update never runs beside one; null when there was nothing to do.
+ */
+export async function applySkillOnly(paths, plan, env, onOutput) {
+    if (!plan?.outdated || !plan.canRun)
+        return null;
+    const release = await takeLock(paths, 'update-install.lock').catch(() => null);
+    if (!release)
+        return {
+            ok: false,
+            busy: true,
+            message: 'another sideby update is running; wait for it to finish, then run `sideby update` again',
+        };
+    try {
+        return await applySkillUpdate(plan, env, onOutput);
+    }
+    finally {
+        await release().catch(() => { });
+    }
+}
 /**
  * Runs the Update the plan names, then starts a running background Panel again from the new code and, when the
  * desktop app is installed, runs `sideby app install` again from the new code. The caller has
@@ -703,6 +790,22 @@ export async function autoUpdateBlocker(paths, plan) {
         return `a session is running (pid ${running.join(', ')})`;
     return null;
 }
+/**
+ * The skill half of Auto Update (spec §3.23): with the CLI current, a skill behind it is updated alone and the result
+ * recorded once per version, so a failure waits a day.
+ */
+async function skillAutoSync(paths, env, config, cache, current, now) {
+    const plan = await skillUpdatePlan(paths.home, current).catch(() => null);
+    if (!skillAutoPending(cache, current, config, skillBehind(plan, current), now))
+        return;
+    const r = await applySkillOnly(paths, plan ?? undefined, env);
+    // A manual Update holding the lock is not a failure; the next command looks again.
+    if (!r || r.busy)
+        return;
+    await updateUpdateCache(paths, {
+        skillAuto: { to: current, at: deps().now().toISOString(), ok: r.ok, message: r.message },
+    });
+}
 /**
  * Body of the detached `sideby update-check`: an Update Check when one is due, then an Auto Update when config
  * `update.auto` is on and nothing blocks it. Only one runs at a time; it never throws.
@@ -719,9 +822,16 @@ export async function backgroundCheck(paths, env, config, panelPort) {
         if (checkDue(cache, now))
             cache = await refreshUpdateCheck(paths, env);
         const current = packageVersion();
-        if (!autoPending(cache, current, config, now))
+        if (!autoPending(cache, current, config, now)) {
+            await skillAutoSync(paths, env, config, cache, current, now);
             return;
-        const plan = planFrom(await installMethod(env), current, cache.latest, env);
+        }
+        // The skill teaches agents the new version's commands, so an Auto Update carries it as `sideby update` does.
+        const skill = await skillUpdatePlan(paths.home, cache.latest).catch(() => null);
+        const plan = {
+            ...planFrom(await installMethod(env), current, cache.latest, env),
+            ...(skill ? { skill } : {}),
+        };
         await updateUpdateCache(paths, { autoTriedAt: now.toISOString() });
         // A blocker only the user can lift is said once and looked at again a day later, like a failed install; a
         // running session only delays it (the next look is within the hour).

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;

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

@@ -1,5 +1,5 @@
-// How Grok Build takes part in a Handoff (spec §3.17). It has no public Quota, so it starts one only after a turn
-// failed at the limit. Interactive `grok` has no launch option for hooks: `sideby handoff setup grok` adds
+// How Grok Build takes part in a Handoff (spec §3.17). Since its Quota comes from its own CLI (spec §3.26), it starts
+// one at the Handoff Threshold, and still after a turn failed at the limit. Interactive `grok` has no launch option for hooks: `sideby handoff setup grok` adds
 // `hooks/sideby-handoff.json` to the Main Account and Doctor copies it to the others (verified 2026-10-09).
 // The hook inherits Grok's sandbox, so the profile decides whether a run may start or receive.
 import { mkdir, readFile, rm, rmdir } from 'node:fs/promises';
@@ -124,10 +124,22 @@ export function grokEligibility(policy, args, home) {
     };
 }
 const hookCommand = (event) => `sideby handoff-hook grok ${event}`;
-/** 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 const GROK_HOOK_FILE_V1 = `${JSON.stringify({
+    hooks: {
+        Stop: [{ hooks: [{ type: 'command', command: hookCommand('Stop') }] }],
+        StopFailure: [{ hooks: [{ type: 'command', command: hookCommand('StopFailure'), timeout: 60 }] }],
+    },
+}, null, 2)}\n`;
+/** The whole file setup writes; teardown removes it only while it is still exactly this (or `GROK_HOOK_FILE_V1`). */
 export function grokHookFileText() {
     const hooks = {
         hooks: {
+            // Quota Pressure after each tool call, to prepare and start a Handoff before the limit (spec §3.26).
+            PostToolUse: [{ hooks: [{ type: 'command', command: hookCommand('PostToolUse') }] }],
             Stop: [{ hooks: [{ type: 'command', command: hookCommand('Stop') }] }],
             // Observation hooks get 5 seconds by default; putting a Brief together may take longer.
             StopFailure: [{ hooks: [{ type: 'command', command: hookCommand('StopFailure'), timeout: 60 }] }],
@@ -143,7 +155,8 @@ async function plan(ctx) {
     const have = await textOrNull(file);
     if (have === want)
         return { status: 'enabled', file, diff: '', message: `already set up in ${shown}` };
-    if (have !== null)
+    const upgrade = have === GROK_HOOK_FILE_V1;
+    if (have !== null && !upgrade)
         return {
             status: 'blocked',
             file,
@@ -153,19 +166,22 @@ async function plan(ctx) {
     const problem = await sidebyBinProblem(ctx.env, 'Grok runs `sideby handoff-hook` when a turn ends');
     if (problem)
         return { status: 'blocked', file, diff: '', message: problem };
+    const lines = (text, mark) => text
+        .trimEnd()
+        .split('\n')
+        .map((l) => `${mark}${l}`)
+        .join('\n');
     return {
         status: 'ready',
         file,
-        diff: `--- /dev/null\n+++ ${shown}\n${want
-            .trimEnd()
-            .split('\n')
-            .map((l) => `+${l}`)
-            .join('\n')}\n`,
-        message: `adds ${shown} so Grok tells sideby when a turn hits the usage limit; then run \`sideby doctor grok --fix\` to copy it to every Grok account; undo with \`sideby handoff teardown grok\``,
+        diff: upgrade
+            ? `--- ${shown}\n+++ ${shown}\n${lines(have, '-')}\n${lines(want, '+')}\n`
+            : `--- /dev/null\n+++ ${shown}\n${lines(want, '+')}\n`,
+        message: `${upgrade ? 'updates' : 'adds'} ${shown} so Grok tells sideby how full its quota is after each tool call and when a turn hits the usage limit; then run \`sideby doctor grok --fix\` to copy it to every Grok account; undo with \`sideby handoff teardown grok\``,
     };
 }
 export const grokHookSetup = {
-    summary: 'Adds one sideby hook file to ~/.grok/hooks so a Grok session that hits its usage limit can hand over.',
+    summary: 'Adds one sideby hook file to ~/.grok/hooks so a Grok session can hand over when its quota runs low or hits the limit.',
     plan,
     async apply(ctx) {
         const p = await plan(ctx);
@@ -175,13 +191,14 @@ export const grokHookSetup = {
         await writeFileAtomic(p.file, grokHookFileText(), 0o644);
         return { ...p, status: 'enabled' };
     },
+    earlierTexts: [GROK_HOOK_FILE_V1],
     async teardown(ctx) {
         const file = hookFile(ctx);
         const shown = tildify(file, ctx.home);
         const have = await textOrNull(file);
         if (have === null)
             return { ok: true, message: `${shown} is not there; nothing to undo` };
-        if (sha256(have) !== sha256(grokHookFileText()))
+        if (sha256(have) !== sha256(grokHookFileText()) && have !== GROK_HOOK_FILE_V1)
             return {
                 ok: false,
                 message: `${shown} changed since setup; delete it yourself if you no longer want it`,
@@ -196,7 +213,7 @@ export const grokHookSetup = {
     },
 };
 export const grokHandoff = {
-    starts: ['limit'],
+    starts: ['quota', 'limit'],
     promptArgs: promptAfterDashes,
     continueArgs: (args) => carryArgs(args, GROK_ARGS),
     resumeArgs: (id) => ['--resume', id],

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

@@ -5,6 +5,8 @@ import { BUILTIN_LOGOS } from '../logos.js';
 import { groupedEntryWrittenAt, resumeFlagSession } from '../shared/sessions.js';
 import { topLevelTomlString } from '../shared/toml.js';
 import { grokHandoff } from './handoff.js';
+import { grokQuotaFetch } from './quota.js';
+import { readGrokLogQuota } from './quota-log.js';
 // Grok's sandbox rejects these paths when they are symlinks; doctor quotes the Host's own words.
 const HOOKS_DIR_MESSAGE = 'Grok hooks directory has wrong type (expected real directory)';
 const REAL_FILE_MESSAGE = 'Grok hooks-paths registry has wrong type (expected real file)';
@@ -71,6 +73,9 @@ export const grokFamily = {
     },
     model: readModel,
     identity: grokIdentity,
+    // Quota (spec §3.26, ADR-0025): Grok's own billing lines in its log, and its CLI asked at most every 15 minutes.
+    readQuota: (account) => readGrokLogQuota(account.dir),
+    fetchQuota: grokQuotaFetch,
     resumedSession: resumeFlagSession,
     handoff: grokHandoff,
     // One directory per session, grouped by working directory: sessions/<encoded cwd>/<id>/.

package/dist/src/families/grok/quota-log.d.ts

@@ -0,0 +1,30 @@
+import { FileMemo } from '../../core/file-memo.ts';
+import type { QuotaResult, QuotaWindow } from '../../types.ts';
+export type GrokQuota = Extract<QuotaResult, {
+    status: 'ok';
+}>;
+export declare const GROK_BILLING_MSG = "billing: fetched credits config";
+/** How far back the CLI and the Panel look (Grok halves the file at 5 MB) and how far the handoff hook does. */
+export declare const LOG_READ_BYTES: number;
+export declare const HOOK_LOG_READ_BYTES: number;
+export declare function grokLogFile(accountDir: string): string;
+/**
+ * A Quota reading from Grok's billing answer: `{ config, subscription_tier }` from `_x.ai/billing`, or the log line's
+ * `ctx` (`{ config, subscriptionTier }`). Null when it holds no usable window.
+ */
+export declare function grokQuota(answer: unknown, observedAt: string, source: string): GrokQuota | null;
+/** The newest billing line in the last `maxBytes` of `file`, read backwards a chunk at a time; null when none. */
+export declare function lastGrokBilling(file: string, maxBytes: number, source?: string): Promise<GrokQuota | null>;
+/** The log's reading per Account directory; the file is read again only after it changed. */
+export declare const grokQuotaMemo: FileMemo<{
+    status: 'ok';
+    windows: QuotaWindow[];
+    observedAt: string;
+    source: string;
+    plan?: string;
+    from?: string;
+    fetched?: boolean;
+    fetchError?: string;
+} | null>;
+/** Grok's local Quota for one Account directory: its newest billing line. */
+export declare function readGrokLogQuota(accountDir: string): Promise<QuotaResult>;