@indigoai-us/hq-cli 5.228.1 → 5.228.2

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+## [5.228.2] — 2026-09-27
+
 ## [5.228.1] — 2026-09-27
 
 ### Fixed

package/dist/lib/flag-registry-worker-mode-cache.d.ts

@@ -3,6 +3,13 @@ interface CachedWorkerMode {
     version: number;
     value: boolean;
 }
+export type FlagRegistryWorkerModeCacheOperation = "read" | "write";
+export type FlagRegistryWorkerModeCacheStep = "mkdir" | "write_temp" | "link" | "unlink" | "prune" | "readdir" | "read";
+/** Build bounded filesystem diagnostics without exposing the state directory. */
+export declare function flagRegistryWorkerModeCacheFailureContext(error: unknown, operation: FlagRegistryWorkerModeCacheOperation, filePath: string, env?: NodeJS.ProcessEnv): {
+    exception: unknown;
+    tags: Record<string, string>;
+};
 /** Keep the last server snapshot decision for this one startup-mode flag. */
 export declare function flagRegistryWorkerModeCachePath(stateDir: string, scopeIdentifiers: readonly string[]): string;
 /** A missing, invalid, or inaccessible cache never enables the rollout. */

package/dist/lib/flag-registry-worker-mode-cache.js

@@ -1,8 +1,116 @@
+import { execFileSync } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 export const FLAG_REGISTRY_SELF_CONTAINED_WORKER_FLAG = "cli.flag-worker-self-contained";
+class FlagRegistryWorkerModeCacheStepError extends Error {
+    cacheStep;
+    originalError;
+    constructor(cacheStep, originalError) {
+        super(`Flag registry worker-mode cache failed at ${cacheStep}`);
+        this.cacheStep = cacheStep;
+        this.originalError = originalError;
+        this.name = "FlagRegistryWorkerModeCacheStepError";
+    }
+}
+const KNOWN_ERRNOS = new Set([
+    "EACCES",
+    "EBUSY",
+    "EEXIST",
+    "EIO",
+    "EISDIR",
+    "EMFILE",
+    "ENFILE",
+    "ENOENT",
+    "ENOSPC",
+    "ENOTDIR",
+    "EPERM",
+    "EROFS",
+]);
+function withCacheFsStep(cacheStep, operation) {
+    try {
+        return operation();
+    }
+    catch (error) {
+        if (error instanceof FlagRegistryWorkerModeCacheStepError)
+            throw error;
+        throw new FlagRegistryWorkerModeCacheStepError(cacheStep, error);
+    }
+}
+function originalCacheError(error) {
+    return error instanceof FlagRegistryWorkerModeCacheStepError
+        ? error.originalError
+        : error;
+}
+function cacheErrorCode(error) {
+    const original = originalCacheError(error);
+    return typeof original === "object" && original !== null && "code" in original
+        ? original.code
+        : undefined;
+}
+function directoryHasUchg(directory) {
+    if (process.platform !== "darwin")
+        return "unknown";
+    try {
+        const rawFlags = execFileSync("/usr/bin/stat", ["-f", "%f", directory], { timeout: 1000 }).toString("utf8").trim();
+        if (!/^\d+$/.test(rawFlags))
+            return "unknown";
+        const flags = Number(rawFlags);
+        if (!Number.isSafeInteger(flags))
+            return "unknown";
+        return String((flags & 0x00000002) !== 0 || (flags & 0x00020000) !== 0);
+    }
+    catch {
+        // This bounded diagnostic is best-effort; preserve unknown and the original cache error.
+        return "unknown";
+    }
+}
+/** Build bounded filesystem diagnostics without exposing the state directory. */
+export function flagRegistryWorkerModeCacheFailureContext(error, operation, filePath, env = process.env) {
+    const cacheError = error instanceof FlagRegistryWorkerModeCacheStepError
+        ? error
+        : undefined;
+    const directory = path.dirname(filePath);
+    let dirExists = "unknown";
+    let stats;
+    try {
+        stats = fs.statSync(directory);
+        dirExists = "true";
+    }
+    catch (metadataError) {
+        if (cacheErrorCode(metadataError) === "ENOENT")
+            dirExists = "false";
+        // Keep inaccessible metadata unknown; diagnostics must not hide the cache error.
+    }
+    const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
+    const ownerMatches = typeof uid === "number" && typeof stats?.uid === "number"
+        ? String(stats.uid === uid)
+        : "unknown";
+    const dirMode = typeof stats?.mode === "number"
+        ? (stats.mode & 0o777).toString(8).padStart(3, "0")
+        : "unknown";
+    const dirHasUchg = directoryHasUchg(directory);
+    const rawErrno = cacheErrorCode(error);
+    const errno = typeof rawErrno === "string" && KNOWN_ERRNOS.has(rawErrno)
+        ? rawErrno
+        : "UNKNOWN";
+    const stateDirSource = env.HQ_STATE_DIR?.trim() ? "env" : "home";
+    return {
+        exception: originalCacheError(error),
+        tags: {
+            cache_op: operation,
+            cache_step: cacheError?.cacheStep ?? (operation === "read" ? "read" : "write_temp"),
+            errno,
+            state_dir_source: stateDirSource,
+            dir_exists: dirExists,
+            dir_owner_matches_uid: ownerMatches,
+            dir_mode: dirMode,
+            dir_has_uchg: dirHasUchg,
+            cache_path_kind: "<stateDir>/flags/<basename>",
+        },
+    };
+}
 /** Keep the last server snapshot decision for this one startup-mode flag. */
 export function flagRegistryWorkerModeCachePath(stateDir, scopeIdentifiers) {
     const basename = scopeIdentifiers.length === 0
@@ -17,11 +125,11 @@ export function flagRegistryWorkerModeCachePath(stateDir, scopeIdentifiers) {
 export function readCachedFlagRegistryWorkerMode(filePath) {
     let latest = readCacheRecordIfPresent(filePath);
     const directory = path.dirname(filePath);
-    if (!fs.existsSync(directory))
+    if (!withCacheFsStep("read", () => fs.existsSync(directory)))
         return latest;
     const basename = path.basename(filePath);
     const versionedPrefix = `${basename}.v`;
-    for (const entry of fs.readdirSync(directory)) {
+    for (const entry of withCacheFsStep("readdir", () => fs.readdirSync(directory))) {
         if (!entry.startsWith(versionedPrefix) || !entry.endsWith(".json"))
             continue;
         const versionedPath = path.join(directory, entry);
@@ -32,7 +140,7 @@ export function readCachedFlagRegistryWorkerMode(filePath) {
     return latest;
 }
 export function writeCachedFlagRegistryWorkerMode(filePath, snapshot) {
-    fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    withCacheFsStep("mkdir", () => fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 }));
     const existing = readCachedFlagRegistryWorkerMode(filePath);
     if (existing && snapshot.version < existing.version)
         return;
@@ -42,26 +150,27 @@ export function writeCachedFlagRegistryWorkerMode(filePath, snapshot) {
     const versionedPath = `${filePath}.v${snapshot.version}.json`;
     const tempPath = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
     try {
-        fs.writeFileSync(tempPath, `${JSON.stringify(snapshot)}\n`, {
+        withCacheFsStep("write_temp", () => fs.writeFileSync(tempPath, `${JSON.stringify(snapshot)}\n`, {
             encoding: "utf8",
             mode: 0o600,
             flag: "wx",
-        });
+        }));
         try {
-            fs.linkSync(tempPath, versionedPath);
+            withCacheFsStep("link", () => fs.linkSync(tempPath, versionedPath));
         }
         catch (error) {
             if (!isAlreadyExistsError(error))
                 throw error;
             const existingVersion = readCacheRecord(versionedPath);
             if (existingVersion.value !== snapshot.value) {
-                throw new Error("Conflicting flag-registry worker cache values share a version");
+                throw new FlagRegistryWorkerModeCacheStepError("link", new Error("Conflicting flag-registry worker cache values share a version"));
             }
         }
     }
     finally {
-        if (fs.existsSync(tempPath))
-            fs.unlinkSync(tempPath);
+        if (withCacheFsStep("unlink", () => fs.existsSync(tempPath))) {
+            withCacheFsStep("unlink", () => fs.unlinkSync(tempPath));
+        }
     }
     pruneOlderCacheRecords(filePath);
 }
@@ -76,7 +185,8 @@ function isCachedWorkerMode(value) {
         "value" in value && typeof value.value === "boolean";
 }
 function readCacheRecord(filePath) {
-    const value = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    const contents = withCacheFsStep("read", () => fs.readFileSync(filePath, "utf8"));
+    const value = JSON.parse(contents);
     if (!isCachedWorkerMode(value)) {
         throw new Error("Cached flag-registry worker mode has an invalid shape");
     }
@@ -97,14 +207,14 @@ function pruneOlderCacheRecords(filePath) {
     const directory = path.dirname(filePath);
     const basename = path.basename(filePath);
     const versionedPrefix = `${basename}.v`;
-    for (const entry of fs.readdirSync(directory)) {
+    for (const entry of withCacheFsStep("readdir", () => fs.readdirSync(directory))) {
         if (!entry.startsWith(versionedPrefix) || !entry.endsWith(".json"))
             continue;
         const recordPath = path.join(directory, entry);
         const record = readCacheRecordIfPresent(recordPath);
         if (record && record.version < latest.version) {
             try {
-                fs.unlinkSync(recordPath);
+                withCacheFsStep("prune", () => fs.unlinkSync(recordPath));
             }
             catch (error) {
                 if (!isNotFoundError(error))
@@ -112,11 +222,11 @@ function pruneOlderCacheRecords(filePath) {
             }
         }
     }
-    if (fs.existsSync(filePath)) {
+    if (withCacheFsStep("prune", () => fs.existsSync(filePath))) {
         const legacyRecord = readCacheRecordIfPresent(filePath);
         if (legacyRecord && legacyRecord.version < latest.version) {
             try {
-                fs.unlinkSync(filePath);
+                withCacheFsStep("prune", () => fs.unlinkSync(filePath));
             }
             catch (error) {
                 if (!isNotFoundError(error))
@@ -136,11 +246,9 @@ function readCacheRecordIfPresent(filePath) {
     }
 }
 function isAlreadyExistsError(error) {
-    return typeof error === "object" && error !== null &&
-        "code" in error && error.code === "EEXIST";
+    return cacheErrorCode(error) === "EEXIST";
 }
 function isNotFoundError(error) {
-    return typeof error === "object" && error !== null &&
-        "code" in error && error.code === "ENOENT";
+    return cacheErrorCode(error) === "ENOENT";
 }
 //# sourceMappingURL=flag-registry-worker-mode-cache.js.map

package/dist/lib/flag-registry.js

@@ -14,7 +14,7 @@ import { workContextRoot } from "./work-context/paths.js";
 import { readCompaniesManifestMap } from "./work-context/repo-remote.js";
 import { loadCachedTokens, resolveDefaultHqRoot } from "../utils/cognito-session.js";
 import { resolveFlagRegistryEndpoint, } from "./flag-registry-endpoint.js";
-import { FLAG_REGISTRY_SELF_CONTAINED_WORKER_FLAG, flagRegistryStateDir, flagRegistryWorkerModeCachePath, readCachedFlagRegistryWorkerMode, writeCachedFlagRegistryWorkerMode, } from "./flag-registry-worker-mode-cache.js";
+import { FLAG_REGISTRY_SELF_CONTAINED_WORKER_FLAG, flagRegistryWorkerModeCacheFailureContext, flagRegistryStateDir, flagRegistryWorkerModeCachePath, readCachedFlagRegistryWorkerMode, writeCachedFlagRegistryWorkerMode, } from "./flag-registry-worker-mode-cache.js";
 import { FLAG_REGISTRY_WORKER_SOURCE } from "./flag-registry-worker-source.generated.js";
 export { FLAG_REGISTRY_ENDPOINT_ENV } from "./flag-registry-endpoint.js";
 const COMPANY_UID_RE = /^cmp_[A-Za-z0-9]{3,128}$/;
@@ -140,8 +140,13 @@ function selfContainedWorkerEnabled(company) {
         return readCachedFlagRegistryWorkerMode(filePath)?.value ?? false;
     }
     catch (error) {
-        Sentry.captureException(error, {
-            tags: { component: "flag-registry-worker-mode-cache", worker: "flag-registry" },
+        const failure = flagRegistryWorkerModeCacheFailureContext(error, "read", filePath);
+        Sentry.captureException(failure.exception, {
+            tags: {
+                component: "flag-registry-worker-mode-cache",
+                worker: "flag-registry",
+                ...failure.tags,
+            },
         });
         return false;
     }
@@ -165,8 +170,14 @@ function cacheWorkerModeFromSnapshot(snapshot, company) {
         writeCachedFlagRegistryWorkerMode(flagRegistryWorkerModeCachePath(flagRegistryStateDir(), scopes), { version: snapshot.version, value: decision.value });
     }
     catch (error) {
-        Sentry.captureException(error, {
-            tags: { component: "flag-registry-worker-mode-cache", worker: "flag-registry" },
+        const filePath = flagRegistryWorkerModeCachePath(flagRegistryStateDir(), scopes);
+        const failure = flagRegistryWorkerModeCacheFailureContext(error, "write", filePath);
+        Sentry.captureException(failure.exception, {
+            tags: {
+                component: "flag-registry-worker-mode-cache",
+                worker: "flag-registry",
+                ...failure.tags,
+            },
         });
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.228.1",
+  "version": "5.228.2",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {