@indigoai-us/hq-cli 5.126.0 → 5.128.0

package/dist/commands/mesh.js

@@ -6,11 +6,12 @@
  * Distinct from `hq doctor` (hook guardrails).
  */
 import * as os from "node:os";
+import { readFileSync } from "node:fs";
 import { findHqRoot } from "../utils/manifest.js";
 import chalk from "chalk";
 import { loadCachedTokens, isMachineIdentity } from "../utils/cognito-session.js";
 import * as readline from "node:readline/promises";
-import { STORY_STATUSES, appendThreadEvent, ensureProjectThread, eventPayload, listActiveMembershipCompanies, listActiveThreads, patchStoryStatus, resolveActiveMembershipCompany, resolveMeshPrincipalUid, warmMeshConversationCache, } from "../lib/mesh/api.js";
+import { STORY_STATUSES, appendThreadEvent, ensureProjectThread, eventPayload, getProjectView, listActiveMembershipCompanies, listActiveThreads, patchStory, putProjectView, registerMeshProject, resolveActiveMembershipCompany, resolveMeshPrincipalUid, warmMeshConversationCache, } from "../lib/mesh/api.js";
 import { createCandidatesFetcher, createMigratePoster, createOrganizePoster, createWorkSessionDeliverer, fetchCompanyLive, formatCompanyLiveTable, openMeshTransport, probeMigrationCapabilityForMemberships, requireToken, } from "../lib/mesh/client.js";
 import { clearDefaultCompany, isDefaultCompanyDisabled, readDeviceConfig, recordMigrationCapabilitySnapshot, setRepairHeldWithDefault, setDefaultCompany, } from "../lib/work-context/config.js";
 import { ensureDefaultCompany } from "../lib/work-context/default-company.js";
@@ -88,14 +89,19 @@ async function runCheck(opts) {
 async function runEvent(verb, opts) {
     const { token, company } = await withCompany(opts);
     const projectId = requireProject(opts);
+    const eventKind = verb === "start" ? "claim" : verb;
+    let claimant = "";
+    if (eventKind === "claim") {
+        const resolvedClaimant = await resolveMeshPrincipalUid(token, loadCachedTokens());
+        if (!resolvedClaimant) {
+            fail("Could not resolve the authenticated claimant. Sign in again and retry `hq mesh start`.");
+        }
+        claimant = resolvedClaimant;
+    }
     const ensured = await ensureProjectThread(token, company, projectId, {
         threadId: opts.threadId,
         summary: opts.summary,
     });
-    const eventKind = verb === "start" ? "claim" : verb;
-    const claimant = eventKind === "claim"
-        ? await resolveMeshPrincipalUid(token, loadCachedTokens())
-        : "";
     const event = await appendThreadEvent(token, company.companyUid, ensured.threadId, eventKind, eventPayload(eventKind, opts, claimant));
     if (opts.json) {
         console.log(JSON.stringify({
@@ -115,17 +121,215 @@ async function runEvent(verb, opts) {
 async function runStory(opts) {
     const storyId = opts.story?.trim();
     const status = opts.status?.trim();
-    if (!storyId || !status || !STORY_STATUSES.has(status)) {
-        fail("story requires --story <id> and --status queued|in_progress|review|done");
+    const assignee = opts.assignee?.trim();
+    if (!storyId) {
+        fail("story requires --story <id>");
+    }
+    if (!status && !assignee) {
+        fail("story requires --status queued|in_progress|review|done or --assignee <uid|me|none>");
+    }
+    if (status && !STORY_STATUSES.has(status)) {
+        fail("story --status must be queued|in_progress|review|done");
     }
     const { token, company } = await withCompany(opts);
     const projectId = requireProject(opts);
-    const patched = await patchStoryStatus(token, company.companyUid, projectId, storyId, status);
+    let assigneeUid;
+    let clearAssignee = false;
+    if (assignee === "none") {
+        clearAssignee = true;
+    }
+    else if (assignee === "me") {
+        const resolved = await resolveMeshPrincipalUid(token, loadCachedTokens());
+        if (!resolved || resolved === "session") {
+            fail("`--assignee me` needs the signed-in person or agent. The synthetic session identity cannot be assigned. Sign in again and retry `hq mesh story`.");
+        }
+        assigneeUid = resolved;
+    }
+    else if (assignee) {
+        if (!/^(prs|agt)_/.test(assignee)) {
+            fail("`--assignee` must be a person or agent uid, `me`, or `none`.");
+        }
+        assigneeUid = assignee;
+    }
+    const patched = await patchStory(token, company.companyUid, projectId, storyId, {
+        ...(status ? { status } : {}),
+        ...(assigneeUid ? { assigneeUid } : {}),
+        ...(clearAssignee ? { clearAssignee: true } : {}),
+    });
     if (opts.json) {
         console.log(JSON.stringify({ ok: true, action: "story", company, ...patched, storyId }, null, 2));
         return;
     }
-    console.log(`Work mesh: story ${storyId} → ${patched.status} (v${patched.version ?? "?"})`);
+    const assignment = assignee === "none"
+        ? "assignee cleared"
+        : assignee
+            ? `assignee ${patched.assigneeUid ?? assigneeUid}`
+            : "";
+    const statusPart = status ? `${storyId} → ${patched.status}` : storyId;
+    console.log(`Work mesh: story ${statusPart}${assignment ? ` ${assignment}` : ""} (v${patched.version ?? "?"})`);
+}
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function parseProjectRepoSpec(value, source) {
+    const raw = value.trim();
+    const separator = raw.lastIndexOf("@");
+    const path = (separator > 0 ? raw.slice(0, separator) : raw).trim();
+    const branch = (separator > 0 ? raw.slice(separator + 1) : "").trim();
+    if (!path)
+        fail(`${source} requires a non-empty repository path.`);
+    if (separator > 0 && !branch)
+        fail(`${source} has an empty branch after @.`);
+    return { path, branch };
+}
+function parseProjectRepos(value, source) {
+    if (!Array.isArray(value))
+        fail(`${source} must be a JSON repository array.`);
+    return value.map((raw, index) => {
+        if (typeof raw === "string")
+            return parseProjectRepoSpec(raw, `${source}[${index}]`);
+        const repo = record(raw);
+        const path = typeof repo?.path === "string"
+            ? repo.path.trim()
+            : typeof repo?.repoPath === "string"
+                ? repo.repoPath.trim()
+                : typeof repo?.repo === "string"
+                    ? repo.repo.trim()
+                    : "";
+        const branchValue = repo?.branch ?? repo?.branchName;
+        const branch = branchValue === undefined ? "" : typeof branchValue === "string" ? branchValue.trim() : null;
+        if (!repo || !path)
+            fail(`${source}[${index}].path requires a string.`);
+        if (branch === null)
+            fail(`${source}[${index}].branch requires a string.`);
+        return { path, branch };
+    });
+}
+function parseProjectReposJson(raw, source) {
+    try {
+        return parseProjectRepos(JSON.parse(raw), source);
+    }
+    catch (err) {
+        if (err instanceof SyntaxError)
+            fail(`${source} must contain valid JSON.`);
+        throw err;
+    }
+}
+function projectStoriesFromJson(value, source) {
+    const plan = Array.isArray(value) ? null : record(value);
+    const rawStories = Array.isArray(value)
+        ? value
+        : Array.isArray(plan?.userStories)
+            ? plan.userStories
+            : Array.isArray(plan?.stories)
+                ? plan.stories
+                : null;
+    if (!rawStories) {
+        fail(`${source} must be a JSON story array or an object with userStories.`);
+    }
+    const stories = rawStories.map((raw, index) => {
+        const story = record(raw);
+        const id = typeof story?.id === "string" ? story.id.trim() : "";
+        const title = typeof story?.title === "string" ? story.title.trim() : "";
+        if (!story || !id || !title) {
+            fail(`${source} userStories[${index}] requires string id and title.`);
+        }
+        const status = typeof story.status === "string" ? story.status.trim() : undefined;
+        if (status && !STORY_STATUSES.has(status)) {
+            fail(`${source} userStories[${index}].status must be queued|in_progress|review|done.`);
+        }
+        const resolvedStatus = status || (story.passes === true ? "done" : undefined);
+        return {
+            id,
+            title,
+            ...(typeof story.description === "string" ? { description: story.description } : {}),
+            ...(Array.isArray(story.acceptanceCriteria)
+                ? {
+                    acceptanceCriteria: story.acceptanceCriteria.filter((item) => typeof item === "string"),
+                }
+                : {}),
+            ...(resolvedStatus ? { status: resolvedStatus } : {}),
+            // hq-pro makes passes mirror the Board status. A completed PRD story
+            // without an explicit status must therefore become done.
+            passes: resolvedStatus === "done",
+            ...(typeof story.priority === "number" && Number.isFinite(story.priority)
+                ? { priority: story.priority }
+                : {}),
+        };
+    });
+    const metadata = record(plan?.metadata);
+    const repos = metadata && Object.hasOwn(metadata, "repos")
+        ? parseProjectRepos(metadata.repos, `${source} metadata.repos`)
+        : undefined;
+    return {
+        ...(typeof plan?.name === "string" ? { name: plan.name } : {}),
+        ...(typeof plan?.description === "string" ? { description: plan.description } : {}),
+        stories,
+        ...(repos ? { repos } : {}),
+    };
+}
+function parseProjectPlan(raw, source) {
+    try {
+        return projectStoriesFromJson(JSON.parse(raw), source);
+    }
+    catch (err) {
+        if (err instanceof SyntaxError)
+            fail(`${source} must contain valid JSON.`);
+        throw err;
+    }
+}
+async function runProjectSet(projectId, opts) {
+    if (opts.storiesFile && opts.storiesJson) {
+        fail("Pass only one of --stories-file or --stories-json.");
+    }
+    if (opts.reposJson && opts.repo?.length) {
+        fail("Pass only one of --repos-json or --repo.");
+    }
+    const source = opts.storiesFile
+        ? parseProjectPlan(readFileSync(opts.storiesFile, "utf8"), opts.storiesFile)
+        : opts.storiesJson
+            ? parseProjectPlan(opts.storiesJson, "--stories-json")
+            : undefined;
+    const explicitRepos = opts.reposJson
+        ? parseProjectReposJson(opts.reposJson, "--repos-json")
+        : opts.repo?.length
+            ? opts.repo.map((repo, index) => parseProjectRepoSpec(repo, `--repo[${index}]`))
+            : undefined;
+    const { token, company } = await withCompany(opts);
+    const current = await getProjectView(token, company.companyUid, projectId);
+    const principalUid = await resolveMeshPrincipalUid(token, loadCachedTokens());
+    const view = await putProjectView(token, company.companyUid, projectId, {
+        name: opts.name?.trim() || source?.name || current.name,
+        ...(opts.description !== undefined
+            ? { description: opts.description }
+            : source?.description !== undefined
+                ? { description: source.description }
+                : { description: current.description }),
+        stories: source?.stories ?? current.stories,
+        repos: explicitRepos ?? source?.repos ?? current.repos,
+        ...(current.version !== undefined ? { version: current.version } : {}),
+    });
+    if (opts.json) {
+        console.log(JSON.stringify({ ok: true, action: "project.set", principalUid, ...view }, null, 2));
+        return;
+    }
+    console.log(`Work mesh: project ${view.projectId} set (${view.name}; ${view.stories.length} stories)`);
+}
+async function runProjectRegister(projectId, opts) {
+    if (opts.channel?.trim()) {
+        fail("--channel is not supported by the current Work Mesh registration API; omit it to let the server create or bind the project channel.");
+    }
+    const { token, company } = await withCompany(opts);
+    const principalUid = await resolveMeshPrincipalUid(token, loadCachedTokens());
+    const registration = await registerMeshProject(token, company.companyUid, projectId);
+    const boardState = "registered";
+    if (opts.json) {
+        console.log(JSON.stringify({ ok: true, action: "project.register", principalUid, boardState, ...registration }, null, 2));
+        return;
+    }
+    console.log(`Work mesh: project ${registration.projectId} registered (${boardState}; channel ${registration.channelId} ${registration.channelCreated ? "created" : "bound"})`);
 }
 async function runDoctor(opts) {
     if (opts.apply) {
@@ -134,6 +338,9 @@ async function runDoctor(opts) {
     }
     const token = await requireToken();
     const principalUid = await resolveMeshPrincipalUid(token, loadCachedTokens());
+    if (!principalUid) {
+        fail("Could not resolve the authenticated principal. Sign in again and retry `hq mesh doctor`.");
+    }
     const warmed = await warmMeshConversationCache(token, principalUid);
     if (opts.json) {
         console.log(JSON.stringify({ ok: true, action: "doctor", ...warmed }, null, 2));
@@ -349,19 +556,20 @@ async function runContextBackfillHeld(opts) {
     const limit = Number.isFinite(parsedLimit) && parsedLimit > 0 ? parsedLimit : 0;
     const companyHint = opts.company?.trim() || undefined;
     const useDeviceDefault = opts.useDeviceDefault === true || readDeviceConfig({ root }).repairHeldWithDefault === true;
-    // Build the reconcile network seam exactly like `hq mesh context reconcile`.
-    // Not needed in --dry-run (reconcile is never invoked then). Explicit types
-    // because these are captured in the reconcile closure below (no control-flow
-    // narrowing, unlike the inline reconcile handler).
+    // Build the membership seam for both modes; dry-run is read-only but must
+    // validate a locally resolved slug just as live reconciliation does.
+    // The remaining seams are captured in the reconcile closure below.
     let deliver;
     let fetchCandidates;
     let validateMembership;
     let offline = Boolean(opts.offline);
-    if (!dryRun && !offline) {
+    if (!offline) {
         try {
             const token = await requireToken();
-            deliver = createWorkSessionDeliverer({ token });
-            fetchCandidates = createCandidatesFetcher({ token });
+            if (!dryRun) {
+                deliver = createWorkSessionDeliverer({ token });
+                fetchCandidates = createCandidatesFetcher({ token });
+            }
             validateMembership = async (candidate) => {
                 const membership = await resolveActiveMembershipCompany(token, candidate);
                 if (!membership)
@@ -386,6 +594,7 @@ async function runContextBackfillHeld(opts) {
         // so `--dry-run` and the real run report the same counts.
         remoteOwnerHint: companyHint || undefined,
         useDeviceDefault,
+        validateMembership,
         reconcile: (obs) => reconcileObservation(
         // Pass --company as a non-forcing hint (remoteOwnerSlug feeds
         // deterministic resolution BELOW the identity-file / device default,
@@ -413,6 +622,9 @@ async function runContextBackfillHeld(opts) {
         `${result.unresolved} unresolved, ` +
         `${result.errors} error(s).` +
         (dryRun ? " (dry-run: nothing written)" : ""));
+    for (const { sessionId, reason } of result.unresolvedReasons) {
+        console.log(`Unresolved ${sessionId}: ${reason}`);
+    }
     if (!dryRun && result.reconciled > 0) {
         console.log("Reconciled session state files were rewritten with a resolved company; " +
             "the mesh daemon's held retry will re-attribute and post those events.");
@@ -1078,9 +1290,32 @@ export function registerMeshCommand(program) {
         .option("--summary <text>", "Note text")).action((opts) => wrap(() => runEvent("note", opts))());
     addSharedFlags(mesh
         .command("story")
-        .description("PATCH one Board story status")
+        .description("PATCH one Board story status and/or assignee")
         .requiredOption("--story <id>", "Story id, e.g. US-001")
-        .requiredOption("--status <status>", "queued|in_progress|review|done")).action((opts) => wrap(() => runStory(opts))());
+        .option("--status <status>", "queued|in_progress|review|done")
+        .option("--assignee <uid|me|none>", "Assign a person or agent uid, yourself, or clear")).action((opts) => wrap(() => runStory(opts))());
+    const project = mesh
+        .command("project")
+        .description("Set a project Board view or register its project channel");
+    project
+        .command("set <projectId>")
+        .description("PUT the project Board view from flags or a PRD JSON file")
+        .requiredOption("--company <slug|uid>", "Company slug or cloud uid")
+        .option("--name <name>", "Project name")
+        .option("--description <text>", "Project description")
+        .option("--stories-file <path>", "PRD JSON file with userStories")
+        .option("--stories-json <json>", "Story array or JSON object with userStories")
+        .option("--repos-json <json>", "Repository array, such as [{path,branch}]")
+        .option("--repo <path[@branch]>", "Repository binding (repeatable)", collectRepeatable)
+        .option("--json", "Print machine-readable JSON")
+        .action((projectId, opts) => wrap(() => runProjectSet(projectId, opts))());
+    project
+        .command("register <projectId>")
+        .description("POST project registration to create or bind its project channel and Board")
+        .requiredOption("--company <slug|uid>", "Company slug or cloud uid")
+        .option("--channel <channelId>", "Reserved: the current server chooses the project channel")
+        .option("--json", "Print machine-readable JSON")
+        .action((projectId, opts) => wrap(() => runProjectRegister(projectId, opts))());
     mesh
         .command("doctor")
         .description("Warm ~/.hq/work-mesh/cache from hq-pro (directory, inbox, pair DMs). Not `hq doctor`.")
@@ -1110,7 +1345,7 @@ export function registerMeshCommand(program) {
     context
         .command("backfill-held")
         .description("Reconcile ENDED sessions whose held events lack a company so the daemon re-attributes the backlog (explicit, opt-in; no fleet fan-out)")
-        .option("--dry-run", "Report what would be reconciled; write nothing, no network")
+        .option("--dry-run", "Report what would be reconciled; write nothing or deliver events")
         .option("--offline", "Reconcile outbox-only (no candidates/register network)")
         .option("--limit <n>", "Cap sessions processed (default 0 = no cap)")
         .option("--company <slug>", "Optional non-forcing company hint")

package/dist/lib/core-utils/sentry-report.d.ts

@@ -12,6 +12,7 @@
  * than truncated. Unknown scalar metadata is dropped instead: the allowlist,
  * not a caller version match, determines what may leave the machine.
  */
+import * as Sentry from "@sentry/node";
 import type { CaptureContext, SeverityLevel } from "@sentry/node";
 export declare const DEFAULT_SENTRY_REPORT_TIMEOUT_MS = 750;
 export declare const MAX_SENTRY_REPORT_TIMEOUT_MS = 5000;
@@ -41,6 +42,7 @@ export type SentryReportOptions = {
 export type SentryReportDependencies = {
     sentry: {
         captureMessage: (message: string, context?: CaptureContext | SeverityLevel) => string;
+        metrics: Pick<typeof Sentry.metrics, "count">;
         flush: (timeout?: number) => PromiseLike<boolean>;
     };
     stdout: Pick<NodeJS.WriteStream, "write">;

package/dist/lib/core-utils/sentry-report.js

@@ -29,6 +29,9 @@ const SENTRY_REPORT_LEVELS = new Set([
     "info",
     "debug",
 ]);
+const HOOK_TIMEOUT_WARNING_TYPE = "hook_timeout_warning";
+const HOOK_TIMEOUT_WARNING_METRIC = "hq.hook_timeout_warning";
+const HOOK_TIMEOUT_EXCEEDED_FINGERPRINT = "hook-timeout-exceeded";
 /**
  * The only hook diagnostics that can be attached as metadata. The list omits
  * command text, prompts, payloads, company names, and repositories. `hook_path`
@@ -182,21 +185,43 @@ function resolveTimeout(timeoutMs) {
         return null;
     return timeout;
 }
-function sentryEnvelope(event) {
+function sentryEnvelope(event, overrides) {
     return {
-        level: event.level,
-        fingerprint: [event.fingerprint],
+        level: overrides?.level ?? event.level,
+        fingerprint: overrides?.fingerprint ?? [event.fingerprint],
         tags: { sentry_event_type: event.type },
         extra: event.metadata,
     };
 }
 /** Build the same scrubbed event projection that the live SDK path uses. */
-function scrubbedSentryEnvelope(event) {
+function scrubbedSentryEnvelope(event, overrides) {
     return beforeSend({
         message: event.message,
-        ...sentryEnvelope(event),
+        ...sentryEnvelope(event, overrides),
     }, {});
 }
+/**
+ * The watchdog's relative threshold fires before the declared timeout and
+ * clamps remaining_ms at zero, so its real warnings stay on the metric path.
+ * Keep a defensive branch for a genuine exceeded payload from another
+ * producer without restoring per-hook grouping.
+ */
+function hookTimeoutExceededOverrides(event) {
+    if (event.type !== HOOK_TIMEOUT_WARNING_TYPE)
+        return undefined;
+    const elapsedMs = event.metadata.elapsed_ms;
+    const declaredTimeoutMs = event.metadata.declared_timeout_ms;
+    if (typeof elapsedMs !== "number" ||
+        typeof declaredTimeoutMs !== "number" ||
+        elapsedMs < declaredTimeoutMs) {
+        return undefined;
+    }
+    const hookEvent = typeof event.metadata.hook_event === "string" ? event.metadata.hook_event : "unknown";
+    return {
+        level: "warning",
+        fingerprint: [HOOK_TIMEOUT_EXCEEDED_FINGERPRINT, hookEvent],
+    };
+}
 /**
  * Resolve true only when the local transport queue drains within the budget.
  * This does not confirm that the ingest service accepted the event.
@@ -234,13 +259,28 @@ export async function reportSentryEvent(stdin, options = {}, dependencies = defa
         const noun = result.droppedMetadataKeys === 1 ? "key" : "keys";
         dependencies.stderr.write(`Dropped ${result.droppedMetadataKeys} unsupported Sentry report metadata ${noun}.\n`);
     }
-    const envelope = sentryEnvelope(result.event);
+    const overrides = hookTimeoutExceededOverrides(result.event);
     if (options.dryRun) {
-        const scrubbed = scrubbedSentryEnvelope(result.event);
+        const scrubbed = scrubbedSentryEnvelope(result.event, overrides);
         if (scrubbed)
             dependencies.stdout.write(`${JSON.stringify(scrubbed)}\n`);
         return result;
     }
+    if (result.event.type === HOOK_TIMEOUT_WARNING_TYPE && !overrides) {
+        try {
+            dependencies.sentry.metrics.count(HOOK_TIMEOUT_WARNING_METRIC, 1, {
+                attributes: result.event.metadata,
+            });
+            if (await flushWithin(dependencies.sentry, timeoutMs))
+                return result;
+        }
+        catch {
+            // Report failure below without exposing event fields or transport details.
+        }
+        dependencies.stderr.write("Sentry report failed.\n");
+        return invalidInput();
+    }
+    const envelope = sentryEnvelope(result.event, overrides);
     try {
         dependencies.sentry.captureMessage(result.event.message, envelope);
         if (await flushWithin(dependencies.sentry, timeoutMs))

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

@@ -2,17 +2,37 @@
  * Provider account resolution (spec §5.5).
  *
  * Naming an account and omitting one mean different things: an explicit
- * disabled id is refused; omitting rotates past a disabled default.
+ * disabled id is refused; omitting picks the least-loaded eligible account.
  * Status reports `configured` and `logged_in` separately. logged_in is
- * derived from whether <home>/auth.json EXISTS — this module never reads,
- * prints, copies, or hashes that file.
+ * derived from whether a provider credential file EXISTS — this module
+ * never reads, prints, copies, or hashes that file.
  */
-import type { LaneProvider, LanesConfig } from "./types.js";
+import { type LaneRecord, type LaneProvider } from "./types.js";
+import type { LanesConfig } from "./types.js";
 export declare const PROVIDER_HOME_ENV: Record<LaneProvider, string>;
 export declare const AUTH_JSON_NAME = "auth.json";
+export declare const CLAUDE_CREDENTIALS_NAME = ".credentials.json";
+/**
+ * Credential filenames are a property of the provider. Codex and Grok write
+ * auth.json. Claude Code writes .credentials.json (never auth.json) inside
+ * the config dir, and can also authenticate via the OS keychain with no
+ * file here at all.
+ */
+export declare const PROVIDER_CREDENTIAL_FILES: Record<LaneProvider, readonly string[]>;
+export type AuthState = "file" | "absent" | "unknown";
 export interface AccountDeps {
     existsSync: (p: string) => boolean;
 }
+export interface AccountResolveContext {
+    hqRoot?: string;
+    existsSync?: (p: string) => boolean;
+    loadLanes?: (hqRoot: string) => LaneRecord[];
+    /** Already-resolved model for this lane. Beats cliModel and account defaults. */
+    model?: string;
+    /** `--model` from create, applied to every candidate account. */
+    cliModel?: string;
+    now?: Date;
+}
 export interface ResolvedAccount {
     provider: LaneProvider;
     id: string;
@@ -29,12 +49,52 @@ export interface AccountStatus {
     /** Present in personal/lanes/config.json. */
     configured: boolean;
     /**
-     * True iff `<home>/auth.json` exists. Never inspects the file contents.
+     * True when a provider credential file exists. False only when every
+     * candidate is absent AND absence is conclusive for that provider
+     * (Codex, Grok). Null for Claude when no candidate exists: Claude can
+     * authenticate via keychain, so a missing file is not logged-out.
+     * Never inspects file contents.
      */
-    logged_in: boolean;
+    logged_in: boolean | null;
+    auth_state: AuthState;
     envVar: string;
 }
-export declare function resolveAccount(provider: LaneProvider, requestedId: string | undefined, config: LanesConfig): ResolvedAccount;
+export declare function credentialPaths(provider: LaneProvider, home: string): string[];
+/**
+ * Existence-only probe. Callers must not read the files this returns paths to.
+ */
+export declare function hasCredentialFile(provider: LaneProvider, home: string, existsSync: (p: string) => boolean): boolean;
+/**
+ * Claude with no file in the config dir is unknown, not logged out: the
+ * credential may live in the OS keychain or an API-key helper. Codex and
+ * Grok write auth.json when logged in, so absence is logged out.
+ */
+export declare function authStateFor(provider: LaneProvider, present: boolean): AuthState;
+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;
+/** Auto-select requires a proven credential file, not Claude-unknown. */
+export declare function isCredentialProven(status: Pick<AccountStatus, "logged_in">): boolean;
+/**
+ * Occupying states hold a slot: running / awaiting_input / blocked have a
+ * live (or paused-live) worker; queued holds a queue slot that will take a
+ * running slot. Terminal states do not count.
+ */
+export declare function isOccupyingLaneState(state: LaneRecord["state"]): boolean;
+export declare function occupyingLaneCount(lanes: readonly LaneRecord[], provider: LaneProvider, accountId: string): number;
+export declare function runningLaneCount(lanes: readonly LaneRecord[], provider: LaneProvider, accountId: string): number;
+/** Most recent created_at on this account+provider, any state. Null if none. */
+export declare function lastStartedAt(lanes: readonly LaneRecord[], provider: LaneProvider, accountId: string): string | null;
+/**
+ * Pick among enabled, credential-proven accounts by occupying count
+ * (lowest wins). Ties break to least-recently-started (oldest created_at),
+ * then account id ascending. Accounts at max_running are excluded from
+ * start-eligible; if every proven account is at cap the pick still returns
+ * one so admission can queue rather than overflow.
+ */
+export declare function selectBalancedAccount(provider: LaneProvider, config: LanesConfig, ctx?: AccountResolveContext): ResolvedAccount;
+export declare function resolveAccount(provider: LaneProvider, requestedId: string | undefined, config: LanesConfig, ctx?: AccountResolveContext): ResolvedAccount;
+/** Codex/Grok path. Kept for callers that still name auth.json. */
 export declare function authJsonPath(home: string): string;
 export declare function accountStatus(provider: LaneProvider, accountId: string, config: LanesConfig, deps?: AccountDeps): AccountStatus;
 export declare function listAccountStatuses(provider: LaneProvider, config: LanesConfig, deps?: AccountDeps): AccountStatus[];