@indigoai-us/hq-cli 5.153.0 → 5.155.0

package/dist/lib/agent-kit/mcp/attachments.js

@@ -0,0 +1,188 @@
+/**
+ * `hq_attachment_fetch` — pull a chat attachment named on an inbox item down
+ * to a private local file the bot can open.
+ *
+ * Inbox items carry attachments as `{ vaultPath, companyUid, … }` where
+ * `vaultPath` is SCOPE-relative (`chat/attachments/{dm|chan}/<id>/<file>`) and
+ * `companyUid` is the vault scope the bytes live in: the company uid for a
+ * company channel, or the SENDER's person uid (`prs_…`) for a DM, because a DM
+ * attachment is stored in the sender's personal vault. Neither `hq_files_read`
+ * (which only accepts `companies/<slug>/…` and returns clamped text) nor
+ * anything else on the MCP surface could read those, so bots answered
+ * "I can't open the file".
+ *
+ * Bytes come through the same vault presign path `hq files cat` uses
+ * (`createCompanyPresignClient` → POST /v1/files/presign), minted with the
+ * bot's own machine token, so the server's per-key ACL stays the authority.
+ * The client-side checks here are the tenant boundary the bot can state
+ * before any request leaves the machine. They matter because an attachment
+ * ref is SENDER-controlled while the server authorizes against the BOT's own
+ * access: without them a sender could attach any key the bot can read (say
+ * `knowledge/restricted/x.csv` in the bot's company) and have the bot fetch
+ * it for them.
+ *   - the key must be a plain relative path with no traversal, under
+ *     `chat/attachments/`;
+ *   - a DM key (`chat/attachments/dm/<a>--<b>/…`) must name this bot in the
+ *     pair, whichever scope it is read from;
+ *   - a `cmp_` scope must be the bot's own enrolled company;
+ *   - a `prs_` scope is only a DM attachment between that person and this
+ *     bot (the pair naming both).
+ *
+ * Files land under `<agentDir>/attachments/<scopeUid>/` (dir 0700, file 0600)
+ * with a sanitized name, so nothing from the message can pick the location.
+ */
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { McpToolInputError } from "./jsonrpc.js";
+/**
+ * Refuse anything larger than this. Chat uploads are capped at 25 MB
+ * (MAX_CHAT_ATTACHMENT_BYTES in hq-desktop-app); 26 MiB leaves a little
+ * headroom over that without letting a crafted key pull a large vault object.
+ */
+export const MAX_ATTACHMENT_BYTES = 26 * 1024 * 1024;
+/** Upper bound on the inline text rendering returned alongside the path. */
+export const MAX_ATTACHMENT_TEXT_CHARS = 20_000;
+const SCOPE_UID = /^(cmp|prs)_[A-Za-z0-9_-]{1,200}$/;
+/** Every chat upload lands under this prefix in its scope. */
+export const CHAT_ATTACHMENT_PREFIX = "chat/attachments/";
+const DM_KEY = /^chat\/attachments\/dm\/([^/]+)\/[^/]+$/;
+function notChatAttachment(p) {
+    return new McpToolInputError(`${JSON.stringify(p)} is not a chat attachment (expected chat/attachments/…); ` +
+        `hq_attachment_fetch only downloads files attached to HQ messages. For vault files and folders use hq_files_list / hq_files_read.`);
+}
+/**
+ * Validate a scope-relative attachment key. Accepts only `chat/attachments/…`
+ * file keys exactly as inbox items carry them. Folder / share refs (`/`,
+ * `…/`) get a "not a chat attachment" error pointing at hq_files_read.
+ * Rejects absolute paths, traversal, empty / dot segments, backslashes and
+ * control characters. Returns the key with any leading slashes stripped.
+ */
+export function assertAttachmentKey(p) {
+    const trimmed = p.trim();
+    // A folder or share ref is not a traversal attempt, just the wrong tool.
+    if (trimmed.endsWith("/"))
+        throw notChatAttachment(p);
+    const clean = trimmed.replace(/^\/+/, "");
+    const segs = clean.split("/");
+    const bad = clean.length === 0 ||
+        clean.length > 1000 ||
+        /\\/.test(clean) ||
+        [...clean].some((c) => c.charCodeAt(0) < 0x20 || c.charCodeAt(0) === 0x7f) ||
+        segs.some((s) => s === "" || s === "." || s === "..");
+    if (bad) {
+        throw new McpToolInputError(`"vault_path" must be a relative vault key without traversal (got ${JSON.stringify(p)})`);
+    }
+    if (segs[0] === "companies") {
+        throw new McpToolInputError(`"vault_path" is scope-relative (e.g. chat/attachments/dm/<id>/<file>); pass it exactly as hq_inbox_read returned it, without companies/<slug>/`);
+    }
+    if (!clean.startsWith(CHAT_ATTACHMENT_PREFIX)) {
+        throw notChatAttachment(p);
+    }
+    return clean;
+}
+/** Throws unless `scopeUid` is a well-formed cmp_/prs_ uid. No network. */
+export function assertAttachmentScopeUid(scopeUid) {
+    if (!SCOPE_UID.test(scopeUid)) {
+        throw new McpToolInputError(`"company_uid" must be a cmp_… or prs_… uid from hq_inbox_read (got ${JSON.stringify(scopeUid)})`);
+    }
+}
+/**
+ * The checks that need no network: uid format, DM-pair membership for any
+ * `chat/attachments/dm/…` key, and the prs_ scope rule. Run before resolving
+ * the bot's company so a refused ref never costs (or leaks) a request.
+ */
+export function assertAttachmentRef(input) {
+    const { scopeUid, key, botEntityUid } = input;
+    assertAttachmentScopeUid(scopeUid);
+    const isDmKey = key.startsWith(`${CHAT_ATTACHMENT_PREFIX}dm/`);
+    const m = DM_KEY.exec(key);
+    const members = m ? m[1].split("--") : [];
+    const botInPair = members.length === 2 && members.includes(botEntityUid);
+    if (isDmKey && !botInPair) {
+        throw new McpToolInputError(`a DM attachment is only readable by a member of that DM; this agent (${botEntityUid}) is not in ${JSON.stringify(key.split("/")[3] ?? "")}`);
+    }
+    if (scopeUid.startsWith("prs_") && !(m && botInPair && members.includes(scopeUid))) {
+        throw new McpToolInputError(`a personal-vault attachment is only readable when it is a DM between that person and this agent (chat/attachments/dm/<uid>--<uid>/…)`);
+    }
+}
+/**
+ * Tenant gate. Throws unless the scope is this bot's own company, or a
+ * person vault holding a DM attachment between that person and this bot.
+ */
+export function assertAttachmentScope(input) {
+    const { scopeUid, key, botCompanyUid, botEntityUid } = input;
+    assertAttachmentRef({ scopeUid, key, botEntityUid });
+    if (scopeUid.startsWith("cmp_") && scopeUid !== botCompanyUid) {
+        throw new McpToolInputError(`attachment belongs to company ${scopeUid}; this agent is enrolled in ${botCompanyUid} and cannot read another company's files`);
+    }
+}
+/** Reduce an untrusted name to a safe single path component. */
+export function sanitizeAttachmentFileName(raw) {
+    const base = raw.trim().split(/[/\\]/).pop() ?? "";
+    const cleaned = base.replace(/[^\w.\- ()[\]]+/g, "_").replace(/^[.\s]+/, "");
+    return cleaned.slice(0, 180) || "file";
+}
+const TEXT_EXT = new Set(["csv", "tsv", "txt", "md", "json", "yaml", "yml", "xml", "html", "log"]);
+function renderText(buf, name, contentType) {
+    const ext = name.split(".").pop()?.toLowerCase() ?? "";
+    const textual = TEXT_EXT.has(ext) || (contentType ?? "").startsWith("text/") || contentType === "application/json";
+    if (!textual || buf.includes(0))
+        return undefined;
+    const text = buf.toString("utf8");
+    return text.length > MAX_ATTACHMENT_TEXT_CHARS
+        ? `${text.slice(0, MAX_ATTACHMENT_TEXT_CHARS)}\n… [truncated ${text.length - MAX_ATTACHMENT_TEXT_CHARS} chars; read the local file for the rest]`
+        : text;
+}
+/**
+ * Download `key` from `scopeUid` and write it privately under `attachmentsDir`.
+ * `download` is the presign-backed reader; the caller has already gated scope.
+ */
+export async function saveAttachment(input) {
+    const { attachmentsDir, scopeUid, key } = input;
+    const bytes = await input.download(scopeUid, key);
+    if (bytes.length > MAX_ATTACHMENT_BYTES) {
+        throw new Error(`attachment is ${bytes.length} bytes, over the ${MAX_ATTACHMENT_BYTES}-byte limit`);
+    }
+    const name = sanitizeAttachmentFileName(input.name || key.split("/").pop() || "file");
+    const dir = path.join(attachmentsDir, sanitizeAttachmentFileName(scopeUid));
+    for (const d of [attachmentsDir, dir]) {
+        fs.mkdirSync(d, { recursive: true, mode: 0o700 });
+        fs.chmodSync(d, 0o700);
+    }
+    // A short digest of scope+key keeps two same-named files apart and makes a
+    // re-fetch of the same attachment overwrite rather than pile up.
+    const digest = createHash("sha256").update(`${scopeUid}\0${key}`).digest("hex").slice(0, 12);
+    const localPath = path.join(dir, `${digest}-${name}`);
+    if (path.dirname(localPath) !== dir)
+        throw new Error("refusing to write outside the attachments directory");
+    const tmp = `${localPath}.${process.pid}.tmp`;
+    try {
+        fs.writeFileSync(tmp, bytes, { mode: 0o600 });
+        fs.chmodSync(tmp, 0o600);
+        fs.renameSync(tmp, localPath);
+    }
+    catch (err) {
+        // Never leave a partial copy of the attachment behind.
+        fs.rmSync(tmp, { force: true });
+        throw err;
+    }
+    const ext = name.split(".").pop()?.toLowerCase() ?? "";
+    const text = renderText(bytes, name, input.contentType);
+    const note = text !== undefined
+        ? undefined
+        : ext === "xlsx" || ext === "xls"
+            ? "Spreadsheet saved locally; open localPath with a spreadsheet library (e.g. openpyxl / pandas) to read the sheets."
+            : "Binary file saved locally; open localPath with a suitable tool.";
+    return {
+        localPath,
+        name,
+        ...(input.contentType ? { contentType: input.contentType } : {}),
+        sizeBytes: bytes.length,
+        vaultPath: key,
+        companyUid: scopeUid,
+        ...(text !== undefined ? { text } : {}),
+        ...(note ? { note } : {}),
+    };
+}
+//# sourceMappingURL=attachments.js.map

package/dist/lib/agent-kit/mcp/tools.d.ts

@@ -25,8 +25,11 @@ export interface HqRunResult {
 }
 export interface McpToolClients {
     creds: ExternalMachineCreds;
-    /** Kit layout; the inbox tools read the mirror and done-state here. */
-    paths: Pick<AgentKitPaths, "inboxDir">;
+    /**
+     * Kit layout; the inbox tools read the mirror and done-state here, and
+     * `hq_attachment_fetch` writes downloaded attachments under attachmentsDir.
+     */
+    paths: Pick<AgentKitPaths, "inboxDir" | "attachmentsDir">;
     /** Run `hq <args…>` as the machine identity; never throws. */
     runHq: (args: string[]) => Promise<HqRunResult>;
     getToken: () => Promise<string>;
@@ -37,6 +40,13 @@ export interface McpToolClients {
      * match on file names and paths, not on contents.
      */
     syncFiles?: boolean;
+    /** The cmp_ uid of this agent's enrolled company (creds.companySlug). */
+    resolveCompanyUid: () => Promise<string>;
+    /**
+     * Read one vault object's bytes by scope uid (cmp_/prs_) + scope-relative
+     * key through the presign API, as the machine identity.
+     */
+    downloadVaultObject: (scopeUid: string, key: string) => Promise<Buffer>;
     /** Authenticated JSON call against the control plane. */
     apiJson: (token: string, path: string, init?: {
         method?: string;
@@ -48,6 +58,7 @@ export interface McpToolClients {
     }>;
 }
 export declare const MAX_TOOL_OUTPUT_CHARS = 40000;
+export declare const ATTACHMENTS_HINT: string;
 export declare function clampOutput(text: string, max?: number): string;
 /** Vault paths are company-anchored and must not escape. */
 export declare function assertVaultPath(p: string): string;

package/dist/lib/agent-kit/mcp/tools.js

@@ -19,8 +19,12 @@ import { CLI_VERSION } from "../../../cli-version.js";
 import { peekIdToken } from "../../../utils/id-token.js";
 import { isRecipientUid } from "../../../lib/notify-recipient.js";
 import { markInboxDone, mergeAgentInbox, readDoneIds, summarizeInboxEntry } from "../inbox-state.js";
+import { assertAttachmentKey, assertAttachmentRef, assertAttachmentScope, saveAttachment } from "./attachments.js";
 import { errorResult, McpToolInputError, textResult } from "./jsonrpc.js";
 export const MAX_TOOL_OUTPUT_CHARS = 40_000;
+export const ATTACHMENTS_HINT = "Some messages carry files. For each entry in a message's `attachments` whose vaultPath starts with chat/attachments/, " +
+    "call hq_attachment_fetch with that vaultPath and companyUid to download it; hq_files_read cannot open message attachments. " +
+    "Anything else (a folder or shared vault path) is not a chat attachment: use hq_files_list / hq_files_read for those.";
 function str(args, key, opts = {}) {
     const v = args[key];
     if (v === undefined || v === null) {
@@ -148,7 +152,8 @@ export function buildAgentMcpTools(clients) {
         },
         {
             name: "hq_files_read",
-            description: "Read one vault file's contents (hq files cat). Text files only; output is truncated at 40k chars.",
+            description: "Read one company vault file's contents (hq files cat). Text files only; output is truncated at 40k chars. " +
+                "For files attached to an HQ message use hq_attachment_fetch instead.",
             inputSchema: {
                 type: "object",
                 properties: { path: { type: "string", description: "companies/<slug>/<file>" } },
@@ -239,7 +244,8 @@ export function buildAgentMcpTools(clients) {
         {
             name: "hq_inbox_read",
             description: "Read this agent's HQ inbox (DMs, channel mentions, jobs), oldest first. By default only items not yet " +
-                "marked handled. Reply with hq_dm_send, then mark each one handled with hq_inbox_done so it is never answered twice.",
+                "marked handled. Items with `attachments` carry files: download each with hq_attachment_fetch (pass its vaultPath " +
+                "and companyUid) when its vaultPath is under chat/attachments/ before answering. Reply with hq_dm_send, then mark each one handled with hq_inbox_done so it is never answered twice.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -262,7 +268,64 @@ export function buildAgentMcpTools(clients) {
                     .filter((e) => includeDone || !done.has(e.id))
                     .slice(0, limit)
                     .map((e) => summarizeInboxEntry(e, done.has(e.id)));
-                return textResult(clampOutput(JSON.stringify({ count: rows.length, messages: rows, ...(serverNote ? { note: serverNote } : {}) }, null, 2)));
+                const hasFiles = rows.some((r) => r.attachments?.length);
+                return textResult(clampOutput(JSON.stringify({
+                    count: rows.length,
+                    messages: rows,
+                    ...(serverNote ? { note: serverNote } : {}),
+                    ...(hasFiles ? { attachmentsHint: ATTACHMENTS_HINT } : {}),
+                }, null, 2)));
+            },
+        },
+        {
+            name: "hq_attachment_fetch",
+            description: "Download a file attached to an HQ chat message (from hq_inbox_read `attachments`, vaultPath under chat/attachments/) " +
+                "to a private local file and return its localPath, contentType and size. Text-like files (csv, txt, json, …) also come back inline, bounded. " +
+                "Works for any type (xlsx, pdf, images): open localPath with a suitable tool. Only chat attachments in this agent's company, " +
+                "or in a DM with this agent; for other vault files or folders use hq_files_list / hq_files_read.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    vault_path: { type: "string", description: "attachments[].vaultPath exactly as hq_inbox_read returned it (chat/attachments/…)" },
+                    company_uid: { type: "string", description: "attachments[].companyUid (cmp_… or prs_…)" },
+                    name: { type: "string", description: "attachments[].name (optional; used for the local file name)" },
+                    content_type: { type: "string", description: "attachments[].contentType (optional)" },
+                },
+                required: ["vault_path", "company_uid"],
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                const key = assertAttachmentKey(str(args, "vault_path", { required: true, max: 1000 }));
+                const scopeUid = str(args, "company_uid", { required: true, max: 220 }).trim();
+                const name = str(args, "name", { max: 500 });
+                const contentType = str(args, "content_type", { max: 200 });
+                // Format, DM-pair and prs_ checks need no network: refuse bad refs
+                // before resolving the company (a lookup that sends the bot's token).
+                assertAttachmentRef({ scopeUid, key, botEntityUid: creds.entityUid });
+                if (scopeUid.startsWith("cmp_")) {
+                    let botCompanyUid;
+                    try {
+                        botCompanyUid = await clients.resolveCompanyUid();
+                    }
+                    catch (err) {
+                        return errorResult(`could not resolve this agent's company: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                    assertAttachmentScope({ scopeUid, key, botCompanyUid, botEntityUid: creds.entityUid });
+                }
+                try {
+                    const result = await saveAttachment({
+                        attachmentsDir: clients.paths.attachmentsDir,
+                        scopeUid,
+                        key,
+                        name,
+                        contentType,
+                        download: clients.downloadVaultObject,
+                    });
+                    return textResult(clampOutput(JSON.stringify(result, null, 2)));
+                }
+                catch (err) {
+                    return errorResult(`attachment fetch failed: ${err instanceof Error ? err.message : String(err)}`);
+                }
             },
         },
         {

package/dist/lib/agent-kit/paths.d.ts

@@ -7,6 +7,7 @@
  *   ~/.hq-agent/kit.json             kit install settings (hq root, intervals)
  *   ~/.hq-agent/state/               component-{sync,mesh,inbox}, last-heartbeat.json
  *   ~/.hq-agent/inbox/               mirrored inbox items (one JSON per message)
+ *   ~/.hq-agent/attachments/<scope>/ message attachments fetched on demand (0700 / 0600)
  *   ~/.hq-agent/logs/*.log           one log per kit service
  *   ~/.hq-agent/skills/<name>/SKILL.md
  *
@@ -39,6 +40,8 @@ export interface AgentKitPaths {
     kitConfigPath: string;
     stateDir: string;
     inboxDir: string;
+    /** Private (0700) home for message attachments fetched by hq_attachment_fetch. */
+    attachmentsDir: string;
     logsDir: string;
     skillsDir: string;
     lastHeartbeatPath: string;

package/dist/lib/agent-kit/paths.js

@@ -7,6 +7,7 @@
  *   ~/.hq-agent/kit.json             kit install settings (hq root, intervals)
  *   ~/.hq-agent/state/               component-{sync,mesh,inbox}, last-heartbeat.json
  *   ~/.hq-agent/inbox/               mirrored inbox items (one JSON per message)
+ *   ~/.hq-agent/attachments/<scope>/ message attachments fetched on demand (0700 / 0600)
  *   ~/.hq-agent/logs/*.log           one log per kit service
  *   ~/.hq-agent/skills/<name>/SKILL.md
  *
@@ -102,6 +103,7 @@ export function agentKitPaths(home = os.homedir(), env = process.env) {
         kitConfigPath: path.join(dir, KIT_CONFIG_NAME),
         stateDir,
         inboxDir: path.join(dir, "inbox"),
+        attachmentsDir: path.join(dir, "attachments"),
         logsDir: path.join(dir, "logs"),
         skillsDir: path.join(dir, "skills"),
         lastHeartbeatPath: path.join(stateDir, LAST_HEARTBEAT_NAME),

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

@@ -4,8 +4,8 @@
  * 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 whether a provider credential file EXISTS — this module
- * never reads, prints, copies, or hashes that file.
+ * derived from credential-file existence or a provider status command; this
+ * module never reads, prints, copies, or hashes credential files.
  */
 import { type LaneRecord, type LaneProvider } from "./types.js";
 import type { LanesConfig } from "./types.js";
@@ -19,13 +19,22 @@ export declare const CLAUDE_CREDENTIALS_NAME = ".credentials.json";
  * file here at all.
  */
 export declare const PROVIDER_CREDENTIAL_FILES: Record<LaneProvider, readonly string[]>;
-export type AuthState = "file" | "absent" | "unknown";
+export type AuthState = "file" | "status" | "absent" | "unknown";
+export interface AccountStatusProbeResult {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+}
 export interface AccountDeps {
     existsSync: (p: string) => boolean;
+    /** 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;
 }
 export interface AccountResolveContext {
     hqRoot?: string;
     existsSync?: (p: string) => boolean;
+    accountDeps?: Omit<AccountDeps, "existsSync">;
     loadLanes?: (hqRoot: string) => LaneRecord[];
     /** Already-resolved model for this lane. Beats cliModel and account defaults. */
     model?: string;
@@ -38,6 +47,8 @@ export interface AccountResolveContext {
      * set is never selected, so no refusal has to be decided under the lock.
      */
     allowedAccounts?: readonly string[];
+    /** Ordered preferences; callers pass these only for a new lane's first assignment. */
+    preferredAccounts?: readonly string[];
 }
 export interface ResolvedAccount {
     provider: LaneProvider;
@@ -54,13 +65,7 @@ export interface AccountStatus {
     disabled_reason?: string;
     /** Present in personal/lanes/config.json. */
     configured: boolean;
-    /**
-     * 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.
-     */
+    /** True/false comes from file existence or the provider status command. */
     logged_in: boolean | null;
     auth_state: AuthState;
     envVar: string;
@@ -79,7 +84,7 @@ 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;
-/** Auto-select requires a proven credential file, not Claude-unknown. */
+/** Auto-select requires a positive file or provider-status login result. */
 export declare function isCredentialProven(status: Pick<AccountStatus, "logged_in">): boolean;
 /**
  * Occupying states hold a slot: running / awaiting_input / blocked have a

package/dist/lib/lanes/accounts.js

@@ -4,8 +4,8 @@
  * 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 whether a provider credential file EXISTS — this module
- * never reads, prints, copies, or hashes that file.
+ * derived from credential-file existence or a provider status command; this
+ * module never reads, prints, copies, or hashes credential files.
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -76,7 +76,7 @@ export function loggedInFromAuthState(state) {
 export function isLoggedOut(status) {
     return status.logged_in === false;
 }
-/** Auto-select requires a proven credential file, not Claude-unknown. */
+/** Auto-select requires a positive file or provider-status login result. */
 export function isCredentialProven(status) {
     return status.logged_in === true;
 }
@@ -205,8 +205,12 @@ export function selectBalancedAccount(provider, config, ctx = {}) {
     }
     const proven = [];
     for (const id of enabled) {
-        const account = providerCfg.accounts[id];
-        if (hasCredentialFile(provider, account.home, existsSync))
+        const status = accountStatus(provider, id, config, {
+            existsSync,
+            ...(ctx.accountDeps?.probe ? { probe: ctx.accountDeps.probe } : {}),
+            ...(ctx.accountDeps?.env ? { env: ctx.accountDeps.env } : {}),
+        });
+        if (status.logged_in === true)
             proven.push(id);
     }
     if (proven.length === 0) {
@@ -235,6 +239,9 @@ export function selectBalancedAccount(provider, config, ctx = {}) {
         const cap = accountMaxRunning(providerCfg, id);
         return runningLaneCount(lanes, provider, id) < cap;
     });
+    const preferred = underCap.length > 0
+        ? ctx.preferredAccounts?.find((id) => underCap.includes(id))
+        : undefined;
     const pool = underCap.length > 0 ? underCap : runnable;
     const ranked = pool
         .map((id) => ({
@@ -243,7 +250,7 @@ export function selectBalancedAccount(provider, config, ctx = {}) {
         lastStarted: lastStartedAt(lanes, provider, id),
     }))
         .sort(compareEligible);
-    const chosen = ranked[0].id;
+    const chosen = preferred ?? ranked[0].id;
     return boundAccount(provider, chosen, providerCfg.accounts[chosen]);
 }
 export function resolveAccount(provider, requestedId, config, ctx = {}) {
@@ -293,14 +300,28 @@ export function accountStatus(provider, accountId, config, deps = defaultAccount
         };
     }
     const present = hasCredentialFile(provider, account.home, deps.existsSync);
-    const auth_state = authStateFor(provider, present);
+    let auth_state = authStateFor(provider, present);
+    let logged_in = loggedInFromAuthState(auth_state);
+    if (!present && provider === "claude" && deps.probe !== undefined) {
+        try {
+            const result = deps.probe("claude", ["auth", "status"], { ...(deps.env ?? process.env), CLAUDE_CONFIG_DIR: account.home });
+            const providerStatus = claudeLoginStatus(result);
+            if (providerStatus !== null) {
+                auth_state = "status";
+                logged_in = providerStatus;
+            }
+        }
+        catch {
+            process.stderr.write(`hq lanes: Claude auth status probe failed for account ${accountId}\n`);
+        }
+    }
     const status = {
         provider,
         id: accountId,
         home: account.home,
         enabled: account.enabled,
         configured: true,
-        logged_in: loggedInFromAuthState(auth_state),
+        logged_in,
         auth_state,
         envVar,
     };
@@ -312,6 +333,27 @@ export function accountStatus(provider, accountId, config, deps = defaultAccount
 export function listAccountStatuses(provider, config, deps = defaultAccountDeps()) {
     return Object.keys(config.providers[provider].accounts).map((id) => accountStatus(provider, id, config, deps));
 }
+function claudeLoginStatus(result) {
+    const text = result.stdout.trim();
+    if (text.startsWith("{")) {
+        try {
+            const parsed = JSON.parse(text);
+            if (parsed !== null &&
+                typeof parsed === "object" &&
+                !Array.isArray(parsed) &&
+                typeof parsed.loggedIn === "boolean") {
+                return parsed.loggedIn;
+            }
+        }
+        catch (err) {
+            process.stderr.write(`hq lanes: Claude auth status returned invalid JSON: ${err instanceof Error ? err.message : String(err)}\n`);
+            return null;
+        }
+    }
+    if (/\bnot logged in\b/i.test(`${result.stdout}\n${result.stderr}`))
+        return false;
+    return null;
+}
 /** Environment assignment the worker process should receive. */
 export function accountEnv(resolved) {
     return { [resolved.envVar]: resolved.home };

package/dist/lib/lanes/admission-host.d.ts

@@ -0,0 +1,19 @@
+import type { AdmissionHost } from "./admission.js";
+export declare const OUTPOST_ID_PATH = "/etc/outpost/outpost-id";
+export declare const OUTPOST_DIR = "/etc/outpost";
+export type OutpostIdentity = {
+    kind: "id";
+    id: string;
+} | {
+    kind: "unknown";
+} | {
+    kind: "not_outpost";
+};
+export declare function readOutpostIdentity(existsSync?: (p: string) => boolean, readFileSync?: (p: string) => string): OutpostIdentity;
+export declare function resolveAdmissionHost(deps?: {
+    hostname?: () => string;
+    readOutpostIdentity?: () => OutpostIdentity;
+    existsSync?: (p: string) => boolean;
+    readFileSync?: (p: string) => string;
+}): AdmissionHost;
+//# sourceMappingURL=admission-host.d.ts.map

package/dist/lib/lanes/admission-host.js

@@ -0,0 +1,33 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+export const OUTPOST_ID_PATH = "/etc/outpost/outpost-id";
+export const OUTPOST_DIR = "/etc/outpost";
+export function readOutpostIdentity(existsSync = (p) => fs.existsSync(p), readFileSync = (p) => fs.readFileSync(p, "utf8")) {
+    const hasMarker = existsSync(OUTPOST_ID_PATH);
+    const hasDir = existsSync(OUTPOST_DIR);
+    if (hasMarker) {
+        let text;
+        try {
+            text = readFileSync(OUTPOST_ID_PATH);
+        }
+        catch (err) {
+            process.stderr.write(`hq lanes: failed to read ${OUTPOST_ID_PATH}: ${err instanceof Error ? err.message : String(err)}\n`);
+            throw err;
+        }
+        const id = text.trim();
+        if (!id)
+            return hasDir ? { kind: "unknown" } : { kind: "not_outpost" };
+        return { kind: "id", id };
+    }
+    if (hasDir)
+        return { kind: "unknown" };
+    return { kind: "not_outpost" };
+}
+export function resolveAdmissionHost(deps = {}) {
+    const identity = deps.readOutpostIdentity?.() ?? readOutpostIdentity(deps.existsSync, deps.readFileSync);
+    return {
+        hostname: (deps.hostname ?? os.hostname)(),
+        outpostId: identity.kind === "id" ? identity.id : null,
+    };
+}
+//# sourceMappingURL=admission-host.js.map

package/dist/lib/lanes/config.js

@@ -173,6 +173,29 @@ function parseFastModeModels(value, field) {
     }
     return value.map((model) => model.trim());
 }
+function parsePreferredAccounts(provider, value, accounts) {
+    const field = `providers.${provider}.preferred_accounts`;
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) ||
+        value.some((id) => typeof id !== "string" ||
+            id.trim().length === 0 ||
+            id.trim() !== id)) {
+        throw new LanesConfigError("invalid_preferred_accounts", `${field} must be an array of non-empty account ids without surrounding whitespace`, { provider, field });
+    }
+    const preferred = value;
+    const seen = new Set();
+    for (const id of preferred) {
+        if (seen.has(id)) {
+            throw new LanesConfigError("invalid_preferred_accounts", `${field} contains duplicate account ${JSON.stringify(id)}`, { provider, field, account: id });
+        }
+        if (accounts[id] === undefined) {
+            throw new LanesConfigError("preferred_account_unconfigured", `${field} names unconfigured account ${JSON.stringify(id)}`, { provider, field, account: id, accounts: Object.keys(accounts) });
+        }
+        seen.add(id);
+    }
+    return [...preferred];
+}
 function rejectDuplicateHomes(provider, accounts) {
     const seen = new Map();
     for (const [id, account] of Object.entries(accounts)) {
@@ -232,6 +255,7 @@ function parseProvider(provider, raw, deps) {
         max_running: positiveInt(raw.max_running, `providers.${provider}.max_running`, DEFAULT_PROVIDER_MAX_RUNNING[provider]),
         max_queued: positiveInt(raw.max_queued, `providers.${provider}.max_queued`, DEFAULT_MAX_QUEUED),
         accounts,
+        preferred_accounts: parsePreferredAccounts(provider, raw.preferred_accounts, accounts),
     };
     if (provider === "codex") {
         parsed.fast_mode_models = parseFastModeModels(raw.fast_mode_models, `providers.${provider}.fast_mode_models`);
@@ -301,6 +325,7 @@ export function documentedDefaultConfig(deps = defaultDeps()) {
             max_running: DEFAULT_PROVIDER_MAX_RUNNING[provider],
             max_queued: DEFAULT_MAX_QUEUED,
             accounts: defaultAccountMap(provider, deps),
+            preferred_accounts: [],
         };
         if (provider === "codex")
             providerConfig.fast_mode_models = [];

package/dist/lib/lanes/provider-rejection.d.ts

@@ -37,6 +37,7 @@ export interface ProviderRejection {
     /** Which event on the stream carried the failure. */
     event: "codex.turn.failed" | "claude.result.is_error" | "grok.error";
 }
+export declare function isProviderLoginFailure(failure: ProviderRejection | null): boolean;
 export declare function capMessage(message: string): string;
 /**
  * Whether a later run could succeed without the operator changing anything.
@@ -56,10 +57,9 @@ export declare function retryableFromStatus(status: number | null): boolean;
 export declare function parseCodexTurnFailed(text: string): ProviderRejection | null;
 /**
  * Claude `-p --output-format json`: the last `type: "result"` object with
- * `is_error: true` and a numeric `api_error_status`. A result that is an
- * error with no status is not a provider rejection: it is either the quota
- * text shape quota.ts reads, or the worker's own failure, and keeps the
- * existing classification.
+ * `is_error: true` and a numeric `api_error_status`, or the CLI's explicit
+ * unauthenticated message. Other status-less errors keep the existing
+ * classification because they may be quota text or a worker failure.
  */
 export declare function parseClaudeResultRejection(text: string): ProviderRejection | null;
 /**