@indigoai-us/hq-cli 5.345.176 → 5.345.178

package/dist/commands/cloud.js

@@ -22,7 +22,7 @@ import * as path from "path";
 import { share, getStateDir, listJournals, createIgnoreFilter, VaultClient, computePersonalVaultPaths, PERSONAL_VAULT_JOURNAL_SLUG, resolvePullScope, readSyncProgress, syncDoctor, } from "@indigoai-us/hq-cloud";
 import { syncLeg } from "../utils/sync-operation-lock.js";
 import { SYNC_WATCHDOG_EXIT_CODE, SYNC_WATCHDOG_REPORT_GRACE_MS, SyncWatchdogTimeoutError, createSnapshotProgressProbe, resolveSyncWatchdogLimits, withSyncWatchdog, } from "../utils/sync-watchdog.js";
-import { DEFAULT_HQ_ROOT, ensureCognitoToken, buildVaultConfig, loadCachedTokens, } from "../utils/cognito-session.js";
+import { DEFAULT_HQ_ROOT, ensureCognitoToken, buildVaultConfig, IdentitySwapRefusal, cognitoCachePrincipalUid, isDefinitivePersonAuthRejection, isIdentitySwapRefusal, loadCachedTokens, } from "../utils/cognito-session.js";
 import { resolveUploadAuthor } from "../utils/upload-author.js";
 import { companyFolderExceedsThreshold, emitNarrowHint, isStrictRefusal, resolveBannerLevel, resolveNarrowHintPresentationLevel, resolveNarrowHintMinBytes, } from "../lib/narrow-hint-banner.js";
 import { beginSyncHealthReport, classifySyncFailure, } from "../utils/client-health.js";
@@ -66,12 +66,130 @@ async function ensureSyncCognitoToken() {
         interactive: process.stdin.isTTY === true && process.stdout.isTTY === true,
     });
 }
+/** Shown when the session expires during a sync and cannot be renewed. */
+export const SYNC_SESSION_EXPIRED_MESSAGE = "Your HQ session expired during sync and could not be refreshed. Run `hq login`, then rerun the sync.";
+/** Shown when the refresh failed for a network or server reason. */
+export const SYNC_REFRESH_UNAVAILABLE_MESSAGE = "Could not refresh your HQ session during sync because the sign-in service did not respond. Check your connection, then rerun the sync.";
+/** Shown when the start token carries no principal to bind the run to. */
+export const SYNC_NO_IDENTITY_MESSAGE = "The HQ session token does not identify an account, so the sync did not start. Run `hq login`, then rerun the sync.";
+/** Shown when the token would change to a different account mid-run. */
+export const SYNC_IDENTITY_CHANGED_MESSAGE = "The signed-in HQ account changed while this sync was running, so the sync stopped instead of continuing as a different account. Rerun the sync as the account you want.";
+/**
+ * The session token expired during a sync run and the non-interactive
+ * refresh failed. `kind` separates a rejected session (sign in again) from a
+ * network or server failure (retry later).
+ */
+export class SyncSessionExpiredError extends Error {
+    kind;
+    reason;
+    constructor(kind, reason) {
+        const base = kind === "reauth" ? SYNC_SESSION_EXPIRED_MESSAGE : SYNC_REFRESH_UNAVAILABLE_MESSAGE;
+        super(reason ? `${base} (${reason})` : base);
+        this.kind = kind;
+        this.reason = reason;
+        this.name = "SyncSessionExpiredError";
+    }
+}
+/**
+ * Per-config record of the last token-function failure. hq-cloud's one-shot
+ * 401 retry swallows getter errors and rethrows the original 401, so
+ * {@link formatSyncFailure} reads this (given the run's config) to report the
+ * real cause. Keyed by config so two runs in one process never share a record.
+ */
+const syncAuthFailures = new WeakMap();
+/** The last token failure recorded by a {@link buildSyncVaultConfig} config. */
+export function syncAuthFailureFor(config) {
+    return config ? (syncAuthFailures.get(config)?.() ?? null) : null;
+}
+function classifyRefreshFailure(err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    const reauth = isDefinitivePersonAuthRejection(err) ||
+        /No valid HQ session|Run `hq login`/i.test(reason);
+    return new SyncSessionExpiredError(reauth ? "reauth" : "unavailable", reason);
+}
+/**
+ * Vault config for a sync run whose token stays valid for the whole run.
+ *
+ * `initialToken` is resolved (and, on a TTY, logged in) before the run starts.
+ * The config carries a getter instead of that string, so every vault request
+ * re-reads the cached session and refreshes it when it is close to expiry.
+ * When a request still gets a 401, hq-cloud's VaultClient calls the getter
+ * once more and retries once if the token changed (no loop). A multi-company
+ * `hq sync pull --all` can outlast the one-hour Cognito access token; a
+ * captured string made every later target fail with 401 (feedback_3d3fab0b).
+ *
+ * The getter is bound to the principal of `initialToken`. If a later token
+ * belongs to a different principal (a mid-run `hq login` as another account,
+ * or the machine-identity fallback after a rejected person refresh), it throws
+ * an {@link IdentitySwapRefusal} and the run stops. It never continues as a
+ * different principal.
+ *
+ * Mid-run refreshes never open a browser.
+ */
+export function buildSyncVaultConfig(initialToken, deps = {}) {
+    const ensureToken = deps.ensureToken ?? (() => ensureCognitoToken({ interactive: false }));
+    const runPrincipal = cognitoCachePrincipalUid(initialToken);
+    // A start token with no sub/entityUid cannot be bound to a principal, and a
+    // null binding would accept any later identity-less token. Refuse up front.
+    if (runPrincipal === null) {
+        throw new IdentitySwapRefusal(SYNC_NO_IDENTITY_MESSAGE);
+    }
+    let refused = null;
+    let lastSyncAuthFailure = null;
+    const authToken = async () => {
+        // Once refused, stay refused for the rest of the run.
+        if (refused)
+            throw refused;
+        let token;
+        try {
+            token = await ensureToken();
+        }
+        catch (err) {
+            const failure = isIdentitySwapRefusal(err) ? err : classifyRefreshFailure(err);
+            if (isIdentitySwapRefusal(failure))
+                refused = failure;
+            lastSyncAuthFailure = failure;
+            throw failure;
+        }
+        if (cognitoCachePrincipalUid(token) !== runPrincipal) {
+            refused = new IdentitySwapRefusal(SYNC_IDENTITY_CHANGED_MESSAGE);
+            lastSyncAuthFailure = refused;
+            throw refused;
+        }
+        lastSyncAuthFailure = null;
+        return token;
+    };
+    const config = { ...buildVaultConfig(initialToken), authToken };
+    syncAuthFailures.set(config, () => lastSyncAuthFailure);
+    return config;
+}
+function isVaultAuthRejection(err) {
+    // Duck-typed (VaultAuthError sets statusCode 401) so this stays compatible
+    // across independently released hq-cloud versions.
+    if (typeof err !== "object" || err === null)
+        return false;
+    const e = err;
+    return e.name === "VaultAuthError" || e.statusCode === 401;
+}
 /**
  * Preserve the vault's typed write-scope refusal at the CLI boundary. This is
  * deliberately duck-typed so hq-cli remains compatible while hq-cloud and the
  * CLI are released independently.
  */
 export function formatSyncFailure(err, ctx = {}) {
+    if (err instanceof SyncSessionExpiredError || isIdentitySwapRefusal(err)) {
+        return err.message;
+    }
+    if (isVaultAuthRejection(err)) {
+        // hq-cloud's 401 retry swallowed the token-function error; report it.
+        const recorded = syncAuthFailureFor(ctx.vaultConfig);
+        if (recorded)
+            return recorded.message;
+        // A 401 that survived the one refresh-and-retry: the session is no longer
+        // accepted, so the fix is a fresh sign-in.
+        const base = err instanceof Error ? err.message : String(err);
+        return `${base}. ${SYNC_SESSION_EXPIRED_MESSAGE}`;
+    }
     const unreachable = formatUnreachablePushPaths(err, ctx);
     if (unreachable)
         return unreachable;
@@ -694,7 +812,7 @@ export async function pullAll(options, deps) {
             }
         }
         catch (err) {
-            const message = formatSyncFailure(err);
+            const message = (deps.formatFailure ?? formatSyncFailure)(err);
             result.errors.push({ company: entry.slug, message });
             result.perCompany.push({ slug: entry.slug, error: message });
         }
@@ -823,7 +941,7 @@ export async function pushAll(options, deps) {
             });
         }
         catch (err) {
-            const message = formatSyncFailure(err);
+            const message = (deps.formatFailure ?? formatSyncFailure)(err);
             result.errors.push({ company: entry.slug, message });
             result.perCompany.push({ slug: entry.slug, error: message });
         }
@@ -1126,6 +1244,8 @@ export function registerCloudCommands(program) {
         // Assigned right before the sync engine runs, so option-validation
         // failures never count as a sync attempt (US-003).
         let syncHealth;
+        /** The run's vault config, so the catch can report its recorded token failure. */
+        let runVaultConfig;
         let explicitPersonalPaths;
         // Company folder the push resolves relative paths against; names the
         // .hqinclude line and the blocked path in failure output.
@@ -1172,11 +1292,13 @@ export function registerCloudCommands(program) {
                 // Upload creds are pre-vended in entityContext, but prefix filtering
                 // still needs vault-service membership/grant resolution.
                 const accessToken = await ensureSyncCognitoToken();
-                scopeVaultConfig = buildVaultConfig(accessToken);
+                scopeVaultConfig = buildSyncVaultConfig(accessToken);
+                runVaultConfig = scopeVaultConfig;
             }
             else {
                 const accessToken = await ensureSyncCognitoToken();
-                vaultConfig = buildVaultConfig(accessToken);
+                vaultConfig = buildSyncVaultConfig(accessToken);
+                runVaultConfig = vaultConfig;
                 scopeVaultConfig = vaultConfig;
             }
             // Resolve the target. For `--personal`, look up the caller's
@@ -1426,6 +1548,7 @@ export function registerCloudCommands(program) {
             const message = formatSyncFailure(err, {
                 hqRoot: options.hqRoot,
                 companySlug: pushCompanySlug,
+                vaultConfig: runVaultConfig,
             });
             if (jsonMode) {
                 // In JSON mode, the parent process is parsing stderr for ndjson —
@@ -1493,12 +1616,15 @@ export function registerCloudCommands(program) {
             return;
         }
         let syncHealth;
+        /** The run's vault config, so the catch can report its recorded token failure. */
+        let runVaultConfig;
         try {
             console.log(chalk.bold("\nHQ Sync — Pull"));
             console.log(`  HQ root:  ${options.hqRoot}`);
             console.log(`  Company:  ${options.company ?? "(from .hq/config.json)"}\n`);
             const accessToken = await ensureSyncCognitoToken();
-            const vaultConfig = buildVaultConfig(accessToken);
+            const vaultConfig = buildSyncVaultConfig(accessToken);
+            runVaultConfig = vaultConfig;
             // US-011 (2026-05-21 fix): resolve the caller's sync-config for
             // the targeted membership BEFORE the pull, so we can (a) emit the
             // narrow-hint banner after success if still on all-mode and
@@ -1581,7 +1707,7 @@ export function registerCloudCommands(program) {
         catch (err) {
             if (syncHealth)
                 await syncHealth.failed();
-            const message = formatSyncFailure(err);
+            const message = formatSyncFailure(err, { vaultConfig: runVaultConfig });
             console.error(chalk.red("\n✗ Pull failed:"), message);
             process.exit(1);
         }
@@ -1843,9 +1969,12 @@ async function runPullAll(hqRoot, onConflict, modeAllOverride, skipPersonal, for
     logVaultSkips(skipPersonal, skipCompanies);
     console.log("");
     let result;
+    /** The run's vault config, so the catch can report its recorded token failure. */
+    let runVaultConfig;
     try {
         const accessToken = await ensureSyncCognitoToken();
-        const vaultConfig = buildVaultConfig(accessToken);
+        const vaultConfig = buildSyncVaultConfig(accessToken);
+        runVaultConfig = vaultConfig;
         const realClient = new VaultClient(vaultConfig);
         const adapter = {
             listMyMemberships: () => realClient.listMyMemberships(),
@@ -1871,6 +2000,7 @@ async function runPullAll(hqRoot, onConflict, modeAllOverride, skipPersonal, for
             ...(skipCompanies && skipCompanies.size > 0 ? { skipCompanies } : {}),
         }, {
             vaultClient: adapter,
+            formatFailure: (err) => formatSyncFailure(err, { vaultConfig }),
             // DEV-1768: resolve each company's REAL pull scope (mode + prefixSet)
             // via the shared resolver, so the actual pull is scoped — the CLI no
             // longer seeds an all-mode PullRecord that wedges the menubar runner.
@@ -1898,7 +2028,7 @@ async function runPullAll(hqRoot, onConflict, modeAllOverride, skipPersonal, for
         });
     }
     catch (err) {
-        console.error(chalk.red("\n✗ Pull-all failed:"), describeSyncError(err));
+        console.error(chalk.red("\n✗ Pull-all failed:"), formatSyncFailure(err, { vaultConfig: runVaultConfig }));
         // Unwind (never process.exit) so withSyncHealthReport records the
         // terminal sync_failure before exiting on our behalf.
         throw new SyncExitError(1);
@@ -1937,9 +2067,12 @@ export async function runPullPersonal(hqRoot, onConflict) {
     console.log(chalk.bold("\nHQ Sync — Pull (personal)"));
     console.log(`  HQ root:  ${hqRoot}`);
     console.log(`  Strategy: ${onConflict ?? "(interactive)"}\n`);
+    /** The run's vault config, so the catch can report its recorded token failure. */
+    let runVaultConfig;
     try {
         const accessToken = await ensureSyncCognitoToken();
-        const vaultConfig = buildVaultConfig(accessToken);
+        const vaultConfig = buildSyncVaultConfig(accessToken);
+        runVaultConfig = vaultConfig;
         const client = new VaultClient(vaultConfig);
         const personalUid = await resolveCanonicalPersonUid({
             listMyMemberships: () => client.listMyMemberships(),
@@ -1967,7 +2100,7 @@ export async function runPullPersonal(hqRoot, onConflict) {
     catch (err) {
         if (err instanceof SyncExitError)
             throw err;
-        console.error(chalk.red("\n✗ Pull (personal) failed:"), describeSyncError(err));
+        console.error(chalk.red("\n✗ Pull (personal) failed:"), formatSyncFailure(err, { vaultConfig: runVaultConfig }));
         throw new SyncExitError(1);
     }
 }
@@ -1983,9 +2116,12 @@ async function runPushAll(hqRoot, message, onConflict, skipPersonal, skipCompani
     logVaultSkips(skipPersonal, skipCompanies);
     console.log("");
     let result;
+    /** The run's vault config, so the catch can report its recorded token failure. */
+    let runVaultConfig;
     try {
         const accessToken = await ensureSyncCognitoToken();
-        const vaultConfig = buildVaultConfig(accessToken);
+        const vaultConfig = buildSyncVaultConfig(accessToken);
+        runVaultConfig = vaultConfig;
         const realClient = new VaultClient(vaultConfig);
         const author = resolveUploadAuthor();
         const adapter = {
@@ -2008,6 +2144,7 @@ async function runPushAll(hqRoot, message, onConflict, skipPersonal, skipCompani
             ...(skipCompanies && skipCompanies.size > 0 ? { skipCompanies } : {}),
         }, {
             vaultClient: adapter,
+            formatFailure: (err) => formatSyncFailure(err, { vaultConfig }),
             resolveScope: (companyUid, slug) => resolvePullScope(realClient, companyUid, slug, hqRoot),
             beforeShare: async ({ slug, companyUid, companyRoot }) => warnAboutInvalidOntologyEntities({
                 hqRoot,
@@ -2052,7 +2189,7 @@ async function runPushAll(hqRoot, message, onConflict, skipPersonal, skipCompani
         });
     }
     catch (err) {
-        console.error(chalk.red("\n✗ Push-all failed:"), describeSyncError(err));
+        console.error(chalk.red("\n✗ Push-all failed:"), formatSyncFailure(err, { vaultConfig: runVaultConfig }));
         // Unwind (never process.exit) so withSyncHealthReport records the
         // terminal sync_failure before exiting on our behalf.
         throw new SyncExitError(1);
@@ -2149,9 +2286,12 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
     console.log(`  HQ root:  ${hqRoot}`);
     console.log(`  Target:   ${personal ? "(personal)" : (company ?? "(active company)")}`);
     console.log(`  Strategy: ${onConflict ?? "(interactive)"}\n`);
+    /** The run's vault config, so the catch can report its recorded token failure. */
+    let runVaultConfig;
     try {
         const accessToken = await ensureSyncCognitoToken();
-        const vaultConfig = buildVaultConfig(accessToken);
+        const vaultConfig = buildSyncVaultConfig(accessToken);
+        runVaultConfig = vaultConfig;
         const author = resolveUploadAuthor();
         // Resolve the target. For --personal, look up the canonical person and
         // route paths/journal through personalMode. Otherwise use the company arg
@@ -2403,7 +2543,7 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
     catch (err) {
         if (err instanceof SyncExitError)
             throw err;
-        console.error(chalk.red("\n✗ Sync now failed:"), describeSyncError(err));
+        console.error(chalk.red("\n✗ Sync now failed:"), formatSyncFailure(err, { vaultConfig: runVaultConfig }));
         throw new SyncExitError(1);
     }
 }

package/dist/commands/dm-attach.js

@@ -18,7 +18,8 @@
  *
  * Network is injected (`presign`, `put`) so the sequence is unit-testable.
  */
-import { createReadStream, statSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
+import { Readable } from "node:stream";
 import path from "node:path";
 import { vaultApiFetch } from "../utils/vault-api.js";
 import { contentTypeFor, streamPut } from "./library-add.js";
@@ -89,7 +90,17 @@ export function validateAttachmentPaths(paths, stat = statSync) {
 }
 export const defaultAttachmentUploadDeps = {
     presign: (token, body) => vaultApiFetch({ token, path: "/v1/files/presign", method: "POST", body }),
-    put: (file, url, headers) => streamPut(url, headers, createReadStream(file.path), file.sizeBytes),
+    // Read the bytes once and declare their real length. Streaming with the
+    // size from validateAttachmentPaths' earlier stat sent a Content-Length the
+    // body could fall short of (file rewritten or truncated in between); S3 then
+    // waits ~20s and answers 400 RequestTimeout. Attachments are capped at 25 MB.
+    put: (file, url, headers) => {
+        const bytes = readFileSync(file.path);
+        if (bytes.length > MAX_DM_ATTACHMENT_BYTES) {
+            return Promise.reject(new Error(`Attachment too large: ${file.path} grew past the 25 MB limit after it was checked.`));
+        }
+        return streamPut(url, headers, Readable.from([bytes]), bytes.length);
+    },
 };
 /**
  * Presign-put every file into `scopeUid`, then return the `attachments[]`
@@ -138,7 +149,8 @@ export async function uploadDmAttachments(args) {
         }
         const put = await deps.put(p.file, row.url, headers);
         if (put.status < 200 || put.status >= 300) {
-            throw new Error(`Upload failed for ${p.file.path} (HTTP ${put.status}). The message was not sent.`);
+            const reason = [put.errorCode, put.errorMessage].filter(Boolean).join(": ");
+            throw new Error(`Upload failed for ${p.file.path} (HTTP ${put.status}${reason ? ` ${reason}` : ""}). The message was not sent.`);
         }
         out.push({
             vaultPath: p.key,

package/dist/commands/library-add.d.ts

@@ -19,7 +19,16 @@ export interface OpenedSource {
 export interface PutResponse {
     status: number;
     headers: Record<string, string | undefined>;
+    /** S3 `<Code>` from a non-2xx response body (e.g. `RequestTimeout`), when present. */
+    errorCode?: string;
+    /** S3 `<Message>` from a non-2xx response body, when present. */
+    errorMessage?: string;
 }
+/** Pull `<Code>` and `<Message>` out of an S3 XML error body. Pure. */
+export declare function parseS3Error(body: string): {
+    errorCode?: string;
+    errorMessage?: string;
+};
 export interface LibraryAddDeps {
     hqRoot: string;
     now: () => Date;

package/dist/commands/library-add.js

@@ -33,6 +33,14 @@ import { CONTENT_SHA256_METADATA_KEY, PLACEHOLDER_SUFFIX, companyOffloadKey, con
 import { formatPlanGateError, formatUpgradeRefusal, planGateErrorFromResponse, } from "../utils/plan-gate-error.js";
 /** Metadata key hq-pro binds to `checksumSha256` (sync's content hash). */
 const CONTENT_SHA256_META_KEY = CONTENT_SHA256_METADATA_KEY;
+/** Cap on how much of a non-2xx PUT response body is kept for the error reason. */
+const PUT_ERROR_BODY_LIMIT = 8 * 1024;
+/** Pull `<Code>` and `<Message>` out of an S3 XML error body. Pure. */
+export function parseS3Error(body) {
+    const code = /<Code>([^<]{1,200})<\/Code>/.exec(body)?.[1]?.trim();
+    const message = /<Message>([^<]{1,500})<\/Message>/.exec(body)?.[1]?.trim();
+    return { ...(code ? { errorCode: code } : {}), ...(message ? { errorMessage: message } : {}) };
+}
 const MEDIA_TYPES = {
     ".png": "image/png",
     ".jpg": "image/jpeg",
@@ -515,12 +523,21 @@ export function streamPut(url, headers, body, size) {
     return new Promise((resolve, reject) => {
         const target = new URL(url);
         const request = (target.protocol === "http:" ? http : https).request(target, { method: "PUT", headers: { ...headers, "content-length": String(size) } }, (res) => {
-            res.resume();
+            const status = res.statusCode ?? 0;
+            // Keep the start of a failure body so the caller can name S3's reason
+            // (RequestTimeout, EntityTooLarge, ...) instead of a bare status.
+            let errorBody = "";
+            res.setEncoding("utf8");
+            res.on("data", (chunk) => {
+                if ((status < 200 || status >= 300) && errorBody.length < PUT_ERROR_BODY_LIMIT) {
+                    errorBody += chunk.slice(0, PUT_ERROR_BODY_LIMIT - errorBody.length);
+                }
+            });
             res.on("end", () => {
                 const out = {};
                 for (const [k, v] of Object.entries(res.headers))
                     out[k] = Array.isArray(v) ? v.join(", ") : v;
-                resolve({ status: res.statusCode ?? 0, headers: out });
+                resolve({ status, headers: out, ...(errorBody ? parseS3Error(errorBody) : {}) });
             });
             res.on("error", reject);
         });

package/dist/commands/run.js

@@ -10,7 +10,7 @@ import { computeSha256 } from '../utils/integrity.js';
 import { isUnavailableSecretLoadHttpStatus, SecretLoadUnavailableError, } from '../utils/secret-load-availability.js';
 import { vaultApiFetch, getCompanyUid } from '../utils/vault-api.js';
 import { discoverSchemas } from '../run/discover-schemas.js';
-import { installHqPlugin, prewarmHqSecrets } from '../run/hq-plugin.js';
+import { installHqPlugin, itemIsOptional, prewarmHqSecrets } from '../run/hq-plugin.js';
 import { assertEnvGraphLoaded, resolveEnvValuesOrThrow, EnvGraphLoadError, EnvResolutionError, } from '../run/env-graph-guard.js';
 import { hadFatalRejection } from '../unhandled-rejection-boundary.js';
 import { withRunSecretReadTelemetry } from './run-feature-telemetry.js';
@@ -223,6 +223,14 @@ export function registerRunCommand(program) {
                 const schemaItems = Object.entries(graph.configSchema);
                 const itemMessages = (wantWarnings) => schemaItems.flatMap(([k, item]) => (item.errors ?? [])
                     .filter((e) => Boolean(e?.isWarning) === wantWarnings)
+                    .filter((e) => {
+                    if (wantWarnings)
+                        return true;
+                    if (!itemIsOptional(item))
+                        return true;
+                    const msg = e?.message ?? '';
+                    return !/No read permission|does not exist in company|not returned by vault/.test(msg);
+                })
                     .map((e) => `  ${k}: ${e?.message ?? String(e)}`));
                 const warningMsgs = itemMessages(true);
                 if (warningMsgs.length > 0) {

package/dist/lib/bot/config.d.ts

@@ -90,6 +90,8 @@ export interface BotConfig {
     ownerUid: string;
     runtime: BotRuntimeId;
     engine?: BotEngineMetadata;
+    fleetAuthPending?: boolean;
+    fleetServiceInstallPending?: boolean;
     /**
      * "personal" (acts as its owner everywhere) or "company" (acts as itself,
      * member of `companies`). Missing on bots created before kinds existed:

package/dist/lib/bot/fleet-default-flag.d.ts

@@ -0,0 +1,31 @@
+import { type FlagClient, type FlagClientOptions } from "@indigoai-us/hq-flags-client";
+/** Personal bots are created on the HQ Fleet Runtime for companies with this flag on. */
+export declare const LOCAL_BOTS_FLEET_DEFAULT_FLAG = "agents.local-bots-hq-fleet-default";
+export declare const LOCAL_BOTS_FLEET_DEFAULT_ENV = "HQ_BOT_FLEET_DEFAULT";
+type DefaultFlagClient = Pick<FlagClient, "ready" | "isEnabled" | "close">;
+export interface OwnerMembership {
+    companyUid: string;
+    companySlug?: string;
+    status: string;
+}
+export interface FleetDefaultFlagDependencies {
+    env?: NodeJS.ProcessEnv;
+    createClient?: (options: FlagClientOptions) => DefaultFlagClient;
+    getToken?: FlagClientOptions["getToken"];
+    fetch?: typeof fetch;
+    /** The signed-in owner's memberships; never prompts for sign-in. */
+    memberships?: () => Promise<OwnerMembership[]>;
+}
+/** Every active company the signed-in owner can access, independent of rollout flags or local folders. */
+export declare function fleetOwnerCompanies(dependencies?: Pick<FleetDefaultFlagDependencies, "memberships">): Promise<string[]>;
+/**
+ * The owner's companies that turned the fleet-default flag on: active
+ * memberships whose company folder is on this computer. Any lookup failure
+ * leaves that company out. `HQ_BOT_FLEET_DEFAULT=1` skips the flag and keeps
+ * every such membership.
+ */
+export declare function fleetDefaultCompanies(hqRoot: string, dependencies?: FleetDefaultFlagDependencies): Promise<string[]>;
+/** `HQ_BOT_FLEET_DEFAULT=1|0` overrides the registry; otherwise on when any flagged company was found. */
+export declare function fleetRuntimeIsDefault(flaggedCompanies: readonly string[], env?: NodeJS.ProcessEnv): boolean;
+export {};
+//# sourceMappingURL=fleet-default-flag.d.ts.map

package/dist/lib/bot/fleet-default-flag.js

@@ -0,0 +1,127 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { loadCachedTokens } from "@indigoai-us/hq-cloud";
+import { createFlagClient, } from "@indigoai-us/hq-flags-client";
+import { ensureCognitoToken } from "../../utils/cognito-session.js";
+import { vaultApiFetch } from "../../utils/vault-api.js";
+import { resolveFlagGate } from "../flag-registry.js";
+import { resolveFlagRegistryEndpoint } from "../flag-registry-endpoint.js";
+/** Personal bots are created on the HQ Fleet Runtime for companies with this flag on. */
+export const LOCAL_BOTS_FLEET_DEFAULT_FLAG = "agents.local-bots-hq-fleet-default";
+export const LOCAL_BOTS_FLEET_DEFAULT_ENV = "HQ_BOT_FLEET_DEFAULT";
+const FLAG_TIMEOUT_MS = 3_000;
+const MEMBERSHIP_TIMEOUT_MS = 10_000;
+const COMPANY_UID_RE = /^cmp_[A-Za-z0-9]{3,128}$/;
+const COMPANY_SLUG_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+async function signedInMemberships() {
+    const token = await ensureCognitoToken({ tokenSource: "person", interactive: false });
+    const res = await vaultApiFetch({ token, path: "/membership/me", signal: AbortSignal.timeout(MEMBERSHIP_TIMEOUT_MS) });
+    if (!res.ok)
+        throw new Error(`membership lookup returned ${res.status}`);
+    const data = (await res.json());
+    if (!Array.isArray(data.memberships))
+        throw new Error("membership lookup returned no list");
+    return data.memberships;
+}
+/** Every active company the signed-in owner can access, independent of rollout flags or local folders. */
+export async function fleetOwnerCompanies(dependencies = {}) {
+    const memberships = await (dependencies.memberships ?? signedInMemberships)();
+    const companies = new Set();
+    for (const membership of memberships) {
+        const slug = membership.companySlug?.trim() ?? "";
+        if (membership.status !== "active" || !COMPANY_UID_RE.test(membership.companyUid))
+            continue;
+        if (!COMPANY_SLUG_RE.test(slug) || slug === "personal")
+            continue;
+        companies.add(slug);
+    }
+    return [...companies].sort((a, b) => a.localeCompare(b));
+}
+function hasLocalFolder(hqRoot, slug) {
+    try {
+        const stat = fs.lstatSync(path.join(hqRoot, "companies", slug));
+        return stat.isDirectory() && !stat.isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The owner's companies that turned the fleet-default flag on: active
+ * memberships whose company folder is on this computer. Any lookup failure
+ * leaves that company out. `HQ_BOT_FLEET_DEFAULT=1` skips the flag and keeps
+ * every such membership.
+ */
+export async function fleetDefaultCompanies(hqRoot, dependencies = {}) {
+    const env = dependencies.env ?? process.env;
+    let memberships;
+    try {
+        memberships = await (dependencies.memberships ?? signedInMemberships)();
+    }
+    catch {
+        return [];
+    }
+    const candidates = new Map();
+    for (const membership of memberships) {
+        const slug = membership.companySlug?.trim() ?? "";
+        if (membership.status !== "active" || !COMPANY_UID_RE.test(membership.companyUid))
+            continue;
+        if (!COMPANY_SLUG_RE.test(slug) || slug === "personal" || !hasLocalFolder(hqRoot, slug))
+            continue;
+        candidates.set(slug, membership.companyUid);
+    }
+    const entries = [...candidates.entries()].sort(([a], [b]) => a.localeCompare(b));
+    const override = env[LOCAL_BOTS_FLEET_DEFAULT_ENV]?.trim();
+    if (override === "1" || override === "true")
+        return entries.map(([slug]) => slug);
+    const createClient = dependencies.createClient ?? createFlagClient;
+    const getToken = dependencies.getToken ?? (() => loadCachedTokens()?.idToken ?? "");
+    const endpoint = resolveFlagRegistryEndpoint(undefined, env);
+    const doFetch = dependencies.fetch ?? globalThis.fetch;
+    const flagOn = async (slug, companyUid) => {
+        let client;
+        let failed = false;
+        try {
+            client = createClient({
+                endpoint,
+                companyUid,
+                companyIdentifiers: [slug],
+                env: {},
+                getToken,
+                ...(doFetch ? { fetch: doFetch } : {}),
+                refreshIntervalMs: 0,
+                requestTimeoutMs: FLAG_TIMEOUT_MS,
+                onError: () => {
+                    failed = true;
+                },
+            });
+            await client.ready();
+            if (failed)
+                return false;
+            return resolveFlagGate(client, LOCAL_BOTS_FLEET_DEFAULT_FLAG, { fallback: false }, () => false);
+        }
+        catch {
+            return false;
+        }
+        finally {
+            try {
+                client?.close();
+            }
+            catch {
+                /* closing a flag client never changes the answer */
+            }
+        }
+    };
+    const results = await Promise.all(entries.map(([slug, uid]) => flagOn(slug, uid)));
+    return entries.filter((_, index) => results[index]).map(([slug]) => slug);
+}
+/** `HQ_BOT_FLEET_DEFAULT=1|0` overrides the registry; otherwise on when any flagged company was found. */
+export function fleetRuntimeIsDefault(flaggedCompanies, env = process.env) {
+    const override = env[LOCAL_BOTS_FLEET_DEFAULT_ENV]?.trim();
+    if (override === "1" || override === "true")
+        return true;
+    if (override === "0" || override === "false")
+        return false;
+    return flaggedCompanies.length > 0;
+}
+//# sourceMappingURL=fleet-default-flag.js.map