@agentrhq/webcmd 0.1.1 → 0.2.0

package/dist/src/commands/auth.js

@@ -0,0 +1,434 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { InvalidArgumentError, Option } from 'commander';
+import { AuthRequiredError, CliError, getErrorMessage } from '../errors.js';
+import { executeCommand } from '../execution.js';
+import { fullName, getRegistry, } from '../registry.js';
+import { render as renderOutput } from '../output.js';
+const AUTH_REFRESH_STATE_VERSION = 1;
+const AUTH_REFRESH_INTERVAL_MS = 24 * 60 * 60 * 1000;
+function parsePositiveInt(raw, label, fallback) {
+    if (raw === undefined || raw === null || raw === '')
+        return fallback;
+    const parsed = Number(raw);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new InvalidArgumentError(`${label} must be a positive integer. Received: "${String(raw)}"`);
+    }
+    return parsed;
+}
+function parseSiteFilter(raw) {
+    if (!raw || !raw.trim())
+        return null;
+    const sites = raw.split(',').map(site => site.trim()).filter(Boolean);
+    return sites.length > 0 ? new Set(sites) : null;
+}
+function defaultAuthRefreshStatePath() {
+    return join(homedir(), '.webcmd', 'auth-refresh.json');
+}
+function emptyAuthRefreshState() {
+    return { version: AUTH_REFRESH_STATE_VERSION, sites: {} };
+}
+async function loadAuthRefreshState(statePath) {
+    try {
+        const parsed = JSON.parse(await readFile(statePath, 'utf8'));
+        if (parsed && parsed.version === AUTH_REFRESH_STATE_VERSION && parsed.sites && typeof parsed.sites === 'object') {
+            return { version: AUTH_REFRESH_STATE_VERSION, sites: parsed.sites };
+        }
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    return emptyAuthRefreshState();
+}
+async function saveAuthRefreshState(statePath, state) {
+    await mkdir(dirname(statePath), { recursive: true });
+    await writeFile(statePath, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+}
+function lastTouchedMs(entry) {
+    if (!entry?.last_touched_at)
+        return null;
+    const parsed = Date.parse(entry.last_touched_at);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function isRefreshThrottled(entry, now) {
+    const touched = lastTouchedMs(entry);
+    return touched !== null && now.getTime() - touched < AUTH_REFRESH_INTERVAL_MS;
+}
+function nextRefreshAt(entry) {
+    const touched = lastTouchedMs(entry);
+    return touched === null ? '' : new Date(touched + AUTH_REFRESH_INTERVAL_MS).toISOString();
+}
+function authWhoamiCommands() {
+    const seen = new Set();
+    return [...getRegistry().values()]
+        .filter((cmd) => {
+        if (seen.has(cmd))
+            return false;
+        seen.add(cmd);
+        return cmd.name === 'whoami' && cmd.browser === true && cmd.access === 'read';
+    })
+        .sort((a, b) => a.site.localeCompare(b.site));
+}
+async function loadLazyCommand(cmd) {
+    const internal = cmd;
+    if (!internal._lazy || !internal._modulePath)
+        return cmd;
+    await import(pathToFileURL(internal._modulePath).href);
+    return getRegistry().get(fullName(cmd)) ?? cmd;
+}
+function withTimeoutArg(cmd, timeoutSeconds) {
+    const hasTimeout = cmd.args.some(arg => arg.name === 'timeout');
+    return {
+        ...cmd,
+        args: hasTimeout
+            ? cmd.args
+            : [...cmd.args, { name: 'timeout', type: 'int', default: timeoutSeconds, help: 'Per-site auth command timeout in seconds' }],
+    };
+}
+function quickCheckCommand(cmd, timeoutSeconds) {
+    if (cmd.browser !== true || typeof cmd.authStatus?.quickCheck !== 'function')
+        return null;
+    return withTimeoutArg({
+        ...cmd,
+        func: cmd.authStatus.quickCheck,
+        navigateBefore: false,
+        siteSession: 'ephemeral',
+        defaultWindowMode: 'background',
+    }, timeoutSeconds);
+}
+function normalizeQuickResult(result) {
+    if (typeof result === 'boolean')
+        return result;
+    if (result && typeof result === 'object' && !Array.isArray(result)) {
+        const value = result.logged_in;
+        if (typeof value === 'boolean')
+            return value;
+    }
+    return null;
+}
+function safeIdentityValue(value) {
+    if (value === undefined || value === null)
+        return '';
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    return '';
+}
+function identitySummary(result) {
+    if (!result || typeof result !== 'object' || Array.isArray(result))
+        return '';
+    const row = result;
+    const blocked = /(?:email|phone|real.?name|first.?name|last.?name|cookie|token|session|secret|password|csrf|jwt|bearer|wt2)/i;
+    for (const key of ['username', 'handle', 'user_id', 'id', 'name', 'nickname', 'user_type', 'url']) {
+        if (blocked.test(key))
+            continue;
+        const value = safeIdentityValue(row[key]);
+        if (value)
+            return value;
+    }
+    for (const [key, raw] of Object.entries(row)) {
+        if (key === 'site' || key === 'logged_in' || blocked.test(key))
+            continue;
+        const value = safeIdentityValue(raw);
+        if (value)
+            return value;
+    }
+    return '';
+}
+function rowForError(site, checked, error) {
+    if (error instanceof AuthRequiredError) {
+        return { site, status: 'not_logged_in', logged_in: false, identity: '', checked, error: '' };
+    }
+    const code = error instanceof CliError ? error.code : '';
+    const message = getErrorMessage(error);
+    return {
+        site,
+        status: 'error',
+        logged_in: '',
+        identity: '',
+        checked,
+        error: code ? `${code}: ${message}` : message,
+    };
+}
+function refreshCommand(cmd, timeoutSeconds) {
+    if (cmd.browser !== true)
+        return null;
+    let refreshFunc = cmd.authStatus?.refresh;
+    if (typeof refreshFunc !== 'function') {
+        const quickCheck = cmd.authStatus?.quickCheck;
+        if (typeof quickCheck !== 'function' || !cmd.domain)
+            return null;
+        const refreshUrl = cmd.domain.startsWith('http://') || cmd.domain.startsWith('https://')
+            ? cmd.domain
+            : `https://${cmd.domain}`;
+        refreshFunc = async (page, kwargs, debug) => {
+            await page.goto(refreshUrl);
+            await page.wait(1);
+            const loggedIn = normalizeQuickResult(await quickCheck(page, kwargs, debug));
+            if (loggedIn !== true) {
+                throw new AuthRequiredError(cmd.domain ?? cmd.site, `Auth refresh quickCheck failed for ${cmd.site}`);
+            }
+            return { status: 'touched' };
+        };
+    }
+    return withTimeoutArg({
+        ...cmd,
+        func: refreshFunc,
+        navigateBefore: false,
+        siteSession: 'persistent',
+        defaultWindowMode: 'background',
+    }, timeoutSeconds);
+}
+function normalizeRefreshStatus(result) {
+    if (result && typeof result === 'object' && !Array.isArray(result)) {
+        const row = result;
+        if (row.status === 'refreshed' || row.refreshed === true)
+            return 'refreshed';
+    }
+    return 'touched';
+}
+function refreshRowForError(site, entry, error) {
+    if (error instanceof AuthRequiredError) {
+        return {
+            site,
+            status: 'not_logged_in',
+            last_touched_at: entry?.last_touched_at ?? '',
+            next_refresh_at: nextRefreshAt(entry),
+            error: '',
+        };
+    }
+    const code = error instanceof CliError ? error.code : '';
+    const message = getErrorMessage(error);
+    return {
+        site,
+        status: 'error',
+        last_touched_at: entry?.last_touched_at ?? '',
+        next_refresh_at: nextRefreshAt(entry),
+        error: code ? `${code}: ${message}` : message,
+    };
+}
+async function runQuick(cmd, opts) {
+    const loaded = await loadLazyCommand(cmd);
+    const quickCmd = quickCheckCommand(loaded, opts.timeoutSeconds);
+    if (!quickCmd) {
+        return {
+            site: cmd.site,
+            status: 'unknown',
+            logged_in: '',
+            identity: '',
+            checked: 'skipped',
+            error: 'quickCheck not implemented; use --full to run whoami',
+        };
+    }
+    try {
+        const result = await executeCommand(quickCmd, { timeout: opts.timeoutSeconds }, false, {
+            siteSession: 'ephemeral',
+            keepTab: 'false',
+            windowMode: 'background',
+            ...(opts.profile ? { profile: opts.profile } : {}),
+        });
+        const loggedIn = normalizeQuickResult(result);
+        if (loggedIn === true) {
+            return { site: cmd.site, status: 'logged_in', logged_in: true, identity: '', checked: 'quick', error: '' };
+        }
+        if (loggedIn === false) {
+            return { site: cmd.site, status: 'not_logged_in', logged_in: false, identity: '', checked: 'quick', error: '' };
+        }
+        return {
+            site: cmd.site,
+            status: 'unknown',
+            logged_in: '',
+            identity: '',
+            checked: 'quick',
+            error: 'quickCheck returned no boolean logged_in signal',
+        };
+    }
+    catch (error) {
+        return rowForError(cmd.site, 'quick', error);
+    }
+}
+async function runFull(cmd, opts) {
+    const loaded = await loadLazyCommand(cmd);
+    const fullCmd = withTimeoutArg(loaded, opts.timeoutSeconds);
+    try {
+        const result = await executeCommand(fullCmd, { timeout: opts.timeoutSeconds }, false, {
+            siteSession: 'ephemeral',
+            keepTab: 'false',
+            windowMode: 'background',
+            ...(opts.profile ? { profile: opts.profile } : {}),
+        });
+        return {
+            site: cmd.site,
+            status: 'logged_in',
+            logged_in: true,
+            identity: identitySummary(result),
+            checked: 'full',
+            error: '',
+        };
+    }
+    catch (error) {
+        return rowForError(cmd.site, 'full', error);
+    }
+}
+async function runRefresh(cmd, opts) {
+    const existing = opts.state.sites[cmd.site];
+    if (!opts.force && isRefreshThrottled(existing, opts.now)) {
+        return {
+            site: cmd.site,
+            status: 'skipped',
+            last_touched_at: existing?.last_touched_at ?? '',
+            next_refresh_at: nextRefreshAt(existing),
+            error: '',
+        };
+    }
+    const attemptAt = opts.now.toISOString();
+    const loaded = await loadLazyCommand(cmd);
+    const refreshCmd = refreshCommand(loaded, opts.timeoutSeconds);
+    if (!refreshCmd) {
+        opts.state.sites[cmd.site] = { ...existing, last_attempt_at: attemptAt, last_status: 'unsupported' };
+        return {
+            site: cmd.site,
+            status: 'unsupported',
+            last_touched_at: existing?.last_touched_at ?? '',
+            next_refresh_at: nextRefreshAt(existing),
+            error: 'refresh probe is not available for this site',
+        };
+    }
+    try {
+        const result = await executeCommand(refreshCmd, { timeout: opts.timeoutSeconds }, false, {
+            siteSession: 'persistent',
+            keepTab: 'true',
+            windowMode: 'background',
+            ...(opts.profile ? { profile: opts.profile } : {}),
+        });
+        const status = normalizeRefreshStatus(result);
+        opts.state.sites[cmd.site] = {
+            ...existing,
+            last_attempt_at: attemptAt,
+            last_touched_at: attemptAt,
+            last_status: status,
+        };
+        return {
+            site: cmd.site,
+            status,
+            last_touched_at: attemptAt,
+            next_refresh_at: new Date(opts.now.getTime() + AUTH_REFRESH_INTERVAL_MS).toISOString(),
+            error: '',
+        };
+    }
+    catch (error) {
+        const status = error instanceof AuthRequiredError ? 'not_logged_in' : 'error';
+        opts.state.sites[cmd.site] = { ...existing, last_attempt_at: attemptAt, last_status: status };
+        return refreshRowForError(cmd.site, existing, error);
+    }
+}
+async function mapConcurrent(items, concurrency, worker) {
+    const results = new Array(items.length);
+    let next = 0;
+    const runners = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
+        while (next < items.length) {
+            const index = next++;
+            results[index] = await worker(items[index]);
+        }
+    });
+    await Promise.all(runners);
+    return results;
+}
+export async function collectAuthStatus(options) {
+    const selectedSites = parseSiteFilter(options.sites);
+    const mode = options.full ? 'full' : 'quick';
+    const concurrency = parsePositiveInt(options.concurrency, '--concurrency', mode === 'full' ? 3 : 8);
+    const timeoutSeconds = parsePositiveInt(options.timeout, '--timeout', mode === 'full' ? 20 : 8);
+    const only = String(options.only ?? 'all');
+    if (!['all', 'logged-in', 'not-logged-in', 'unknown', 'error'].includes(only)) {
+        throw new InvalidArgumentError('--only must be one of: all, logged-in, not-logged-in, unknown, error');
+    }
+    const commands = authWhoamiCommands().filter(cmd => !selectedSites || selectedSites.has(cmd.site));
+    const rows = await mapConcurrent(commands, concurrency, cmd => (mode === 'full'
+        ? runFull(cmd, { timeoutSeconds, profile: options.profile })
+        : runQuick(cmd, { timeoutSeconds, profile: options.profile })));
+    const normalizedOnly = only.replace(/-/g, '_');
+    return normalizedOnly === 'all'
+        ? rows
+        : rows.filter(row => row.status === normalizedOnly);
+}
+export async function collectAuthRefresh(options) {
+    const selectedSites = parseSiteFilter(options.sites);
+    const concurrency = parsePositiveInt(options.concurrency, '--concurrency', 3);
+    const timeoutSeconds = parsePositiveInt(options.timeout, '--timeout', 20);
+    const statePath = options.statePath ?? defaultAuthRefreshStatePath();
+    const now = options.now ?? new Date();
+    const state = await loadAuthRefreshState(statePath);
+    const commands = authWhoamiCommands().filter(cmd => !selectedSites || selectedSites.has(cmd.site));
+    const rows = await mapConcurrent(commands, concurrency, cmd => runRefresh(cmd, {
+        timeoutSeconds,
+        profile: options.profile,
+        now,
+        state,
+        force: options.all === true,
+    }));
+    await saveAuthRefreshState(statePath, state);
+    return rows;
+}
+export function registerAuthCommands(program) {
+    const auth = program
+        .command('auth')
+        .description('Inspect website login status');
+    const status = auth
+        .command('status')
+        .description('Show login status for sites with auth adapters')
+        .option('--site <sites>', 'Comma-separated site names to check, e.g. github,chatgpt')
+        .option('--full', 'Run full per-site whoami probes instead of quick no-navigation checks', false)
+        .option('--concurrency <n>', 'Maximum sites to check at once')
+        .option('--timeout <seconds>', 'Per-site timeout in seconds')
+        .addOption(new Option('--only <status>', 'Filter rows by status').choices(['all', 'logged-in', 'not-logged-in', 'unknown', 'error']).default('all'))
+        .option('-f, --format <fmt>', 'Output format: table, plain, json, yaml, md, csv', 'table')
+        .action(async (opts) => {
+        const globals = typeof status.optsWithGlobals === 'function' ? status.optsWithGlobals() : {};
+        const rows = await collectAuthStatus({
+            sites: opts.site,
+            full: opts.full === true,
+            concurrency: opts.concurrency,
+            timeout: opts.timeout,
+            only: opts.only,
+            profile: typeof globals.profile === 'string' && globals.profile.trim() ? globals.profile.trim() : undefined,
+        });
+        const fmt = typeof opts.format === 'string' ? opts.format : 'table';
+        renderOutput(rows, {
+            fmt,
+            fmtExplicit: status.getOptionValueSource('format') === 'cli',
+            columns: ['site', 'status', 'identity', 'checked', 'error'],
+            title: 'webcmd/auth status',
+            source: opts.full ? 'full whoami probe' : 'quick auth check',
+        });
+    });
+    const refresh = auth
+        .command('refresh')
+        .description('Touch logged-in site sessions to keep browser auth fresh')
+        .option('--site <sites>', 'Comma-separated site names to refresh, e.g. github,claude')
+        .option('--all', 'Ignore the 24h refresh throttle and force every selected site', false)
+        .option('--concurrency <n>', 'Maximum sites to refresh at once')
+        .option('--timeout <seconds>', 'Per-site timeout in seconds')
+        .option('-f, --format <fmt>', 'Output format: table, plain, json, yaml, md, csv', 'table')
+        .action(async (opts) => {
+        const globals = typeof refresh.optsWithGlobals === 'function' ? refresh.optsWithGlobals() : {};
+        const rows = await collectAuthRefresh({
+            sites: opts.site,
+            all: opts.all === true,
+            concurrency: opts.concurrency,
+            timeout: opts.timeout,
+            profile: typeof globals.profile === 'string' && globals.profile.trim() ? globals.profile.trim() : undefined,
+        });
+        const fmt = typeof opts.format === 'string' ? opts.format : 'table';
+        renderOutput(rows, {
+            fmt,
+            fmtExplicit: refresh.getOptionValueSource('format') === 'cli',
+            columns: ['site', 'status', 'last_touched_at', 'next_refresh_at', 'error'],
+            title: 'webcmd/auth refresh',
+            source: opts.all ? 'forced persistent touch' : 'persistent touch with 24h throttle',
+        });
+    });
+    return auth;
+}

package/dist/src/commands/auth.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/commands/auth.test.js

@@ -0,0 +1,252 @@
+import { mkdtemp, readFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+const executeCommandMock = vi.hoisted(() => vi.fn());
+vi.mock('../execution.js', () => ({
+    executeCommand: executeCommandMock,
+}));
+import { collectAuthRefresh, collectAuthStatus } from './auth.js';
+import { AuthRequiredError } from '../errors.js';
+import { cli, getRegistry, Strategy } from '../registry.js';
+function registerWhoami(site, opts = {}) {
+    cli({
+        site,
+        name: 'whoami',
+        access: 'read',
+        description: `${site} whoami`,
+        strategy: Strategy.COOKIE,
+        browser: true,
+        domain: `${site}.example.com`,
+        navigateBefore: false,
+        args: [],
+        columns: ['logged_in', 'site', 'username'],
+        authStatus: {
+            ...(opts.quick ? { quickCheck: async () => ({ logged_in: opts.quickLoggedIn ?? false }) } : {}),
+            ...(opts.refresh ? { refresh: async () => ({ status: opts.refresh }) } : {}),
+        },
+        func: async () => opts.identity ?? { logged_in: true, site, username: site },
+    });
+}
+async function tempStatePath() {
+    const dir = await mkdtemp(join(tmpdir(), 'webcmd-auth-refresh-test-'));
+    return join(dir, 'auth-refresh.json');
+}
+beforeEach(() => {
+    getRegistry().clear();
+    executeCommandMock.mockReset();
+    executeCommandMock.mockImplementation(async (cmd, kwargs) => {
+        if (!cmd.func)
+            return {};
+        return cmd.func({ goto: vi.fn(), wait: vi.fn() }, kwargs);
+    });
+});
+describe('auth status collection', () => {
+    it('uses quickCheck by default and does not run full whoami', async () => {
+        registerWhoami('alpha', { quick: true, quickLoggedIn: true, identity: { username: 'full-alpha' } });
+        const rows = await collectAuthStatus({ sites: 'alpha' });
+        expect(rows).toEqual([
+            { site: 'alpha', status: 'logged_in', logged_in: true, identity: '', checked: 'quick', error: '' },
+        ]);
+        expect(executeCommandMock).toHaveBeenCalledTimes(1);
+        expect(executeCommandMock.mock.calls[0]?.[0]).toMatchObject({
+            site: 'alpha',
+            name: 'whoami',
+            navigateBefore: false,
+            siteSession: 'ephemeral',
+            defaultWindowMode: 'background',
+        });
+    });
+    it('marks sites without quickCheck as unknown unless --full is used', async () => {
+        registerWhoami('beta');
+        const rows = await collectAuthStatus({ sites: 'beta' });
+        expect(rows).toEqual([
+            {
+                site: 'beta',
+                status: 'unknown',
+                logged_in: '',
+                identity: '',
+                checked: 'skipped',
+                error: 'quickCheck not implemented; use --full to run whoami',
+            },
+        ]);
+        expect(executeCommandMock).not.toHaveBeenCalled();
+    });
+    it('runs full whoami with --full and returns a safe identity summary', async () => {
+        registerWhoami('gamma', {
+            identity: {
+                logged_in: true,
+                site: 'gamma',
+                email: 'hidden@example.com',
+                username: 'public-handle',
+            },
+        });
+        const rows = await collectAuthStatus({ sites: 'gamma', full: true });
+        expect(rows).toEqual([
+            { site: 'gamma', status: 'logged_in', logged_in: true, identity: 'public-handle', checked: 'full', error: '' },
+        ]);
+    });
+    it('converts AuthRequiredError into not_logged_in rows', async () => {
+        registerWhoami('delta', { quick: true });
+        executeCommandMock.mockRejectedValueOnce(new AuthRequiredError('delta.example.com'));
+        const rows = await collectAuthStatus({ sites: 'delta' });
+        expect(rows).toEqual([
+            { site: 'delta', status: 'not_logged_in', logged_in: false, identity: '', checked: 'quick', error: '' },
+        ]);
+    });
+});
+describe('auth refresh collection', () => {
+    it('touches sites through persistent sessions and writes last_touched_at on success', async () => {
+        registerWhoami('alpha', { quick: true, quickLoggedIn: true });
+        const statePath = await tempStatePath();
+        const now = new Date('2026-06-06T12:00:00.000Z');
+        const rows = await collectAuthRefresh({ sites: 'alpha', statePath, now });
+        expect(rows).toEqual([
+            {
+                site: 'alpha',
+                status: 'touched',
+                last_touched_at: now.toISOString(),
+                next_refresh_at: '2026-06-07T12:00:00.000Z',
+                error: '',
+            },
+        ]);
+        expect(executeCommandMock).toHaveBeenCalledTimes(1);
+        expect(executeCommandMock.mock.calls[0]?.[0]).toMatchObject({
+            site: 'alpha',
+            name: 'whoami',
+            navigateBefore: false,
+            siteSession: 'persistent',
+            defaultWindowMode: 'background',
+        });
+        expect(executeCommandMock.mock.calls[0]?.[3]).toMatchObject({
+            siteSession: 'persistent',
+            keepTab: 'true',
+            windowMode: 'background',
+        });
+        const state = JSON.parse(await readFile(statePath, 'utf8'));
+        expect(state.sites.alpha).toMatchObject({
+            last_touched_at: now.toISOString(),
+            last_attempt_at: now.toISOString(),
+            last_status: 'touched',
+        });
+    });
+    it('uses adapter refresh hooks when present and records refreshed', async () => {
+        registerWhoami('beta', { refresh: 'refreshed' });
+        const statePath = await tempStatePath();
+        const rows = await collectAuthRefresh({
+            sites: 'beta',
+            statePath,
+            now: new Date('2026-06-06T12:00:00.000Z'),
+        });
+        expect(rows[0]?.status).toBe('refreshed');
+        expect(executeCommandMock).toHaveBeenCalledTimes(1);
+    });
+    it('skips sites touched within the hidden 24h throttle', async () => {
+        registerWhoami('gamma', { quick: true, quickLoggedIn: true });
+        const statePath = await tempStatePath();
+        await collectAuthRefresh({
+            sites: 'gamma',
+            statePath,
+            now: new Date('2026-06-06T12:00:00.000Z'),
+        });
+        executeCommandMock.mockClear();
+        const rows = await collectAuthRefresh({
+            sites: 'gamma',
+            statePath,
+            now: new Date('2026-06-07T11:59:00.000Z'),
+        });
+        expect(rows).toEqual([
+            {
+                site: 'gamma',
+                status: 'skipped',
+                last_touched_at: '2026-06-06T12:00:00.000Z',
+                next_refresh_at: '2026-06-07T12:00:00.000Z',
+                error: '',
+            },
+        ]);
+        expect(executeCommandMock).not.toHaveBeenCalled();
+    });
+    it('lets --all bypass the 24h throttle', async () => {
+        registerWhoami('delta', { quick: true, quickLoggedIn: true });
+        const statePath = await tempStatePath();
+        await collectAuthRefresh({
+            sites: 'delta',
+            statePath,
+            now: new Date('2026-06-06T12:00:00.000Z'),
+        });
+        executeCommandMock.mockClear();
+        const rows = await collectAuthRefresh({
+            sites: 'delta',
+            all: true,
+            statePath,
+            now: new Date('2026-06-07T11:59:00.000Z'),
+        });
+        expect(rows[0]?.status).toBe('touched');
+        expect(rows[0]?.last_touched_at).toBe('2026-06-07T11:59:00.000Z');
+        expect(executeCommandMock).toHaveBeenCalledTimes(1);
+    });
+    it('does not throttle not_logged_in results', async () => {
+        registerWhoami('epsilon', { quick: true, quickLoggedIn: true });
+        const statePath = await tempStatePath();
+        executeCommandMock.mockRejectedValueOnce(new AuthRequiredError('epsilon.example.com'));
+        const rows = await collectAuthRefresh({
+            sites: 'epsilon',
+            statePath,
+            now: new Date('2026-06-06T12:00:00.000Z'),
+        });
+        expect(rows).toEqual([
+            { site: 'epsilon', status: 'not_logged_in', last_touched_at: '', next_refresh_at: '', error: '' },
+        ]);
+        const state = JSON.parse(await readFile(statePath, 'utf8'));
+        expect(state.sites.epsilon).toMatchObject({
+            last_attempt_at: '2026-06-06T12:00:00.000Z',
+            last_status: 'not_logged_in',
+        });
+        expect(state.sites.epsilon.last_touched_at).toBeUndefined();
+        executeCommandMock.mockClear();
+        await collectAuthRefresh({
+            sites: 'epsilon',
+            statePath,
+            now: new Date('2026-06-06T12:01:00.000Z'),
+        });
+        expect(executeCommandMock).toHaveBeenCalledTimes(1);
+    });
+    it('does not update last_touched_at for generic errors', async () => {
+        registerWhoami('zeta', { quick: true, quickLoggedIn: true });
+        const statePath = await tempStatePath();
+        executeCommandMock.mockRejectedValueOnce(new Error('network down'));
+        const rows = await collectAuthRefresh({
+            sites: 'zeta',
+            statePath,
+            now: new Date('2026-06-06T12:00:00.000Z'),
+        });
+        expect(rows).toEqual([
+            { site: 'zeta', status: 'error', last_touched_at: '', next_refresh_at: '', error: 'network down' },
+        ]);
+        const state = JSON.parse(await readFile(statePath, 'utf8'));
+        expect(state.sites.zeta).toMatchObject({
+            last_attempt_at: '2026-06-06T12:00:00.000Z',
+            last_status: 'error',
+        });
+        expect(state.sites.zeta.last_touched_at).toBeUndefined();
+    });
+    it('marks sites without quickCheck or refresh hook as unsupported instead of running DOM whoami fallback', async () => {
+        registerWhoami('eta');
+        const statePath = await tempStatePath();
+        const rows = await collectAuthRefresh({
+            sites: 'eta',
+            statePath,
+            now: new Date('2026-06-06T12:00:00.000Z'),
+        });
+        expect(rows).toEqual([
+            {
+                site: 'eta',
+                status: 'unsupported',
+                last_touched_at: '',
+                next_refresh_at: '',
+                error: 'refresh probe is not available for this site',
+            },
+        ]);
+        expect(executeCommandMock).not.toHaveBeenCalled();
+    });
+});