@indigoai-us/hq-cli 5.345.91 → 5.345.93

package/dist/lib/capacity/project.d.ts

@@ -0,0 +1,12 @@
+import type { CapacityAccount } from "./accounts.js";
+import type { NowView } from "./ledger.js";
+export interface ProjectCapacityOptions {
+    accounts: readonly CapacityAccount[];
+    /**
+     * Ledger account id → hashed profile account id. Return null when the
+     * profile call did not run. Unknown identities never merge across homes.
+     */
+    identityKeyForAccount?: (accountId: string) => string | null;
+}
+export declare function projectCapacityView(view: NowView, options: ProjectCapacityOptions): NowView;
+//# sourceMappingURL=project.d.ts.map

package/dist/lib/capacity/project.js

@@ -0,0 +1,264 @@
+/**
+ * Present the capacity ledger against the accounts that exist right now.
+ *
+ * Readings keep the label they were collected under. A rename, or two labels
+ * for one home, must show up in `hq capacity` without waiting for the next
+ * provider poll and without rewriting the ledger. Claude blocks merge when
+ * they share a home, or when both have the same cached profile identity key.
+ * A missing key (the token was never read, or it was expired) never merges.
+ * Raw ids are never stored or returned.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+const STATE_RANK = {
+    ok: 0,
+    "reset-pending": 1,
+    warn: 2,
+    exhausted: 3,
+    unknown: 4,
+};
+export function projectCapacityView(view, options) {
+    const annotated = view.providers.some((provider) => (provider.accounts?.length ?? 0) > 0);
+    if (!annotated || options.accounts.length === 0)
+        return view;
+    const identityKeyForAccount = options.identityKeyForAccount ?? (() => null);
+    return {
+        ...view,
+        providers: view.providers.map((provider) => projectProvider(provider, options.accounts, identityKeyForAccount)),
+    };
+}
+function projectProvider(provider, accounts, identityKeyForAccount) {
+    if (!provider.accounts || provider.accounts.length === 0)
+        return provider;
+    const mine = accounts.filter((account) => account.provider === provider.provider);
+    if (mine.length === 0)
+        return provider;
+    const byHome = new Map();
+    const homeByLabel = new Map();
+    for (const account of mine) {
+        const home = canonicalHome(account.home);
+        const list = byHome.get(home) ?? [];
+        list.push(account);
+        byHome.set(home, list);
+        homeByLabel.set(account.label, home);
+    }
+    const pieces = [];
+    for (const account of provider.accounts) {
+        const homes = new Set();
+        const namedHomes = account.homes
+            .map((home) => canonicalHome(home))
+            .filter((home) => byHome.has(home));
+        if (namedHomes.length > 0) {
+            for (const home of namedHomes)
+                homes.add(home);
+        }
+        else if (account.homes.length === 0) {
+            for (const label of account.labels) {
+                const home = homeByLabel.get(label);
+                if (home)
+                    homes.add(home);
+            }
+        }
+        if (homes.size === 0)
+            continue;
+        pieces.push({ account, homes: [...homes] });
+    }
+    if (pieces.length === 0)
+        return withoutAccounts(provider);
+    const parent = pieces.map((_, index) => index);
+    const find = (index) => {
+        let cursor = index;
+        while (parent[cursor] !== cursor)
+            cursor = parent[cursor] ?? cursor;
+        return cursor;
+    };
+    const union = (left, right) => {
+        const a = find(left);
+        const b = find(right);
+        if (a !== b)
+            parent[b] = a;
+    };
+    const seenHome = new Map();
+    const seenIdentity = new Map();
+    pieces.forEach((piece, index) => {
+        for (const home of piece.homes) {
+            const previous = seenHome.get(home);
+            if (previous === undefined)
+                seenHome.set(home, index);
+            else
+                union(previous, index);
+        }
+        const identity = identityKeyForAccount(piece.account.accountId);
+        if (!identity)
+            return;
+        const previousIdentity = seenIdentity.get(identity);
+        if (previousIdentity === undefined)
+            seenIdentity.set(identity, index);
+        else
+            union(previousIdentity, index);
+    });
+    const groups = new Map();
+    pieces.forEach((piece, index) => {
+        const root = find(index);
+        const list = groups.get(root) ?? [];
+        list.push(piece);
+        groups.set(root, list);
+    });
+    const projected = [];
+    for (const group of groups.values()) {
+        const homes = [];
+        for (const piece of group) {
+            for (const home of piece.homes) {
+                if (!homes.includes(home))
+                    homes.push(home);
+            }
+        }
+        const labels = displayLabels(homes, byHome);
+        if (labels.length === 0)
+            continue;
+        projected.push(mergeGroup(group, homes, labels, provider.provider));
+    }
+    if (projected.length === 0)
+        return withoutAccounts(provider);
+    projected.sort((a, b) => (a.labels[0] ?? "").localeCompare(b.labels[0] ?? ""));
+    return recomputeFromAccounts(provider, projected);
+}
+function recomputeFromAccounts(provider, accounts) {
+    const limits = [];
+    for (const account of accounts) {
+        for (const limit of account.limits)
+            limits.push(limit);
+    }
+    let state = "ok";
+    if (limits.length === 0) {
+        state = accounts.some((account) => account.authState === "expired" || account.authState === "signed_out" || account.signedOut)
+            ? "unknown"
+            : "ok";
+    }
+    else {
+        for (const limit of limits) {
+            if (STATE_RANK[limit.state] > STATE_RANK[state])
+                state = limit.state;
+        }
+    }
+    return {
+        ...provider,
+        accounts,
+        limits,
+        state,
+        lastError: state === "unknown" ? accounts.find((account) => account.reason)?.reason ?? provider.lastError : null,
+    };
+}
+function withoutAccounts(provider) {
+    const next = { ...provider };
+    delete next.accounts;
+    return next;
+}
+/**
+ * `default` stands for the provider's own home. A registry account that uses
+ * that same home (lanes calls it `a`) is not a second account.
+ */
+function displayLabels(homes, byHome) {
+    const labels = [];
+    let defaultHome = null;
+    for (const home of homes) {
+        for (const account of byHome.get(home) ?? []) {
+            if (account.label === "default")
+                defaultHome = home;
+            if (!labels.includes(account.label))
+                labels.push(account.label);
+        }
+    }
+    const hidden = new Set();
+    if (defaultHome) {
+        for (const account of byHome.get(defaultHome) ?? []) {
+            if (account.label !== "default")
+                hidden.add(account.label);
+        }
+    }
+    const shown = labels.filter((label) => !hidden.has(label));
+    const rest = shown.filter((label) => label !== "default").sort((a, b) => a.localeCompare(b));
+    return shown.includes("default") ? ["default", ...rest] : rest;
+}
+function mergeGroup(group, homes, labels, provider) {
+    const ok = group.filter((piece) => piece.account.authState === "ok" && piece.account.limits.length > 0);
+    const limits = mergeLimits((ok.length > 0 ? ok : group).map((piece) => piece.account));
+    const observedAt = latestObserved(group.map((piece) => piece.account));
+    const organization = latestOrganization(group.map((piece) => piece.account));
+    const accountId = (ok[0] ?? group[0])?.account.accountId ?? labels[0] ?? provider;
+    if (ok.length > 0) {
+        let state = "ok";
+        for (const limit of limits) {
+            if (STATE_RANK[limit.state] > STATE_RANK[state])
+                state = limit.state;
+        }
+        return {
+            accountId,
+            labels,
+            organization,
+            homes,
+            state,
+            signedOut: false,
+            authState: "ok",
+            observedAt,
+            reason: null,
+            fixCommand: null,
+            limits,
+        };
+    }
+    const problem = [...group].sort((a, b) => (b.account.observedAt ?? "").localeCompare(a.account.observedAt ?? ""))[0]?.account;
+    const expired = problem?.authState === "expired";
+    const signedOut = problem?.authState === "signed_out" || problem?.signedOut === true;
+    return {
+        accountId,
+        labels,
+        organization,
+        homes,
+        state: "unknown",
+        signedOut,
+        authState: expired ? "expired" : signedOut ? "signed_out" : problem?.authState ?? "unknown",
+        observedAt,
+        reason: problem?.reason ?? null,
+        fixCommand: problem?.fixCommand ?? null,
+        limits,
+    };
+}
+function mergeLimits(accounts) {
+    const byId = new Map();
+    for (const account of accounts) {
+        for (const limit of account.limits) {
+            const previous = byId.get(limit.limitId);
+            if (!previous || limit.observedAt >= previous.observedAt)
+                byId.set(limit.limitId, limit);
+        }
+    }
+    return [...byId.values()].sort((a, b) => a.limitId.localeCompare(b.limitId));
+}
+function latestObserved(accounts) {
+    let latest = "";
+    for (const account of accounts) {
+        if (account.observedAt && account.observedAt > latest)
+            latest = account.observedAt;
+    }
+    return latest || null;
+}
+function latestOrganization(accounts) {
+    const ordered = [...accounts].sort((a, b) => (a.observedAt ?? "").localeCompare(b.observedAt ?? ""));
+    let organization = null;
+    for (const account of ordered) {
+        if (account.organization)
+            organization = account.organization;
+    }
+    return organization;
+}
+/** Same directory, including macOS `/var` → `/private/var`. Missing paths stay resolved. */
+function canonicalHome(home) {
+    const resolved = path.resolve(home);
+    try {
+        return fs.realpathSync(resolved);
+    }
+    catch {
+        return resolved;
+    }
+}
+//# sourceMappingURL=project.js.map

package/dist/lib/capacity/read.d.ts

@@ -0,0 +1,62 @@
+import { LedgerCorrupt, LedgerMissing, type LedgerOptions, type NowLimit, type NowProvider, type NowView } from "./ledger.js";
+export { LedgerCorrupt, LedgerMissing };
+/** Same window as `hq capacity`: generatedAt older than this is stale. */
+export declare const ADVISORY_STALE_MS: number;
+export interface AdvisoryNow extends NowView {
+    stale: boolean;
+    ageMs: number;
+}
+export interface AdvisoryProvider {
+    provider: string;
+    state: string;
+    weeklyUsedPercent: number | null;
+}
+export interface AdvisoryRecord {
+    at: string;
+    caller: string;
+    story: string | null;
+    chosenEngine: string;
+    naiveEngine: string | null;
+    agree: boolean;
+    providers: AdvisoryProvider[];
+}
+export interface DispatchAdvisoryInput {
+    chosenEngine: string;
+    caller: string;
+    story?: string | null;
+    env?: NodeJS.ProcessEnv;
+    stderr?: {
+        write: (chunk: string) => boolean | void;
+    };
+}
+/**
+ * The weekly_all row the advisory quotes. Lowest usedPercent when several exist.
+ * Pass accountId to prefer that account, falling back to the lowest across accounts.
+ */
+export declare function weeklyLimit(provider: NowProvider, accountId?: string): NowLimit | null;
+/** Caller's lane account when the home or label matches, else the lowest-used account. */
+export declare function preferredAccountId(provider: NowProvider, env?: NodeJS.ProcessEnv): string | undefined;
+export declare function weeklyUsedPercent(provider: NowProvider, env?: NodeJS.ProcessEnv): number | null;
+export declare function formatSpan(seconds: number | null): string;
+/**
+ * Read now.json. Throws LedgerMissing when the file is absent and
+ * LedgerCorrupt when it is not a view. `stale` and `ageMs` are about
+ * generatedAt, not about an individual limit.
+ */
+export declare function readNow(options?: LedgerOptions): AdvisoryNow;
+/**
+ * Provider with state ok and the lowest weekly_all usedPercent.
+ * Ties keep `chosenEngine` when it is one of the tied providers.
+ * Null when no ok provider has a weekly_all percent.
+ */
+export declare function naiveChoice(view: NowView, chosenEngine: string, env?: NodeJS.ProcessEnv): string | null;
+/** One stderr line. The chosen engine is first and carries reset and age. */
+export declare function formatAdvisory(view: NowView, chosenEngine: string, env?: NodeJS.ProcessEnv): string;
+export declare function appendAdvisory(entry: AdvisoryRecord, options?: LedgerOptions): void;
+/**
+ * Print one advisory line and append one JSONL record.
+ * Missing, disabled, stale, and corrupt ledgers print nothing and record nothing.
+ * Any other error becomes one stderr line and is not rethrown.
+ */
+export declare function emitDispatchAdvisory(input: DispatchAdvisoryInput): void;
+//# sourceMappingURL=read.d.ts.map

package/dist/lib/capacity/read.js

@@ -0,0 +1,264 @@
+/**
+ * Advisory reader for lanes and other dispatchers (US-010).
+ * Files only. Never blocks, reroutes, or mutates provider choice.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { LedgerCorrupt, LedgerMissing, capacityRoot, readCollectorMark, readNow as readLedgerNow, } from "./ledger.js";
+export { LedgerCorrupt, LedgerMissing };
+/** Same window as `hq capacity`: generatedAt older than this is stale. */
+export const ADVISORY_STALE_MS = 5 * 60 * 1000;
+function clock(env, options) {
+    const base = { ...options, env };
+    if (base.now)
+        return base;
+    const raw = env.HQ_CAPACITY_NOW?.trim();
+    if (!raw)
+        return base;
+    const parsed = Date.parse(raw);
+    if (Number.isNaN(parsed)) {
+        throw new Error(`HQ_CAPACITY_NOW must be a UTC timestamp, got '${raw}'`);
+    }
+    return { ...base, now: () => new Date(parsed) };
+}
+function ledgerOptions(env) {
+    const override = env.HQ_CAPACITY_ROOT?.trim();
+    if (override)
+        return clock(env, { root: override });
+    const home = env.HOME?.trim() || env.USERPROFILE?.trim() || os.homedir();
+    return clock(env, { home });
+}
+/**
+ * Vitest inherits the operator's HOME. A test that did not point
+ * HQ_CAPACITY_ROOT at a fixture must not read or write ~/.hq/capacity.
+ */
+function suppressedByTestHarness(env) {
+    if (env.HQ_CAPACITY_ROOT?.trim())
+        return false;
+    // Spawn tests pass a partial env that omits VITEST. The process env is what
+    // vitest sets, and that env still inherits the operator's real HOME.
+    const marker = env.VITEST ?? process.env.VITEST;
+    return marker === "true" || marker === "1";
+}
+function freshness(generatedAt, nowMs) {
+    const at = Date.parse(generatedAt);
+    if (Number.isNaN(at))
+        return { stale: true, ageMs: 0 };
+    const ageMs = Math.max(0, nowMs - at);
+    return { stale: ageMs > ADVISORY_STALE_MS, ageMs };
+}
+const ACCOUNT_HOME_ENV = {
+    claude: "CLAUDE_CONFIG_DIR",
+    codex: "CODEX_HOME",
+    grok: "GROK_HOME",
+};
+function lowestWeekly(limits) {
+    let best = null;
+    for (const limit of limits) {
+        if (limit.kind !== "weekly_all" || typeof limit.usedPercent !== "number")
+            continue;
+        if (!best || (limit.usedPercent ?? Infinity) < (best.usedPercent ?? Infinity))
+            best = limit;
+    }
+    return best;
+}
+/**
+ * The weekly_all row the advisory quotes. Lowest usedPercent when several exist.
+ * Pass accountId to prefer that account, falling back to the lowest across accounts.
+ */
+export function weeklyLimit(provider, accountId) {
+    if (!accountId)
+        return lowestWeekly(provider.limits);
+    return lowestWeekly(provider.limits.filter((limit) => limit.accountId === accountId))
+        ?? lowestWeekly(provider.limits);
+}
+/** Caller's lane account when the home or label matches, else the lowest-used account. */
+export function preferredAccountId(provider, env) {
+    const accounts = provider.accounts;
+    if (!accounts || accounts.length === 0 || !env)
+        return undefined;
+    const key = ACCOUNT_HOME_ENV[provider.provider];
+    const raw = key ? env[key]?.trim() : "";
+    if (raw) {
+        const resolved = path.resolve(raw);
+        const byHome = accounts.find((account) => account.homes.some((home) => path.resolve(home) === resolved));
+        if (byHome)
+            return byHome.accountId;
+        const byLabel = accounts.find((account) => account.labels.includes(raw));
+        if (byLabel)
+            return byLabel.accountId;
+    }
+    let best = null;
+    for (const account of accounts) {
+        if (account.signedOut)
+            continue;
+        const limit = lowestWeekly(account.limits);
+        if (!limit || typeof limit.usedPercent !== "number")
+            continue;
+        if (!best || limit.usedPercent < best.used)
+            best = { accountId: account.accountId, used: limit.usedPercent };
+    }
+    return best?.accountId;
+}
+export function weeklyUsedPercent(provider, env) {
+    return weeklyLimit(provider, preferredAccountId(provider, env))?.usedPercent ?? null;
+}
+export function formatSpan(seconds) {
+    if (seconds === null || !Number.isFinite(seconds))
+        return "—";
+    const span = Math.max(0, Math.floor(seconds));
+    if (span < 60)
+        return `${span}s`;
+    const minutes = Math.floor(span / 60);
+    if (minutes < 60)
+        return `${minutes}m`;
+    const hours = Math.floor(minutes / 60);
+    const remainMinutes = minutes % 60;
+    if (hours < 48)
+        return remainMinutes === 0 ? `${hours}h` : `${hours}h ${remainMinutes}m`;
+    const days = Math.floor(hours / 24);
+    const remainHours = hours % 24;
+    return remainHours === 0 ? `${days}d` : `${days}d ${remainHours}h`;
+}
+/**
+ * Read now.json. Throws LedgerMissing when the file is absent and
+ * LedgerCorrupt when it is not a view. `stale` and `ageMs` are about
+ * generatedAt, not about an individual limit.
+ */
+export function readNow(options) {
+    const env = options?.env ?? process.env;
+    const resolved = options?.root || options?.home || options?.now
+        ? clock(env, options)
+        : ledgerOptions(env);
+    const view = readLedgerNow(resolved);
+    const nowMs = resolved.now ? resolved.now().getTime() : Date.now();
+    return { ...view, ...freshness(view.generatedAt, nowMs) };
+}
+/**
+ * Provider with state ok and the lowest weekly_all usedPercent.
+ * Ties keep `chosenEngine` when it is one of the tied providers.
+ * Null when no ok provider has a weekly_all percent.
+ */
+export function naiveChoice(view, chosenEngine, env) {
+    let best = null;
+    for (const provider of view.providers) {
+        if (provider.state !== "ok")
+            continue;
+        const used = weeklyUsedPercent(provider, env);
+        if (used === null)
+            continue;
+        if (!best
+            || used < best.used
+            || (used === best.used && provider.provider === chosenEngine)) {
+            best = { provider: provider.provider, used };
+        }
+    }
+    return best?.provider ?? null;
+}
+function observedAge(limit, generatedAt) {
+    if (!limit)
+        return "—";
+    const now = Date.parse(generatedAt);
+    const at = Date.parse(limit.observedAt);
+    if (Number.isNaN(now) || Number.isNaN(at))
+        return "—";
+    return `${formatSpan(Math.floor((now - at) / 1000))} ago`;
+}
+function percentText(limit) {
+    return limit && typeof limit.usedPercent === "number" ? `${limit.usedPercent}%` : "—";
+}
+/** One stderr line. The chosen engine is first and carries reset and age. */
+export function formatAdvisory(view, chosenEngine, env) {
+    const ordered = [];
+    const chosen = view.providers.find((provider) => provider.provider === chosenEngine);
+    ordered.push(chosen ?? {
+        provider: chosenEngine,
+        state: "unknown",
+        lastError: null,
+        limits: [],
+    });
+    for (const provider of view.providers) {
+        if (provider.provider !== chosenEngine)
+            ordered.push(provider);
+    }
+    const parts = ordered.map((provider, index) => {
+        const limit = weeklyLimit(provider, preferredAccountId(provider, env));
+        const pct = percentText(limit);
+        if (index === 0) {
+            const resets = limit && typeof limit.secondsToReset === "number"
+                ? formatSpan(limit.secondsToReset)
+                : "—";
+            return `${provider.provider} weekly ${pct} used, resets in ${resets} (observed ${observedAge(limit, view.generatedAt)})`;
+        }
+        return `${provider.provider} weekly ${pct}`;
+    });
+    return `capacity: ${parts.join("; ")}`;
+}
+export function appendAdvisory(entry, options) {
+    const env = options?.env ?? process.env;
+    const resolved = options?.root || options?.home
+        ? { ...options, env }
+        : ledgerOptions(env);
+    const root = resolved.root ?? capacityRoot(env, resolved.home);
+    if (!fs.existsSync(root))
+        throw new LedgerMissing();
+    const day = /^\d{4}-\d{2}-\d{2}/.test(entry.at) ? entry.at.slice(0, 10) : new Date().toISOString().slice(0, 10);
+    const dest = path.join(root, `advisories-${day}.jsonl`);
+    fs.appendFileSync(dest, `${JSON.stringify(entry)}\n`, { mode: 0o600 });
+    try {
+        fs.chmodSync(dest, 0o600);
+    }
+    catch {
+        // The line is already durable. Mode is best-effort on a race.
+    }
+}
+/**
+ * Print one advisory line and append one JSONL record.
+ * Missing, disabled, stale, and corrupt ledgers print nothing and record nothing.
+ * Any other error becomes one stderr line and is not rethrown.
+ */
+export function emitDispatchAdvisory(input) {
+    const env = input.env ?? process.env;
+    const stderr = input.stderr ?? process.stderr;
+    if (suppressedByTestHarness(env))
+        return;
+    try {
+        const options = ledgerOptions(env);
+        const mark = readCollectorMark(options);
+        if (mark?.enabled === false)
+            return;
+        let snap;
+        try {
+            snap = readNow(options);
+        }
+        catch (err) {
+            if (err instanceof LedgerMissing || err instanceof LedgerCorrupt)
+                return;
+            throw err;
+        }
+        if (snap.stale)
+            return;
+        const naiveEngine = naiveChoice(snap, input.chosenEngine, env);
+        const record = {
+            at: (options.now ? options.now() : new Date()).toISOString(),
+            caller: input.caller,
+            story: input.story ?? null,
+            chosenEngine: input.chosenEngine,
+            naiveEngine,
+            agree: naiveEngine === input.chosenEngine,
+            providers: snap.providers.map((provider) => ({
+                provider: provider.provider,
+                state: provider.state,
+                weeklyUsedPercent: weeklyUsedPercent(provider, env),
+            })),
+        };
+        appendAdvisory(record, options);
+        stderr.write(`${formatAdvisory(snap, input.chosenEngine, env)}\n`);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        stderr.write(`capacity advisory skipped: ${message}\n`);
+    }
+}
+//# sourceMappingURL=read.js.map

package/dist/lib/capacity/refusal.d.ts

@@ -0,0 +1,30 @@
+import { type LedgerOptions, type NowLimit } from "./ledger.js";
+export declare const REFUSAL_PROVIDERS: readonly ["claude", "codex", "grok"];
+export type RefusalProvider = (typeof REFUSAL_PROVIDERS)[number];
+export declare const REFUSAL_PARSER_VERSION = "capacity-refusal.1";
+export declare const REFUSAL_DEFAULT_LIMIT_ID = "weekly";
+export declare const REFUSAL_HELP: string;
+export declare class CapacityUsageError extends Error {
+    readonly exitCode: 2;
+    constructor(message: string);
+}
+export interface IngestRefusalInput {
+    provider?: string;
+    limitId?: string;
+    resetsAt?: string;
+    accountId?: string;
+}
+export interface RefusalRecord {
+    provider: RefusalProvider;
+    accountId: string;
+    limitId: string;
+    source: "refusal";
+    confidence: "inferred";
+    observedAt: string;
+    state: NowLimit["state"];
+    resetsAt: string | null;
+    readingId: string;
+    usedPercent: number | null;
+}
+export declare function ingestRefusal(input: IngestRefusalInput, options?: LedgerOptions): RefusalRecord;
+//# sourceMappingURL=refusal.d.ts.map