@indigoai-us/hq-cli 5.106.3 → 5.107.1

package/dist/utils/hook-trust.js

@@ -3,6 +3,26 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import * as readline from 'node:readline';
+// `~/.claude.json` is Claude Code's live user-global state file, so the write
+// reuses the hardened MCP-registration primitives (advisory lock held across
+// read->merge->write, backup before the first byte, temp+fsync+rename commit)
+// rather than a bare readFile/writeFile pair.
+import { acquireLock, atomicReplace, backupConfig, realpathOrSelf, releaseLock, restoreFromBackup, } from '../commands/mcp-registration.js';
+/**
+ * The home directory every runtime's config is resolved under.
+ *
+ * `HOME=''` is not the same as `HOME` unset: with `??` an empty-but-set `HOME`
+ * survives the fallback, and every `path.join(home, ...)` below it silently
+ * becomes a RELATIVE path — pointing `~/.claude.json` at a same-named file in
+ * the cwd, reading it, writing it, and dropping a backup beside it, while the
+ * user's real config goes untouched. Empty means "no home", exactly as the
+ * safe-write substrate's `resolveEnv` treats it.
+ *
+ * Exported for tests; production callers get it through `DEFAULT_DEPS`.
+ */
+export function defaultHomeDir() {
+    return process.env.HOME?.trim() ? process.env.HOME : os.homedir();
+}
 const CODEX_REQUEST_TIMEOUT_MS = 10_000;
 function errorMessage(value) {
     return value instanceof Error ? value.message : String(value);
@@ -154,7 +174,7 @@ export async function createCodexAppServerClient(cwd, executable = 'codex', args
 }
 const DEFAULT_DEPS = {
     createCodexClient: createCodexAppServerClient,
-    homeDir: () => process.env.HOME ?? os.homedir(),
+    homeDir: defaultHomeDir,
 };
 /** Trust only hooks declared by this HQ root's project `.codex/` layer. */
 export async function trustCodexProjectHooks(hqRoot, deps = DEFAULT_DEPS) {
@@ -232,6 +252,221 @@ export async function trustCodexProjectHooks(hqRoot, deps = DEFAULT_DEPS) {
         }
     }
 }
+/**
+ * How many times to re-read and re-merge `~/.claude.json` when Claude rewrites
+ * it mid-flight. Three is enough to ride out an exiting session's write without
+ * spinning against a runtime that is actively churning the file.
+ */
+const CLAUDE_MERGE_ATTEMPTS = 3;
+/** `~/.claude.json` — Claude Code's user-global state file. */
+function claudeConfigPath(home) {
+    return path.join(home, '.claude.json');
+}
+/**
+ * The home directory to resolve runtime config under, or `''` if there is none.
+ *
+ * An injected `homeDir` is authoritative: if a caller says the home is empty we
+ * report that rather than quietly reaching for the real one behind its back.
+ * The empty-`HOME` fallback lives in {@link defaultHomeDir}.
+ */
+function resolveTrustHome(deps) {
+    const home = (deps.homeDir ?? DEFAULT_DEPS.homeDir)();
+    return home?.trim() ? home : '';
+}
+/**
+ * Every spelling of the HQ root that Claude might have keyed `projects` under.
+ *
+ * Claude keys a project by the cwd of the session, so a symlinked HQ root can
+ * appear under either the link or its target depending on how the user got
+ * there. Trusting both is harmless — an entry for a path is inert until a
+ * session actually opens it — and trusting only one is a silent no-op.
+ *
+ * `aliases` carries the spellings the caller had before it canonicalized;
+ * without them a command that realpaths its root up front can only ever
+ * produce one key here, and the symlink branch is unreachable in real use.
+ */
+function claudeProjectKeys(hqRoot, aliases = []) {
+    const keys = [];
+    const add = (candidate) => {
+        if (candidate && !keys.includes(candidate))
+            keys.push(candidate);
+    };
+    for (const raw of [hqRoot, ...aliases]) {
+        if (!raw)
+            continue;
+        const resolved = path.resolve(raw);
+        add(resolved);
+        try {
+            add(fs.realpathSync(resolved));
+        }
+        catch {
+            // Root may be unreadable; the literal path is still worth trusting.
+        }
+    }
+    return keys;
+}
+/** Re-read from disk and report which keys are still not trusted. */
+function pendingAfterWrite(target, keys) {
+    let projects;
+    try {
+        projects = asObject(asObject(JSON.parse(fs.readFileSync(target, 'utf8')))?.projects);
+    }
+    catch {
+        return [...keys];
+    }
+    return keys.filter((key) => asObject(projects?.[key])?.hasTrustDialogAccepted !== true);
+}
+/**
+ * Mark this HQ root as a trusted Claude Code workspace.
+ *
+ * WHY reindex owns this: Claude's trust is per FOLDER, not per hook — the same
+ * flag gates project `.claude/settings.json` hooks AND the `.claude/skills/`
+ * plugin scan. An untrusted HQ root loads neither, and Claude reports it as
+ * "skipped because this workspace was not trusted when plugins were scanned".
+ * So the Claude leg looks like the Grok leg (write folder trust into the
+ * runtime's own config) rather than the Codex leg (trust individual hooks).
+ *
+ * Setting the key is the runtime's own documented alternative to the dialog;
+ * Claude Code's error text names it directly: "Run Claude Code in that folder
+ * once and accept the trust dialog, or set
+ * projects[<path>].hasTrustDialogAccepted: true".
+ *
+ * `~/.claude.json` is a live, high-traffic file — Claude rewrites it after
+ * every session — so this reuses the MCP registration machinery rather than a
+ * bare read/write: the advisory lock is held across read->merge->write, a
+ * backup is taken before the first written byte, and the commit is a
+ * temp+fsync+rename. `JSON.stringify(doc, null, 2)` reproduces Claude's own
+ * formatting byte-for-byte, so an unrelated key is never reformatted.
+ */
+export function trustClaudeProjectFolder(hqRoot, deps = DEFAULT_DEPS, options = {}) {
+    const home = resolveTrustHome(deps);
+    if (!home) {
+        return {
+            runtime: 'claude',
+            status: 'failed',
+            trusted: 0,
+            reason: 'cannot resolve a home directory for ~/.claude.json (HOME is empty and os.homedir() gave nothing)',
+        };
+    }
+    const target = claudeConfigPath(home);
+    if (!fs.existsSync(target)) {
+        return {
+            runtime: 'claude',
+            status: 'skipped',
+            trusted: 0,
+            reason: 'Claude Code has not run on this machine (~/.claude.json absent)',
+        };
+    }
+    const keys = claudeProjectKeys(hqRoot, options.rootAliases);
+    const fail = (reason) => ({
+        runtime: 'claude',
+        status: 'failed',
+        trusted: 0,
+        reason,
+    });
+    let lock;
+    try {
+        try {
+            lock = acquireLock(target, options.lockWaitMs === undefined ? {} : { waitMs: options.lockWaitMs });
+        }
+        catch (error) {
+            // Contention is not corruption. Another HQ writer holds the file, the
+            // next reindex converges, and a lifecycle hook must not stall behind it.
+            return {
+                runtime: 'claude',
+                status: 'skipped',
+                trusted: 0,
+                reason: `another HQ process is writing ~/.claude.json (${errorMessage(error)})`,
+            };
+        }
+        // Read and write the symlink TARGET, never the link. `atomicReplace` takes
+        // a *realTarget* — handed a link it renames a regular file over the link,
+        // silently detaching it and leaving the real config unchanged (and the
+        // read-back verification would still pass, against the wrong file).
+        const real = realpathOrSelf(target);
+        const readText = deps.readConfigText ?? ((file) => fs.readFileSync(file, 'utf8'));
+        for (let attempt = 1; attempt <= CLAUDE_MERGE_ATTEMPTS; attempt += 1) {
+            const raw = readText(real);
+            let doc;
+            try {
+                doc = JSON.parse(raw);
+            }
+            catch (error) {
+                // Never rewrite a file we could not parse — that would replace the
+                // user's Claude state with our own idea of it.
+                return fail(`~/.claude.json is not valid JSON (${errorMessage(error)})`);
+            }
+            const config = asObject(doc);
+            if (!config)
+                return fail('~/.claude.json is not a JSON object');
+            const projectsValue = config.projects === undefined ? {} : config.projects;
+            const projects = asObject(projectsValue);
+            if (!projects)
+                return fail('~/.claude.json "projects" is not an object');
+            // A PRESENT entry that is not an object (null, an array, a scalar) is
+            // either corruption or a schema we do not understand. Spreading it away
+            // would irreversibly drop live per-project state, so refuse instead —
+            // the same conservatism applied to the document as a whole.
+            const malformed = keys.filter((key) => projects[key] !== undefined && !asObject(projects[key]));
+            if (malformed.length > 0) {
+                return fail(`~/.claude.json has a non-object "projects" entry for ${malformed.join(', ')}`);
+            }
+            const pending = keys.filter((key) => asObject(projects[key])?.hasTrustDialogAccepted !== true);
+            if (pending.length === 0) {
+                return { runtime: 'claude', status: 'unchanged', trusted: 0 };
+            }
+            for (const key of pending) {
+                // Preserve every other field Claude keeps per project (lastCost,
+                // lastSessionId, exampleFiles, …) — only the trust flag is ours.
+                projects[key] = { ...(asObject(projects[key]) ?? {}), hasTrustDialogAccepted: true };
+            }
+            config.projects = projects;
+            const next = JSON.stringify(config, null, 2);
+            // Compare-and-swap against CLAUDE ITSELF. `.hqlock` only serializes HQ
+            // code that calls `acquireLock`; Claude has never heard of it and
+            // rewrites this file after every session. If the bytes moved under us
+            // since the read, our merge is built on a stale document and committing
+            // it would silently discard whatever Claude just wrote — so re-read and
+            // re-merge instead. This narrows the exposure to the gap between this
+            // check and the rename; it cannot close it, and losing the race is
+            // reported rather than papered over.
+            if (readText(real) !== raw) {
+                if (attempt < CLAUDE_MERGE_ATTEMPTS)
+                    continue;
+                return fail('Claude rewrote ~/.claude.json during each merge attempt; left it alone rather than discarding its concurrent write');
+            }
+            // Backup before the first written byte: this is the user's live Claude
+            // state, and the backup is the only remediation if the write goes wrong.
+            const backupDir = backupConfig({ home }, target, 'hq-hook-trust');
+            atomicReplace(real, next);
+            // Verify from disk rather than trusting the in-memory merge, and roll the
+            // file back if the flag did not land — a half-written Claude state file is
+            // worse than an untrusted folder.
+            const stillPending = pendingAfterWrite(real, keys);
+            if (stillPending.length > 0) {
+                let tail = `restored from backup ${backupDir}`;
+                try {
+                    restoreFromBackup(real, backupDir);
+                }
+                catch {
+                    tail = `RESTORE FAILED — the original is recoverable at ${backupDir}`;
+                }
+                return fail(`trust flag did not persist for ${stillPending.join(', ')}; ${tail}`);
+            }
+            return { runtime: 'claude', status: 'trusted', trusted: pending.length };
+        }
+        /* c8 ignore next -- the loop returns or continues; continue past the last
+           attempt is guarded above. */
+        return fail('exhausted ~/.claude.json merge attempts');
+    }
+    catch (error) {
+        return fail(errorMessage(error));
+    }
+    finally {
+        if (lock)
+            releaseLock(lock);
+    }
+}
 function regexEscape(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
@@ -412,19 +647,23 @@ export function trustGrokProjectHooks(hqRoot, deps = DEFAULT_DEPS) {
     }
 }
 /** Converge hook trust without turning an absent runtime into a reindex failure. */
-export async function trustHqRuntimeHooks(hqRoot, deps = DEFAULT_DEPS) {
+export async function trustHqRuntimeHooks(hqRoot, deps = DEFAULT_DEPS, options = {}) {
     const results = [
         await trustCodexProjectHooks(hqRoot, deps),
         trustGrokProjectHooks(hqRoot, deps),
+        trustClaudeProjectFolder(hqRoot, deps, options),
     ];
     for (const result of results) {
         if (result.status === 'trusted') {
             if (result.runtime === 'codex') {
                 console.log(`reindex: trusted ${result.trusted} Codex HQ hook${result.trusted === 1 ? '' : 's'}`);
             }
-            else {
+            else if (result.runtime === 'grok') {
                 console.log('reindex: refreshed Grok HQ hook trust');
             }
+            else {
+                console.log('reindex: trusted this HQ folder for Claude Code hooks and skills');
+            }
         }
         else if (result.status === 'failed') {
             console.warn(`reindex: could not trust ${result.runtime} HQ hooks: ${result.reason ?? 'unknown error'}`);

package/dist/utils/secrets-cache.d.ts

@@ -1,6 +1,12 @@
 export declare const DEFAULT_SECRETS_CACHE_TTL_MS: number;
-export declare function readCache(companyUid: string, name: string): string | null;
-export declare function writeCache(companyUid: string, name: string, value: string, ttlMs?: number): void;
+export declare function readCache(companyUid: string, name: string, expectedVersion?: number, maxAgeMs?: number): string | null;
+/**
+ * Returns whether an unexpired entry exists without decrypting its plaintext.
+ * Callers use this only to decide whether to reauthorize a possible cache hit;
+ * they must complete that authorization before calling {@link readCache}.
+ */
+export declare function hasCacheEntry(companyUid: string, name: string): boolean;
+export declare function writeCache(companyUid: string, name: string, value: string, ttlMs?: number, version?: number): void;
 /**
  * List the scope UIDs (`cmp_*` / `prs_*` subdirectories) that currently have a
  * secrets-cache directory on disk. Install-time MCP registration may use an

package/dist/utils/secrets-cache.js

@@ -6,9 +6,13 @@ const CACHE_DIR = path.join(os.homedir(), ".hq", "secrets-cache");
 const KEY_PATH = path.join(CACHE_DIR, ".key");
 const CACHE_FORMAT_MAGIC = Buffer.from("HQSC");
 const CACHE_FORMAT_MAGIC_BYTES = CACHE_FORMAT_MAGIC.length;
+const CACHE_VERSION_MARKER = Buffer.from("HQSCV2\0");
+const LEGACY_CACHE_VERSION_MARKER = Buffer.from("HQSCV1\0");
+const CACHE_VERSION_MARKER_BYTES = CACHE_VERSION_MARKER.length;
 const LEGACY_TIMESTAMP_BYTES = 8;
 const TIMESTAMP_BYTES = 8;
 const TTL_BYTES = 8;
+const CACHE_VERSION_BYTES = 8;
 const ALGORITHM = "aes-256-gcm";
 const IV_BYTES = 12;
 const AUTH_TAG_BYTES = 16;
@@ -45,7 +49,94 @@ function getOrCreateKey() {
     fs.renameSync(tmpPath, KEY_PATH);
     return fs.readFileSync(KEY_PATH);
 }
-export function readCache(companyUid, name) {
+function isCacheVersion(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+function readCacheVersion(raw, offset) {
+    const value = Number(raw.readBigInt64BE(offset));
+    if (value === 0)
+        return undefined;
+    return isCacheVersion(value) ? value : null;
+}
+function cacheAad(header, companyUid, name) {
+    const company = Buffer.from(companyUid, "utf8");
+    const secretName = Buffer.from(name, "utf8");
+    const companyLength = Buffer.alloc(4);
+    const nameLength = Buffer.alloc(4);
+    companyLength.writeUInt32BE(company.length);
+    nameLength.writeUInt32BE(secretName.length);
+    return Buffer.concat([
+        Buffer.from("HQSC-AAD-V2\0"),
+        header,
+        companyLength,
+        company,
+        nameLength,
+        secretName,
+    ]);
+}
+function parseCacheHeader(raw) {
+    if (raw.subarray(0, CACHE_FORMAT_MAGIC_BYTES).equals(CACHE_FORMAT_MAGIC)) {
+        const baseHeaderBytes = CACHE_FORMAT_MAGIC_BYTES + TIMESTAMP_BYTES + TTL_BYTES;
+        if (raw.length < baseHeaderBytes + IV_BYTES + AUTH_TAG_BYTES)
+            return null;
+        let ivStart = baseHeaderBytes;
+        let version;
+        let identityAuthenticated = false;
+        if (raw.length >=
+            baseHeaderBytes + CACHE_VERSION_MARKER_BYTES + CACHE_VERSION_BYTES + IV_BYTES + AUTH_TAG_BYTES &&
+            raw
+                .subarray(baseHeaderBytes, baseHeaderBytes + CACHE_VERSION_MARKER_BYTES)
+                .equals(CACHE_VERSION_MARKER)) {
+            const parsedVersion = readCacheVersion(raw, baseHeaderBytes + CACHE_VERSION_MARKER_BYTES);
+            if (parsedVersion === null)
+                return null;
+            version = parsedVersion;
+            ivStart += CACHE_VERSION_MARKER_BYTES + CACHE_VERSION_BYTES;
+            identityAuthenticated = true;
+        }
+        else if (raw.length >=
+            baseHeaderBytes + LEGACY_CACHE_VERSION_MARKER.length + CACHE_VERSION_BYTES + IV_BYTES + AUTH_TAG_BYTES &&
+            raw
+                .subarray(baseHeaderBytes, baseHeaderBytes + LEGACY_CACHE_VERSION_MARKER.length)
+                .equals(LEGACY_CACHE_VERSION_MARKER)) {
+            const parsedVersion = readCacheVersion(raw, baseHeaderBytes + LEGACY_CACHE_VERSION_MARKER.length);
+            if (parsedVersion === null)
+                return null;
+            version = parsedVersion;
+            ivStart += LEGACY_CACHE_VERSION_MARKER.length + CACHE_VERSION_BYTES;
+        }
+        const authTagStart = ivStart + IV_BYTES;
+        const ciphertextStart = authTagStart + AUTH_TAG_BYTES;
+        if (raw.length < ciphertextStart)
+            return null;
+        return {
+            timestampMs: Number(raw.readBigInt64BE(CACHE_FORMAT_MAGIC_BYTES)),
+            ttlMs: Number(raw.readBigInt64BE(CACHE_FORMAT_MAGIC_BYTES + TIMESTAMP_BYTES)),
+            version,
+            identityAuthenticated,
+            ivStart,
+            authTagStart,
+            ciphertextStart,
+        };
+    }
+    const headerLen = LEGACY_TIMESTAMP_BYTES + IV_BYTES + AUTH_TAG_BYTES;
+    if (raw.length < headerLen)
+        return null;
+    return {
+        timestampMs: Number(raw.readBigInt64BE(0)),
+        ttlMs: DEFAULT_SECRETS_CACHE_TTL_MS,
+        identityAuthenticated: false,
+        ivStart: LEGACY_TIMESTAMP_BYTES,
+        authTagStart: LEGACY_TIMESTAMP_BYTES + IV_BYTES,
+        ciphertextStart: headerLen,
+    };
+}
+function isExpired(header, maxAgeMs) {
+    const ttlMs = maxAgeMs === undefined ? header.ttlMs : Math.min(header.ttlMs, maxAgeMs);
+    const ageMs = Date.now() - header.timestampMs;
+    return !Number.isFinite(ttlMs) || ttlMs <= 0 || ageMs < 0 || ageMs > ttlMs;
+}
+export function readCache(companyUid, name, expectedVersion, maxAgeMs) {
     if (!validateInputs(companyUid, name))
         return null;
     const filePath = path.join(CACHE_DIR, companyUid, name);
@@ -56,40 +147,21 @@ export function readCache(companyUid, name) {
     catch {
         return null;
     }
-    let timestampMs;
-    let ttlMs;
-    let ivStart;
-    let authTagStart;
-    let ciphertextStart;
-    if (raw.length >=
-        CACHE_FORMAT_MAGIC_BYTES + TIMESTAMP_BYTES + TTL_BYTES + IV_BYTES + AUTH_TAG_BYTES &&
-        raw.subarray(0, CACHE_FORMAT_MAGIC_BYTES).equals(CACHE_FORMAT_MAGIC)) {
-        timestampMs = Number(raw.readBigInt64BE(CACHE_FORMAT_MAGIC_BYTES));
-        ttlMs = Number(raw.readBigInt64BE(CACHE_FORMAT_MAGIC_BYTES + TIMESTAMP_BYTES));
-        ivStart = CACHE_FORMAT_MAGIC_BYTES + TIMESTAMP_BYTES + TTL_BYTES;
-        authTagStart = ivStart + IV_BYTES;
-        ciphertextStart = authTagStart + AUTH_TAG_BYTES;
-    }
-    else {
-        const headerLen = LEGACY_TIMESTAMP_BYTES + IV_BYTES + AUTH_TAG_BYTES;
-        if (raw.length < headerLen)
-            return null;
-        timestampMs = Number(raw.readBigInt64BE(0));
-        ttlMs = DEFAULT_SECRETS_CACHE_TTL_MS;
-        ivStart = LEGACY_TIMESTAMP_BYTES;
-        authTagStart = ivStart + IV_BYTES;
-        ciphertextStart = authTagStart + AUTH_TAG_BYTES;
-    }
-    if (ttlMs <= 0 || Date.now() - timestampMs > ttlMs) {
+    const header = parseCacheHeader(raw);
+    if (!header)
+        return null;
+    if (!header.identityAuthenticated ||
+        isExpired(header, maxAgeMs) ||
+        (expectedVersion !== undefined && header.version !== expectedVersion)) {
         try {
             fs.unlinkSync(filePath);
         }
         catch { /* ok */ }
         return null;
     }
-    const iv = raw.subarray(ivStart, authTagStart);
-    const authTag = raw.subarray(authTagStart, ciphertextStart);
-    const ciphertext = raw.subarray(ciphertextStart);
+    const iv = raw.subarray(header.ivStart, header.authTagStart);
+    const authTag = raw.subarray(header.authTagStart, header.ciphertextStart);
+    const ciphertext = raw.subarray(header.ciphertextStart);
     let key;
     try {
         key = getOrCreateKey();
@@ -99,6 +171,7 @@ export function readCache(companyUid, name) {
     }
     try {
         const decipher = crypto.createDecipheriv(ALGORITHM, key, iv);
+        decipher.setAAD(cacheAad(raw.subarray(0, header.ivStart), companyUid, name));
         decipher.setAuthTag(authTag);
         const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
         return decrypted.toString("utf8");
@@ -111,7 +184,35 @@ export function readCache(companyUid, name) {
         return null;
     }
 }
-export function writeCache(companyUid, name, value, ttlMs = DEFAULT_SECRETS_CACHE_TTL_MS) {
+/**
+ * Returns whether an unexpired entry exists without decrypting its plaintext.
+ * Callers use this only to decide whether to reauthorize a possible cache hit;
+ * they must complete that authorization before calling {@link readCache}.
+ */
+export function hasCacheEntry(companyUid, name) {
+    if (!validateInputs(companyUid, name))
+        return false;
+    const filePath = path.join(CACHE_DIR, companyUid, name);
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath);
+    }
+    catch {
+        return false;
+    }
+    const header = parseCacheHeader(raw);
+    if (!header)
+        return false;
+    if (!header.identityAuthenticated || isExpired(header)) {
+        try {
+            fs.unlinkSync(filePath);
+        }
+        catch { /* ok */ }
+        return false;
+    }
+    return true;
+}
+export function writeCache(companyUid, name, value, ttlMs = DEFAULT_SECRETS_CACHE_TTL_MS, version) {
     try {
         if (!validateInputs(companyUid, name))
             return;
@@ -120,14 +221,29 @@ export function writeCache(companyUid, name, value, ttlMs = DEFAULT_SECRETS_CACH
         ensureCacheDir(companyUid);
         const key = getOrCreateKey();
         const iv = crypto.randomBytes(IV_BYTES);
-        const cipher = crypto.createCipheriv(ALGORITHM, key, iv);
-        const encrypted = Buffer.concat([cipher.update(value, "utf8"), cipher.final()]);
-        const authTag = cipher.getAuthTag();
         const timestamp = Buffer.alloc(8);
         timestamp.writeBigInt64BE(BigInt(Date.now()));
         const ttl = Buffer.alloc(8);
         ttl.writeBigInt64BE(BigInt(ttlMs));
-        const out = Buffer.concat([CACHE_FORMAT_MAGIC, timestamp, ttl, iv, authTag, encrypted]);
+        const versionBuffer = Buffer.alloc(CACHE_VERSION_BYTES);
+        versionBuffer.writeBigInt64BE(BigInt(isCacheVersion(version) ? version : 0));
+        const header = Buffer.concat([
+            CACHE_FORMAT_MAGIC,
+            timestamp,
+            ttl,
+            CACHE_VERSION_MARKER,
+            versionBuffer,
+        ]);
+        const cipher = crypto.createCipheriv(ALGORITHM, key, iv);
+        cipher.setAAD(cacheAad(header, companyUid, name));
+        const encrypted = Buffer.concat([cipher.update(value, "utf8"), cipher.final()]);
+        const authTag = cipher.getAuthTag();
+        const out = Buffer.concat([
+            header,
+            iv,
+            authTag,
+            encrypted,
+        ]);
         const filePath = path.join(CACHE_DIR, companyUid, name);
         fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
         const tmpPath = `${filePath}.tmp.${process.pid}`;

package/dist/utils/vault-api.js

@@ -1,4 +1,5 @@
 import { DEFAULT_VAULT_API_URL } from './cognito-session.js';
+import { CLI_VERSION } from '../cli-version.js';
 import { Sentry } from '../sentry.js';
 import { AuthError } from './auth-error.js';
 import { CompanySelectionError } from './company-selection-error.js';
@@ -169,6 +170,11 @@ export async function vaultApiFetch(opts) {
                 Authorization: `Bearer ${opts.token}`,
                 'Content-Type': 'application/json',
                 'x-hq-client-name': HQ_CLIENT_NAME,
+                // US-003: version alongside the client family, mirroring the desktop
+                // app's client_info.rs headers, so the server can see client-version
+                // skew on EVERY authenticated request, not only health heartbeats.
+                // Fixed build constant, never caller-supplied; attribution only.
+                'x-hq-client-version': CLI_VERSION,
             },
             body: opts.body ? JSON.stringify(opts.body) : undefined,
             signal: opts.signal,

package/package.json

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