@indigoai-us/hq-cli 5.345.156 → 5.345.160

package/dist/lib/hook-engine/resolve.d.ts

@@ -1,3 +1,4 @@
+import { type SpawnSyncReturns } from 'node:child_process';
 export declare const HOOK_ENGINE_REPAIR = "npm install -g @indigoai-us/hq-cli --include=optional";
 export declare const HOOK_ENGINE_REPAIR_PIN = "hq core hook-engine-path --repair";
 export interface EngineOptions {
@@ -23,6 +24,19 @@ export declare function pinnedHookEngineMatches(engine: EnginePackage): boolean;
 export declare function findHookEngine(options?: EngineOptions): EnginePackage | null;
 /** Never truncate or replace a running Windows executable. */
 export declare function installHookEngine(options?: EngineOptions): string | null;
+/** master-hook.sh reads this one-line file with shell builtins to find the
+ * pinned engine without starting Node (US-021 bridge). It always names the
+ * engine of the CLI that wrote it, so a CLI update retargets it. */
+export declare function hookEnginePointerPath(options?: EngineOptions): string;
+/** Best effort and atomic: a missing pointer only keeps the bridge off. */
+export declare function writeHookEnginePointer(pinned: string, options?: EngineOptions): void;
+export declare function removeHookEnginePointer(options?: EngineOptions): void;
+export interface VerifyOptions {
+    spawn?: (command: string, args: readonly string[]) => Pick<SpawnSyncReturns<string>, 'status' | 'stdout' | 'error'>;
+}
+/** Run the engine's own `--self-check` and read its report. Returns the
+ * problem as text, or null when the binary answers as an hq-hook engine. */
+export declare function verifyHookEngine(binary: string, options?: VerifyOptions): string | null;
 /** Call only after settings no longer reference these old versions. Windows
  * refuses unlink of a mapped executable; a busy version stays for a later pass.
  * POSIX permits unlink while running, so retain those versions conservatively.

package/dist/lib/hook-engine/resolve.js

@@ -1,5 +1,6 @@
 import { createRequire } from 'node:module';
-import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, rmdirSync, unlinkSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, rmdirSync, unlinkSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 const require = createRequire(import.meta.url);
@@ -104,8 +105,61 @@ export function installHookEngine(options = {}) {
     if (!pinnedHookEngineMatches(engine)) {
         throw new Error(`Hook engine ${engine.version} differs from its pinned copy; close HQ sessions and repair with: ${HOOK_ENGINE_REPAIR_PIN}`);
     }
+    writeHookEnginePointer(engine.pinned, options);
     return engine.pinned;
 }
+/** master-hook.sh reads this one-line file with shell builtins to find the
+ * pinned engine without starting Node (US-021 bridge). It always names the
+ * engine of the CLI that wrote it, so a CLI update retargets it. */
+export function hookEnginePointerPath(options = {}) {
+    return join(options.home ?? homedir(), '.hq', 'bin', 'hq-hook', 'current');
+}
+/** Best effort and atomic: a missing pointer only keeps the bridge off. */
+export function writeHookEnginePointer(pinned, options = {}) {
+    const pointer = hookEnginePointerPath(options);
+    try {
+        mkdirSync(dirname(pointer), { recursive: true });
+        const stage = `${pointer}.${process.pid}.tmp`;
+        writeFileSync(stage, `${pinned}\n`);
+        renameSync(stage, pointer);
+    }
+    catch {
+        // The hook path falls back to bash when the pointer is absent.
+    }
+}
+export function removeHookEnginePointer(options = {}) {
+    try {
+        unlinkSync(hookEnginePointerPath(options));
+    }
+    catch { /* already absent */ }
+}
+/** Run the engine's own `--self-check` and read its report. Returns the
+ * problem as text, or null when the binary answers as an hq-hook engine. */
+export function verifyHookEngine(binary, options = {}) {
+    const spawn = options.spawn ?? ((command, args) => spawnSync(command, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 10_000 }));
+    let result;
+    try {
+        result = spawn(binary, ['--self-check']);
+    }
+    catch (error) {
+        return `hook engine self-check could not start: ${error instanceof Error ? error.message : String(error)}`;
+    }
+    if (result.error)
+        return `hook engine self-check could not start: ${result.error.message}`;
+    let report;
+    try {
+        report = JSON.parse(String(result.stdout ?? '').trim().split('\n').pop() ?? '');
+    }
+    catch {
+        return `hook engine self-check printed no report (exit ${result.status ?? 'signal'})`;
+    }
+    if (report.engine !== 'hq-hook' || typeof report.version !== 'string' || typeof report.bridge_schema !== 'number') {
+        return 'hook engine self-check report is not from hq-hook';
+    }
+    if (result.status !== 0 || report.ok !== true)
+        return `hook engine self-check failed: ${typeof report.error === 'string' ? report.error : `exit ${result.status ?? 'signal'}`}`;
+    return null;
+}
 /** Call only after settings no longer reference these old versions. Windows
  * refuses unlink of a mapped executable; a busy version stays for a later pass.
  * POSIX permits unlink while running, so retain those versions conservatively.

package/dist/lib/index-render/company-knowledge.js

@@ -1,5 +1,5 @@
 import * as fs from "fs";
-import { at, basename, date, extractKeepFences, generatedFingerprint, generatedStamp, hasUnclosedKeepMarker, heading, immediateEntries, isHidden, log, looksAutoGenerated, readJson, readText, sanitize, stampGenerated, titleize, truncate, write, } from "./shared.js";
+import { at, basename, date, extractKeepFences, generatedFingerprint, generatedStamp, hasUnclosedKeepMarker, heading, immediateEntries, isHidden, log, readJson, readText, sanitize, stampGenerated, titleize, truncate, write, } from "./shared.js";
 function describe(item) {
     const name = basename(item);
     try {
@@ -65,8 +65,6 @@ function shouldOverwrite(context, existing, next) {
         return "write";
     if (stored)
         return "refuse";
-    if (looksAutoGenerated(existing))
-        return "write";
     if (generatedFingerprint(existing) === generatedFingerprint(next))
         return "write";
     return "refuse";

package/dist/lib/index-render/projects.js

@@ -1,6 +1,6 @@
 import * as fs from "fs";
 import * as path from "path";
-import { at, basename, date, exists, extractKeepFences, generatedFingerprint, generatedStamp, hasUnclosedKeepMarker, immediateEntries, isHidden, log, looksAutoGenerated, projectStatus, readJson, readText, sanitize, stampGenerated, titleize, truncate, write, } from "./shared.js";
+import { at, basename, date, exists, extractKeepFences, generatedFingerprint, generatedStamp, hasUnclosedKeepMarker, immediateEntries, isHidden, log, projectStatus, readJson, readText, sanitize, stampGenerated, titleize, truncate, write, } from "./shared.js";
 function composeCompanyProjectsIndex(raw, existing) {
     const stamped = stampGenerated(raw);
     const fences = existing === undefined ? "" : extractKeepFences(existing);
@@ -20,8 +20,6 @@ function shouldOverwriteCompanyProjectsIndex(context, existing, next) {
         return "write";
     if (stored)
         return "refuse";
-    if (looksAutoGenerated(existing))
-        return "write";
     if (generatedFingerprint(existing) === generatedFingerprint(next))
         return "write";
     return "refuse";

package/dist/lib/lanes/account-company.d.ts

@@ -0,0 +1,28 @@
+import { LanesError } from "./errors.js";
+import type { AccountConfig, LaneCompanyRef } from "./types.js";
+type ProviderAccounts = Record<string, AccountConfig | undefined>;
+/**
+ * Company enforcement is opt-in per provider: it begins once any account for
+ * that provider carries a `company` tag. Until then every account stays open
+ * to every lane, so existing installs keep creating company lanes after upgrade.
+ */
+export declare function companyEnforcementActive(providerAccounts: ProviderAccounts | undefined): boolean;
+/**
+ * Account ownership is explicit; names and homes never imply a tenant.
+ * Pass the provider's account map to apply the opt-in rule above.
+ */
+export declare function accountMatchesCompany(account: AccountConfig | undefined, company: LaneCompanyRef | null, providerAccounts?: ProviderAccounts): boolean;
+/** Legacy untagged accounts may retain an existing lane, never acquire one. */
+export declare function accountMayRetainLane(account: AccountConfig | undefined, company: LaneCompanyRef | null, providerAccounts?: ProviderAccounts): boolean;
+/**
+ * When enforcement is active and every enabled candidate was excluded only by
+ * company ownership, name the problem instead of reporting no enabled account.
+ */
+export declare function companyMismatchError(input: {
+    provider: string;
+    providerAccounts: ProviderAccounts;
+    candidates: readonly string[];
+    company: LaneCompanyRef | null;
+}): LanesError | undefined;
+export {};
+//# sourceMappingURL=account-company.d.ts.map

package/dist/lib/lanes/account-company.js

@@ -0,0 +1,53 @@
+import { LanesError } from "./errors.js";
+/**
+ * Company enforcement is opt-in per provider: it begins once any account for
+ * that provider carries a `company` tag. Until then every account stays open
+ * to every lane, so existing installs keep creating company lanes after upgrade.
+ */
+export function companyEnforcementActive(providerAccounts) {
+    if (providerAccounts === undefined)
+        return true;
+    return Object.values(providerAccounts).some((account) => account?.company !== undefined);
+}
+/**
+ * Account ownership is explicit; names and homes never imply a tenant.
+ * Pass the provider's account map to apply the opt-in rule above.
+ */
+export function accountMatchesCompany(account, company, providerAccounts) {
+    if (account === undefined)
+        return false;
+    if (providerAccounts !== undefined && !companyEnforcementActive(providerAccounts))
+        return true;
+    if (company === null)
+        return account.company === undefined;
+    return account.company === company.uid || account.company === company.slug;
+}
+/** Legacy untagged accounts may retain an existing lane, never acquire one. */
+export function accountMayRetainLane(account, company, providerAccounts) {
+    return account !== undefined && (account.company === undefined || accountMatchesCompany(account, company, providerAccounts));
+}
+/**
+ * When enforcement is active and every enabled candidate was excluded only by
+ * company ownership, name the problem instead of reporting no enabled account.
+ */
+export function companyMismatchError(input) {
+    if (!companyEnforcementActive(input.providerAccounts))
+        return undefined;
+    const enabled = input.candidates.filter((id) => input.providerAccounts[id]?.enabled === true);
+    if (enabled.length === 0)
+        return undefined;
+    if (enabled.some((id) => accountMatchesCompany(input.providerAccounts[id], input.company, input.providerAccounts)))
+        return undefined;
+    const companyLabel = input.company === null ? "(no company)" : input.company.slug;
+    const excluded = enabled.map((id) => ({ account: id, company: input.providerAccounts[id]?.company ?? null }));
+    return new LanesError("account_company_mismatch", `No enabled ${input.provider} account belongs to lane company ${companyLabel}. ` +
+        `Excluded for company: ${excluded.map((row) => `${row.account} (${row.company ?? "untagged"})`).join(", ")}. ` +
+        `Set "company" on an account under providers.${input.provider}.accounts in personal/lanes/config.json.`, {
+        provider: input.provider,
+        company: input.company?.slug ?? null,
+        excluded_accounts: excluded,
+        config_key: `providers.${input.provider}.accounts.<id>.company`,
+        config_file: "personal/lanes/config.json",
+    });
+}
+//# sourceMappingURL=account-company.js.map

package/dist/lib/lanes/accounts.d.ts

@@ -4,11 +4,15 @@
  * Naming an account and omitting one mean different things: an explicit
  * disabled id is refused; omitting picks the least-loaded eligible account.
  * Status reports `configured` and `logged_in` separately. logged_in is
- * derived from credential-file existence or a provider status command; this
- * module never reads, prints, copies, or hashes credential files.
+ * derived from credential-file existence or a provider status command. For
+ * Claude, an injected `readClaudeCredential` also checks the access-token
+ * expiry of the credential the worker will use (see claude-credential.ts), so
+ * an expired sign-in reports `logged_in: false` with `sign_in_state: "expired"`.
+ * This module never prints, copies, or hashes credentials.
  */
 import { type LaneRecord, type LaneProvider } from "./types.js";
 import type { LanesConfig } from "./types.js";
+import type { ClaudeCredentialReader, ClaudeTokenState } from "./claude-credential.js";
 export declare const PROVIDER_HOME_ENV: Record<LaneProvider, string>;
 /**
  * Claude Code keys its OS keychain credential by `CLAUDE_CONFIG_DIR`: with
@@ -71,6 +75,12 @@ export interface AccountDeps {
     /** Provider status output is parsed for a boolean only; it is never printed. */
     probe?: (command: string, args: string[], env: NodeJS.ProcessEnv) => AccountStatusProbeResult;
     env?: NodeJS.ProcessEnv;
+    /**
+     * Reads the access-token expiry of the Claude credential the worker uses.
+     * Production callers pass readLaneClaudeCredential; omitted, expiry is not
+     * checked and logged_in keeps the presence-only result.
+     */
+    readClaudeCredential?: ClaudeCredentialReader;
 }
 export interface AccountResolveContext {
     hqRoot?: string;
@@ -110,9 +120,16 @@ export interface AccountStatus {
     disabled_reason?: string;
     /** Present in personal/lanes/config.json. */
     configured: boolean;
-    /** True/false comes from file existence or the provider status command. */
+    /**
+     * True/false comes from file existence or the provider status command.
+     * For Claude, an expired access token forces false.
+     */
     logged_in: boolean | null;
     auth_state: AuthState;
+    /** Claude only, when the credential was read: whether its access token is still valid. */
+    sign_in_state?: ClaudeTokenState;
+    /** Claude only: when the access token expires, if the credential records it. */
+    sign_in_expires_at?: string | null;
     envVar: string;
 }
 export declare function credentialPaths(provider: LaneProvider, home: string): string[];
@@ -129,6 +146,8 @@ export declare function authStateFor(provider: LaneProvider, present: boolean):
 export declare function loggedInFromAuthState(state: AuthState): boolean | null;
 /** Admission and listing share this: refuse only a conclusive logged-out. */
 export declare function isLoggedOut(status: Pick<AccountStatus, "logged_in">): boolean;
+/** True when the Claude credential exists but its access token has expired. */
+export declare function isSignInExpired(status: Pick<AccountStatus, "sign_in_state">): boolean;
 /** Auto-select requires a positive file or provider-status login result. */
 export declare function isCredentialProven(status: Pick<AccountStatus, "logged_in">): boolean;
 /**

package/dist/lib/lanes/accounts.js

@@ -4,8 +4,11 @@
  * Naming an account and omitting one mean different things: an explicit
  * disabled id is refused; omitting picks the least-loaded eligible account.
  * Status reports `configured` and `logged_in` separately. logged_in is
- * derived from credential-file existence or a provider status command; this
- * module never reads, prints, copies, or hashes credential files.
+ * derived from credential-file existence or a provider status command. For
+ * Claude, an injected `readClaudeCredential` also checks the access-token
+ * expiry of the credential the worker will use (see claude-credential.ts), so
+ * an expired sign-in reports `logged_in: false` with `sign_in_state: "expired"`.
+ * This module never prints, copies, or hashes credentials.
  */
 import * as fs from "node:fs";
 import * as os from "node:os";
@@ -184,6 +187,10 @@ export function loggedInFromAuthState(state) {
 export function isLoggedOut(status) {
     return status.logged_in === false;
 }
+/** True when the Claude credential exists but its access token has expired. */
+export function isSignInExpired(status) {
+    return status.sign_in_state === "expired";
+}
 /** Auto-select requires a positive file or provider-status login result. */
 export function isCredentialProven(status) {
     return status.logged_in === true;
@@ -330,6 +337,9 @@ export function selectBalancedAccount(provider, config, ctx = {}) {
             ...(ctx.accountDeps?.probe ? { probe: ctx.accountDeps.probe } : {}),
             ...(ctx.accountDeps?.env ? { env: ctx.accountDeps.env } : {}),
             ...(ctx.accountDeps?.homedir ? { homedir: ctx.accountDeps.homedir } : {}),
+            ...(ctx.accountDeps?.readClaudeCredential
+                ? { readClaudeCredential: ctx.accountDeps.readClaudeCredential }
+                : {}),
             ...(ctx.hostname !== undefined ? { hostname: ctx.hostname } : {}),
         });
         if (status.logged_in === true)
@@ -434,6 +444,9 @@ export function resolveAccount(provider, requestedId, config, ctx = {}) {
                     probe: ctx.accountDeps.probe,
                     ...(ctx.accountDeps.env ? { env: ctx.accountDeps.env } : {}),
                     ...(ctx.accountDeps.homedir ? { homedir: ctx.accountDeps.homedir } : {}),
+                    ...(ctx.accountDeps.readClaudeCredential
+                        ? { readClaudeCredential: ctx.accountDeps.readClaudeCredential }
+                        : {}),
                     ...(ctx.hostname !== undefined ? { hostname: ctx.hostname } : {}),
                 });
                 throwIfQuotaBlocked(block, provider, requestedId, status.identity);
@@ -469,6 +482,18 @@ export function accountStatus(provider, accountId, config, deps = defaultAccount
     let auth_state = homeExists ? authStateFor(provider, present) : "home_missing";
     let logged_in = homeExists ? loggedInFromAuthState(auth_state) : false;
     let identity;
+    let token;
+    if (homeExists && provider === "claude" && deps.readClaudeCredential !== undefined) {
+        try {
+            token = deps.readClaudeCredential({
+                home: effective.home,
+                defaultHome: isDefaultProviderHome("claude", effective.home, deps.homedir),
+            });
+        }
+        catch {
+            process.stderr.write(`hq lanes: Claude credential expiry check failed for account ${accountId}\n`);
+        }
+    }
     if (homeExists && !present && provider === "claude" && deps.probe !== undefined) {
         try {
             const result = deps.probe("claude", ["auth", "status"], withProviderHomeEnv(deps.env ?? process.env, "claude", effective.home, deps.homedir));
@@ -483,6 +508,13 @@ export function accountStatus(provider, accountId, config, deps = defaultAccount
             process.stderr.write(`hq lanes: Claude auth status probe failed for account ${accountId}\n`);
         }
     }
+    if (token?.state === "expired") {
+        // The credential is there but the worker would start with a dead token.
+        logged_in = false;
+    }
+    else if (token?.state === "valid" && logged_in === null) {
+        logged_in = true;
+    }
     const status = {
         provider,
         id: accountId,
@@ -494,6 +526,10 @@ export function accountStatus(provider, accountId, config, deps = defaultAccount
         auth_state,
         envVar,
     };
+    if (token !== undefined) {
+        status.sign_in_state = token.state;
+        status.sign_in_expires_at = token.expires_at;
+    }
     if (identity)
         status.identity = identity;
     if (account.disabled_reason !== undefined) {

package/dist/lib/lanes/claude-balance.d.ts

@@ -1,6 +1,6 @@
 import type { AuthState } from "./accounts.js";
 import type { HostCapacityAccount, HostCapacitySnapshot } from "./host-capacity.js";
-import type { LaneHost, LanePlacementPolicy, LaneRecord, LanesConfig } from "./types.js";
+import type { LaneCompanyRef, LaneHost, LanePlacementPolicy, LaneRecord, LanesConfig } from "./types.js";
 import { type QuotaState } from "./quota.js";
 export declare const BALANCE_LIVE_STATES: readonly ["running", "queued", "awaiting_input"];
 export declare const BALANCE_MOVABLE_STATES: readonly ["interrupted", "done", "awaiting_input"];
@@ -71,6 +71,9 @@ export interface BalanceMoveSuggestion {
     skip_reason?: "running_turn" | "state_not_movable" | "no_provider_session" | "pending_resume";
 }
 export declare function selectClaudeAccount(input: {
+    company?: LaneRecord["company"];
+    /** Only an already-recorded account may use the legacy untagged exception. */
+    retainedAccount?: string;
     hosts: readonly BalanceHostSnapshot[];
     targetHost: LaneHost;
     config: LanesConfig;
@@ -95,5 +98,7 @@ export declare function accountLoadsForReport(input: {
 export declare function planClaudeBalanceMoves(input: {
     hosts: readonly BalanceHostSnapshot[];
     config: LanesConfig;
+    /** Resolves a lane's effective company (lane, mesh company, then project owner). */
+    laneCompany?: (lane: LaneRecord) => LaneCompanyRef | null;
 }): BalanceMoveSuggestion[];
 //# sourceMappingURL=claude-balance.d.ts.map

package/dist/lib/lanes/claude-balance.js

@@ -1,4 +1,5 @@
 import { LanesError } from "./errors.js";
+import { accountMatchesCompany, accountMayRetainLane } from "./account-company.js";
 import { quotaBlockFor } from "./quota.js";
 export const BALANCE_LIVE_STATES = ["running", "queued", "awaiting_input"];
 export const BALANCE_MOVABLE_STATES = ["interrupted", "done", "awaiting_input"];
@@ -134,7 +135,10 @@ function buildLoads(input) {
         const quotaBlock = input.quotaState === undefined
             ? undefined
             : quotaBlockFor(input.quotaState, "claude", account, quotaModel, input.now);
-        const ineligible = targetIneligibilityReason(account, configAccounts[account]?.enabled === true, input.allowedAccounts, targetLoad) ?? (quotaBlock?.blocked === true ? "quota_held" : undefined);
+        const companyMismatch = input.company !== undefined && !(account === input.retainedAccount
+            ? accountMayRetainLane(configAccounts[account], input.company, configAccounts)
+            : accountMatchesCompany(configAccounts[account], input.company, configAccounts));
+        const ineligible = companyMismatch ? "company_mismatch" : targetIneligibilityReason(account, configAccounts[account]?.enabled === true, input.allowedAccounts, targetLoad) ?? (quotaBlock?.blocked === true ? "quota_held" : undefined);
         if (ineligible !== undefined)
             skipped.push({ account, host: targetHost, reason: ineligible });
         const knownCounts = hosts.flatMap((host) => host.live_lanes === null ? [] : [host.live_lanes]);
@@ -285,6 +289,7 @@ export function planClaudeBalanceMoves(input) {
         if (sourceStatus === undefined)
             continue;
         const candidates = Object.keys(input.config.providers.claude.accounts)
+            .filter((account) => accountMatchesCompany(input.config.providers.claude.accounts[account], input.laneCompany ? input.laneCompany(lane) : lane.company, input.config.providers.claude.accounts))
             .filter((account) => account !== source && input.config.providers.claude.accounts[account]?.enabled === true)
             .map((account) => ({
             account,

package/dist/lib/lanes/claude-credential.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Expiry check for the Claude OAuth credential a lane worker will use.
+ *
+ * `hq lanes accounts list` used to report `logged_in: true` when a
+ * credential merely existed (a `.credentials.json` file, or `claude auth
+ * status` saying a keychain item is present). An expired access token still
+ * passed, and the lane exited seconds after start with an OAuth expiry
+ * error. This module reads the same credential the worker reads and reports
+ * whether its access token is still valid.
+ *
+ * The worker's credential is keyed by CLAUDE_CONFIG_DIR:
+ * - macOS: the login user's Keychain item `Claude Code-credentials` for the
+ *   default home (the worker runs with the variable unset), or the
+ *   hash-suffixed item for any other home; `<home>/.credentials.json` when no
+ *   Keychain item exists.
+ * - elsewhere: `<home>/.credentials.json`.
+ *
+ * An access token past its expiry is only reported expired when there is no
+ * refresh token, or the capacity collector has recorded the refresh token as
+ * revoked. Otherwise Claude Code renews the access token at startup, so the
+ * account is still usable.
+ *
+ * Only `claudeAiOauth.expiresAt` and the presence of the tokens are read.
+ * Token values are never returned, logged, or copied; the refresh token is
+ * only passed to the revoked check, which compares a fingerprint.
+ */
+/**
+ * valid: an access token whose expiry is in the future (or not recorded).
+ * expired: an access token whose expiry has passed and that cannot be renewed
+ *   (no refresh token, or the refresh token is recorded as revoked). A lane
+ *   started now fails.
+ * missing: no OAuth credential for this home (API-key setups land here).
+ * unknown: the credential could not be read (Keychain timeout, bad JSON).
+ */
+export type ClaudeTokenState = "valid" | "expired" | "missing" | "unknown";
+export interface ClaudeCredentialCheck {
+    state: ClaudeTokenState;
+    /** ISO time the access token expires, when the credential records it. */
+    expires_at: string | null;
+    source: "keychain" | "file" | null;
+}
+export interface ClaudeCredentialTarget {
+    /** The account home the lane runs with. */
+    home: string;
+    /** True when the worker runs with CLAUDE_CONFIG_DIR unset for this home. */
+    defaultHome: boolean;
+}
+export type ClaudeCredentialReader = (target: ClaudeCredentialTarget) => ClaudeCredentialCheck;
+export interface SecurityResult {
+    status: number | null;
+    /** Holds the credential JSON on success. Parsed in memory, never printed. */
+    stdout: string;
+    timedOut: boolean;
+}
+export interface ClaudeCredentialReaderDeps {
+    platform?: NodeJS.Platform;
+    now?: () => number;
+    security?: (args: readonly string[]) => SecurityResult;
+    readFile?: (file: string) => string;
+    /** Keychain account name; defaults to the login user. */
+    username?: string;
+    /** True when this refresh token is recorded as revoked. */
+    isRefreshRevoked?: (refreshToken: string) => boolean;
+}
+/** Revoked check against the capacity collector's marker file. Never throws. */
+export declare function defaultIsRefreshRevoked(refreshToken: string): boolean;
+export declare const CLAUDE_CREDENTIAL_SECURITY_TIMEOUT_MS = 5000;
+/** Keychain service the worker reads for this home. */
+export declare function laneClaudeKeychainService(target: ClaudeCredentialTarget): string;
+/** Classify a credential document. Returns only state and expiry. */
+export declare function claudeTokenStateFromDocument(text: string, nowMs: number, isRefreshRevoked?: (refreshToken: string) => boolean): {
+    state: ClaudeTokenState;
+    expires_at: string | null;
+};
+export declare function createClaudeCredentialReader(deps?: ClaudeCredentialReaderDeps): ClaudeCredentialReader;
+/** Production reader: real Keychain on macOS, the credentials file elsewhere. */
+export declare const readLaneClaudeCredential: ClaudeCredentialReader;
+//# sourceMappingURL=claude-credential.d.ts.map

package/dist/lib/lanes/claude-credential.js

@@ -0,0 +1,163 @@
+/**
+ * Expiry check for the Claude OAuth credential a lane worker will use.
+ *
+ * `hq lanes accounts list` used to report `logged_in: true` when a
+ * credential merely existed (a `.credentials.json` file, or `claude auth
+ * status` saying a keychain item is present). An expired access token still
+ * passed, and the lane exited seconds after start with an OAuth expiry
+ * error. This module reads the same credential the worker reads and reports
+ * whether its access token is still valid.
+ *
+ * The worker's credential is keyed by CLAUDE_CONFIG_DIR:
+ * - macOS: the login user's Keychain item `Claude Code-credentials` for the
+ *   default home (the worker runs with the variable unset), or the
+ *   hash-suffixed item for any other home; `<home>/.credentials.json` when no
+ *   Keychain item exists.
+ * - elsewhere: `<home>/.credentials.json`.
+ *
+ * An access token past its expiry is only reported expired when there is no
+ * refresh token, or the capacity collector has recorded the refresh token as
+ * revoked. Otherwise Claude Code renews the access token at startup, so the
+ * account is still usable.
+ *
+ * Only `claudeAiOauth.expiresAt` and the presence of the tokens are read.
+ * Token values are never returned, logged, or copied; the refresh token is
+ * only passed to the revoked check, which compares a fingerprint.
+ */
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { CLAUDE_KEYCHAIN_SERVICE, claudeKeychainServiceName, isRefreshTokenRevoked, } from "../capacity/collectors/claude-oauth.js";
+import { resolveLanesHqRoot } from "./hq-root.js";
+/** Revoked check against the capacity collector's marker file. Never throws. */
+export function defaultIsRefreshRevoked(refreshToken) {
+    try {
+        return isRefreshTokenRevoked(resolveLanesHqRoot(), refreshToken);
+    }
+    catch {
+        return false;
+    }
+}
+function safeUsername() {
+    try {
+        return os.userInfo().username || null;
+    }
+    catch {
+        return null;
+    }
+}
+export const CLAUDE_CREDENTIAL_SECURITY_TIMEOUT_MS = 5_000;
+/** `security find-generic-password` exit status when the item does not exist. */
+const SECURITY_ITEM_NOT_FOUND = 44;
+/** Keychain service the worker reads for this home. */
+export function laneClaudeKeychainService(target) {
+    return target.defaultHome ? CLAUDE_KEYCHAIN_SERVICE : claudeKeychainServiceName(target.home);
+}
+/** Classify a credential document. Returns only state and expiry. */
+export function claudeTokenStateFromDocument(text, nowMs, isRefreshRevoked = () => false) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return { state: "unknown", expires_at: null };
+    }
+    if (!isRecord(parsed))
+        return { state: "unknown", expires_at: null };
+    const oauth = parsed.claudeAiOauth;
+    if (!isRecord(oauth))
+        return { state: "missing", expires_at: null };
+    const token = typeof oauth.accessToken === "string" ? oauth.accessToken : oauth.access_token;
+    if (typeof token !== "string" || token.trim() === "")
+        return { state: "missing", expires_at: null };
+    const raw = oauth.expiresAt;
+    if (typeof raw !== "number" || !Number.isFinite(raw))
+        return { state: "valid", expires_at: null };
+    const ms = raw < 1e12 ? raw * 1000 : raw;
+    const date = new Date(ms);
+    const expires_at = Number.isNaN(date.getTime()) ? null : date.toISOString();
+    if (ms > nowMs)
+        return { state: "valid", expires_at };
+    // Past expiry. Claude Code renews the access token from the refresh token
+    // at startup, so this is only a dead sign-in when there is nothing to renew
+    // with or the refresh token is known to be revoked.
+    const refresh = typeof oauth.refreshToken === "string" ? oauth.refreshToken : oauth.refresh_token;
+    if (typeof refresh !== "string" || refresh.trim() === "")
+        return { state: "expired", expires_at };
+    let revoked = false;
+    try {
+        revoked = isRefreshRevoked(refresh);
+    }
+    catch {
+        revoked = false;
+    }
+    return { state: revoked ? "expired" : "valid", expires_at };
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function defaultSecurity(args) {
+    const result = spawnSync("security", [...args], {
+        encoding: "utf8",
+        timeout: CLAUDE_CREDENTIAL_SECURITY_TIMEOUT_MS,
+        stdio: ["ignore", "pipe", "ignore"],
+        maxBuffer: 8 * 1024 * 1024,
+    });
+    const timedOut = result.error?.code === "ETIMEDOUT";
+    return {
+        status: result.error ? null : result.status,
+        stdout: typeof result.stdout === "string" ? result.stdout : "",
+        timedOut,
+    };
+}
+export function createClaudeCredentialReader(deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    const now = deps.now ?? (() => Date.now());
+    const security = deps.security ?? defaultSecurity;
+    const readFile = deps.readFile ?? ((file) => fs.readFileSync(file, "utf8"));
+    const isRefreshRevoked = deps.isRefreshRevoked ?? defaultIsRefreshRevoked;
+    const fromFile = (home) => {
+        let text;
+        try {
+            text = readFile(path.join(home, ".credentials.json"));
+        }
+        catch (err) {
+            const code = err?.code;
+            return { state: code === "ENOENT" ? "missing" : "unknown", expires_at: null, source: null };
+        }
+        return { ...claudeTokenStateFromDocument(text, now(), isRefreshRevoked), source: "file" };
+    };
+    return (target) => {
+        if (platform !== "darwin")
+            return fromFile(target.home);
+        const service = laneClaudeKeychainService(target);
+        let read;
+        try {
+            // Claude Code writes its item under the login user's account name. A
+            // second item with the same service and another account (MCP OAuth
+            // only) can exist, so ask for the user's item first, as the capacity
+            // collector does, and fall back to any item for the service.
+            const username = deps.username ?? safeUsername();
+            read = username
+                ? security(["find-generic-password", "-s", service, "-a", username, "-w"])
+                : { status: SECURITY_ITEM_NOT_FOUND, stdout: "", timedOut: false };
+            if (!read.timedOut && read.status === SECURITY_ITEM_NOT_FOUND) {
+                read = security(["find-generic-password", "-s", service, "-w"]);
+            }
+        }
+        catch {
+            return { state: "unknown", expires_at: null, source: null };
+        }
+        if (read.timedOut)
+            return { state: "unknown", expires_at: null, source: null };
+        if (read.status === SECURITY_ITEM_NOT_FOUND)
+            return fromFile(target.home);
+        if (read.status !== 0)
+            return { state: "unknown", expires_at: null, source: null };
+        return { ...claudeTokenStateFromDocument(read.stdout.replace(/\n$/, ""), now(), isRefreshRevoked), source: "keychain" };
+    };
+}
+/** Production reader: real Keychain on macOS, the credentials file elsewhere. */
+export const readLaneClaudeCredential = createClaudeCredentialReader();
+//# sourceMappingURL=claude-credential.js.map