@indigoai-us/hq-cli 5.196.0 → 5.198.0

package/dist/lib/core-utils/qmd-reindex-after-sync.js

@@ -7,7 +7,8 @@
  *
  * Contract preserved verbatim: a missing qmd or a non-HQ path is a silent
  * success (a sync must never fail because indexing could not run), the lexical
- * update always runs, and embeddings rebuild only on `--embed`.
+ * update normally runs, and embeddings rebuild only on `--embed`. An enabled
+ * single-flight canary may skip a pass while another QMD writer owns the lock.
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -16,6 +17,7 @@ import { applyIndexSizeLimit } from "../search-index/max-doc-bytes.js";
 import { defaultEmbedLockDependencies, runWithEmbedLock, } from "../search-index/embed-lock.js";
 import { LoadGateConfigurationError, checkEmbedLoad, defaultLoadGateDependencies, recordSuccessfulEmbed, } from "../search-index/load-gate.js";
 import { resolveProcessFlagGate } from "../flag-registry.js";
+import { qmdReindexSingleFlightEnabled } from "../search-index/reindex-single-flight-flag.js";
 import { isQmdNativeBindingError, QMD_NATIVE_BINDING_REMEDY, } from "../../utils/qmd-native-binding-error.js";
 import { ioFor, line } from "./common.js";
 export const QMD_REINDEX_STARTUP_WARNING_FLAG = "qmd.reindex-startup-warning";
@@ -58,52 +60,59 @@ export function qmdReindexAfterSync(args = [], options = {}) {
         startupFailureWarningShown = true;
         line(stderr, `hq: search index was not updated after sync; ${QMD_NATIVE_BINDING_REMEDY}`);
     };
-    // Every qmd interaction is best-effort: the shell suffixed each with `|| true`.
-    try {
-        reconcile(hqRoot, { bin });
-    }
-    catch {
-        /* registration is advisory; an update still helps */
-    }
-    // The cap has to land before the update, not after: qmd decides what to read
-    // at glob time, so an ignore entry written afterwards saves nothing on this
-    // pass. This is the post-sync entry point, which reaches `qmd update` without
-    // going through `hq index sync` at all.
-    try {
-        sizeLimit(hqRoot);
-    }
-    catch {
-        /* an uncapped index is worse than none, but still better than a failed sync */
-    }
-    try {
-        run(["update"], { bin, cwd: hqRoot });
-    }
-    catch (error) {
-        warnOnNativeStartupFailure(error);
-        /* never fail a sync on index freshness */
-    }
-    if (embed) {
+    const updateIndex = () => {
+        // Every qmd interaction is best-effort: the shell suffixed each with `|| true`.
+        try {
+            reconcile(hqRoot, { bin });
+        }
+        catch {
+            /* registration is advisory; an update still helps */
+        }
+        // The cap has to land before the update: qmd decides what to read
+        // at glob time, so an ignore entry written afterwards saves nothing on this
+        // pass. This is the post-sync entry point, which reaches `qmd update` without
+        // going through `hq index sync` at all.
+        try {
+            sizeLimit(hqRoot);
+        }
+        catch {
+            /* an uncapped index is worse than none, but still better than a failed sync */
+        }
+        try {
+            run(["update"], { bin, cwd: hqRoot });
+        }
+        catch (error) {
+            warnOnNativeStartupFailure(error);
+            /* never fail a sync on index freshness */
+        }
+    };
+    const runEmbed = (home, lockDependencies) => {
+        const loadGateDependencies = options.loadGateDependencies ?? defaultLoadGateDependencies(lockDependencies.env);
+        const decision = checkEmbedLoad(home, loadGateDependencies);
+        if (decision.action === "skip") {
+            line(stderr, decision.notice.trimEnd());
+            return "skipped";
+        }
+        if (decision.forced)
+            line(stderr, decision.notice.trimEnd());
+        run(["embed"], { bin, cwd: hqRoot });
+        recordSuccessfulEmbed(home, loadGateDependencies);
+        return undefined;
+    };
+    if ((options.singleFlightEnabled ?? qmdReindexSingleFlightEnabled)()) {
         const lockDependencies = options.embedLockDependencies ?? defaultEmbedLockDependencies();
         const home = resolveQmdHome(lockDependencies.env);
-        const loadGateDependencies = options.loadGateDependencies ?? defaultLoadGateDependencies(lockDependencies.env);
         try {
             const outcome = runWithEmbedLock(home, lockDependencies, () => {
-                const decision = checkEmbedLoad(home, loadGateDependencies);
-                if (decision.action === "skip") {
-                    line(stderr, decision.notice.trimEnd());
-                    return "skipped";
-                }
-                if (decision.forced)
-                    line(stderr, decision.notice.trimEnd());
-                run(["embed"], { bin, cwd: hqRoot });
-                recordSuccessfulEmbed(home, loadGateDependencies);
-                return undefined;
+                updateIndex();
+                return embed ? runEmbed(home, lockDependencies) : undefined;
             });
             if (outcome === "busy") {
-                line(stderr, "hq: qmd embed is already running; skipping this pass.");
+                line(stderr, "hq: qmd reindex is already running; skipping this post-sync pass.");
+            }
+            if (outcome === "unavailable") {
+                line(stderr, "hq: cannot access the qmd reindex lock; skipping this post-sync pass.");
             }
-            if (outcome === "unavailable")
-                line(stderr, "hq: cannot access the qmd embed lock; skipping this pass.");
         }
         catch (error) {
             if (error instanceof LoadGateConfigurationError)
@@ -111,6 +120,26 @@ export function qmdReindexAfterSync(args = [], options = {}) {
             warnOnNativeStartupFailure(error);
             /* embeddings are deferred-cost and optional */
         }
+        return 0;
+    }
+    updateIndex();
+    if (!embed)
+        return 0;
+    const lockDependencies = options.embedLockDependencies ?? defaultEmbedLockDependencies();
+    const home = resolveQmdHome(lockDependencies.env);
+    try {
+        const outcome = runWithEmbedLock(home, lockDependencies, () => runEmbed(home, lockDependencies));
+        if (outcome === "busy") {
+            line(stderr, "hq: qmd embed is already running; skipping this pass.");
+        }
+        if (outcome === "unavailable")
+            line(stderr, "hq: cannot access the qmd embed lock; skipping this pass.");
+    }
+    catch (error) {
+        if (error instanceof LoadGateConfigurationError)
+            line(stderr, `hq: ${error.message}`);
+        warnOnNativeStartupFailure(error);
+        /* embeddings are deferred-cost and optional */
     }
     return 0;
 }

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

@@ -2,13 +2,24 @@
 import { parentPort, workerData } from "node:worker_threads";
 import { loadCachedTokens } from "@indigoai-us/hq-cloud";
 import { createFlagClient } from "@indigoai-us/hq-flags-client";
-const endpoint = workerData.endpoint;
+const data = workerData;
+const endpoint = data.endpoint;
+const COMPANY_UID_RE = /^cmp_[A-Za-z0-9]{3,128}$/;
+const COMPANY_SLUG_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 async function refresh() {
     if (!parentPort || typeof endpoint !== "string" || endpoint.trim() === "")
         return;
     try {
+        const companyUid = typeof data.companyUid === "string" && COMPANY_UID_RE.test(data.companyUid)
+            ? data.companyUid
+            : undefined;
+        const companyIdentifiers = Array.isArray(data.companyIdentifiers)
+            ? data.companyIdentifiers.filter((value) => typeof value === "string" && COMPANY_SLUG_RE.test(value))
+            : [];
         const client = createFlagClient({
             endpoint,
+            ...(companyUid ? { companyUid } : {}),
+            ...(companyIdentifiers.length ? { companyIdentifiers } : {}),
             getToken: () => loadCachedTokens()?.idToken ?? "",
             refreshIntervalMs: 0,
             onError: () => { },

package/dist/lib/flag-registry.js

@@ -7,8 +7,15 @@
  */
 import { Worker } from "node:worker_threads";
 import { isFlagSnapshot, readLocalOverride, resolveFlag, } from "@indigoai-us/hq-flags-client";
+import { readMachineCompanyBinding } from "./work-context/company.js";
+import { readSessionState } from "./work-context/state.js";
+import { workContextRoot } from "./work-context/paths.js";
+import { readCompaniesManifestMap } from "./work-context/repo-remote.js";
+import { resolveDefaultHqRoot } from "../utils/cognito-session.js";
 /** Dedicated endpoint configuration; this is intentionally not HQ_PRO_API_URL. */
 export const FLAG_REGISTRY_ENDPOINT_ENV = "HQ_FLAGS_API_URL";
+const COMPANY_UID_RE = /^cmp_[A-Za-z0-9]{3,128}$/;
+const COMPANY_SLUG_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 let heldSnapshot = null;
 let processReader = null;
 function processLocalOverride(flagKey) {
@@ -17,14 +24,66 @@ function processLocalOverride(flagKey) {
 function localOverrideOrFallback(flagKey, legacyFallback) {
     return processLocalOverride(flagKey) ?? legacyFallback();
 }
-function processSnapshotReader() {
+function normalizedCompanyUid(value) {
+    const candidate = value?.trim() ?? "";
+    return COMPANY_UID_RE.test(candidate) ? candidate : undefined;
+}
+function normalizedCompanySlug(value) {
+    const candidate = value?.trim() ?? "";
+    return COMPANY_SLUG_RE.test(candidate) ? candidate : undefined;
+}
+/**
+ * Resolve only an explicit machine/session company binding. Device defaults
+ * and cwd/repository heuristics do not scope process-wide feature flags.
+ */
+function processCompanyContext(env = process.env) {
+    const explicitUid = normalizedCompanyUid(env.HQ_COMPANY_UID);
+    const explicitSlug = normalizedCompanySlug(env.HQ_COMPANY_SLUG);
+    if (explicitUid || explicitSlug) {
+        return { companyUid: explicitUid, companySlug: explicitSlug };
+    }
+    const machine = readMachineCompanyBinding(env);
+    const spawnValue = env.HQ_SPAWN_COMPANY?.trim();
+    const spawnSlug = normalizedCompanySlug(spawnValue);
+    const machineContext = spawnValue && COMPANY_UID_RE.test(spawnValue)
+        ? { companyUid: spawnValue }
+        : spawnSlug
+            ? { companySlug: spawnSlug }
+            : {
+                companyUid: normalizedCompanyUid(machine?.uid),
+                companySlug: normalizedCompanySlug(machine?.slug),
+            };
+    if (machineContext.companyUid || machineContext.companySlug)
+        return machineContext;
+    const sessionId = env.HQ_SESSION_ID?.trim();
+    if (!sessionId)
+        return {};
+    const session = readSessionState(sessionId, workContextRoot(undefined, env));
+    if (session?.contextStatus !== "bound" || session.companyConfidence === "device_default") {
+        return {};
+    }
+    return {
+        companyUid: normalizedCompanyUid(session.companyUid),
+        companySlug: normalizedCompanySlug(session.companySlug),
+    };
+}
+function companyUidForContext(context, env = process.env) {
+    if (context.companyUid)
+        return context.companyUid;
+    if (!context.companySlug)
+        return undefined;
+    const hqRoot = resolveDefaultHqRoot({ env });
+    const manifestUid = readCompaniesManifestMap(hqRoot)?.[context.companySlug]?.cloud_uid;
+    return typeof manifestUid === "string" ? normalizedCompanyUid(manifestUid) : undefined;
+}
+function processSnapshotReader(companyIdentifiers) {
     return {
         isEnabled(flagKey, lookup = {}) {
             return resolveFlag({
                 flagKey,
                 env: process.env,
                 snapshot: heldSnapshot,
-                companyIdentifiers: [],
+                companyIdentifiers,
                 lookup,
             }).value;
         },
@@ -45,9 +104,18 @@ export function kickFlagRegistryReadiness(dependencies = {}) {
     const endpoint = (dependencies.endpoint ?? process.env[FLAG_REGISTRY_ENDPOINT_ENV] ?? "").trim();
     if (!endpoint)
         return null;
-    processReader = processSnapshotReader();
+    const company = processCompanyContext();
+    const companyUid = companyUidForContext(company);
+    const companyIdentifiers = [companyUid, company.companySlug].filter((value) => Boolean(value));
+    processReader = processSnapshotReader(companyIdentifiers);
     try {
-        const worker = (dependencies.createWorker ?? ((filename, options) => new Worker(filename, options)))(new URL("./flag-registry-worker.js", import.meta.url), { workerData: { endpoint } });
+        const worker = (dependencies.createWorker ?? ((filename, options) => new Worker(filename, options)))(new URL("./flag-registry-worker.js", import.meta.url), {
+            workerData: {
+                endpoint,
+                ...(companyUid ? { companyUid } : {}),
+                ...(company.companySlug ? { companyIdentifiers: [company.companySlug] } : {}),
+            },
+        });
         worker.on("message", (value) => {
             if (isFlagSnapshot(value))
                 heldSnapshot = value;

package/dist/lib/lanes/story-ledger.js

@@ -122,6 +122,11 @@ function lockPathFor(filePath) {
 function lockOwnerPath(lockPath) {
     return path.join(lockPath, "owner.json");
 }
+function isInvalidLockOwnerReceipt(err, lockPath) {
+    return err instanceof LanesError &&
+        err.error === "story_ledger_lock_invalid" &&
+        err.details.path === lockOwnerPath(lockPath);
+}
 function readLockOwner(lockPath) {
     const ownerPath = lockOwnerPath(lockPath);
     let contents;
@@ -157,15 +162,17 @@ function lockSleep(deps, ms) {
 }
 function restoreMovedLockWithoutReplacement(lockPath, stalePath) {
     const entries = fs.readdirSync(stalePath);
-    if (entries.some((entry) => entry !== "owner.json")) {
+    const isOwnerTemp = (entry) => /^\.owner-[a-f0-9]{24}\.tmp$/.test(entry);
+    if (entries.some((entry) => entry !== "owner.json" && !isOwnerTemp(entry))) {
         throw new Error("Unexpected entry in moved story ledger lock");
     }
-    const ownerContents = entries.includes("owner.json")
-        ? fs.readFileSync(lockOwnerPath(stalePath), "utf8")
-        : undefined;
+    const files = entries.map((entry) => ({
+        name: entry,
+        contents: fs.readFileSync(path.join(stalePath, entry), "utf8"),
+    }));
     fs.mkdirSync(lockPath);
-    if (ownerContents !== undefined) {
-        fs.writeFileSync(lockOwnerPath(lockPath), ownerContents, {
+    for (const file of files) {
+        fs.writeFileSync(path.join(lockPath, file.name), file.contents, {
             encoding: "utf8",
             flag: "wx",
             mode: 0o600,
@@ -186,10 +193,18 @@ function clearStaleLock(lockPath, deps) {
     if (!stat.isDirectory() || stat.isSymbolicLink()) {
         throw new LanesError("story_ledger_lock_invalid", "Story ledger lock path is not a regular directory: " + lockPath, { path: lockPath });
     }
-    const ownerRead = readLockOwner(lockPath);
-    const hasOwnerToken = hasLockOwnerToken(ownerRead);
+    let ownerRead;
+    try {
+        ownerRead = readLockOwner(lockPath);
+    }
+    catch (err) {
+        if (!isInvalidLockOwnerReceipt(err, lockPath) || lockNow(deps) - stat.mtimeMs >= LOCK_STALE_MS) {
+            throw err;
+        }
+        return false;
+    }
     let lockAt = stat.mtimeMs;
-    if (hasOwnerToken && typeof ownerRead.owner.at === "string") {
+    if (hasLockOwnerToken(ownerRead) && typeof ownerRead.owner.at === "string") {
         const parsedAt = Date.parse(ownerRead.owner.at);
         if (Number.isFinite(parsedAt))
             lockAt = parsedAt;
@@ -207,7 +222,26 @@ function clearStaleLock(lockPath, deps) {
         throw err;
     }
     const moved = fs.lstatSync(stalePath);
-    const movedOwnerRead = readLockOwner(stalePath);
+    let movedOwnerRead;
+    try {
+        movedOwnerRead = readLockOwner(stalePath);
+    }
+    catch (err) {
+        if (!isInvalidLockOwnerReceipt(err, stalePath))
+            throw err;
+        const stillFresh = lockNow(deps) - moved.mtimeMs < LOCK_STALE_MS;
+        try {
+            // Put the moved directory back before retrying or reporting the invalid receipt.
+            restoreMovedLockWithoutReplacement(lockPath, stalePath);
+        }
+        catch {
+            throw new LanesError("story_ledger_lock_race", "A replacement story ledger lock was preserved at " + stalePath +
+                " because it could not safely be restored to " + lockPath, { path: lockPath, preserved_path: stalePath });
+        }
+        if (stillFresh)
+            return false;
+        throw err;
+    }
     let movedLockAt = moved.mtimeMs;
     if (hasLockOwnerToken(movedOwnerRead) && typeof movedOwnerRead.owner.at === "string") {
         const parsedAt = Date.parse(movedOwnerRead.owner.at);
@@ -239,7 +273,14 @@ function acquireLedgerLock(filePath, deps) {
     while (lockNow(deps) - started < timeoutMs) {
         try {
             fs.mkdirSync(lockPath);
-            fs.writeFileSync(lockOwnerPath(lockPath), JSON.stringify({ pid: process.pid, token, at: new Date(lockNow(deps)).toISOString() }) + "\n", { mode: 0o600 });
+            const ownerTempPath = path.join(lockPath, ".owner-" + token + ".tmp");
+            try {
+                fs.writeFileSync(ownerTempPath, JSON.stringify({ pid: process.pid, token, at: new Date(lockNow(deps)).toISOString() }) + "\n", { encoding: "utf8", flag: "wx", mode: 0o600 });
+                fs.renameSync(ownerTempPath, lockOwnerPath(lockPath));
+            }
+            finally {
+                fs.rmSync(ownerTempPath, { force: true });
+            }
             return { lockPath, token };
         }
         catch (err) {

package/dist/lib/lanes/tracker-store.d.ts

@@ -0,0 +1,27 @@
+export type TrackerKind = "blocker" | "kpi" | "okr" | "directive";
+export interface TrackerRecord {
+    schema_version: "hq-lanes-tracker-record.v1";
+    kind: TrackerKind;
+    id: string;
+    company: string;
+    project_id: string;
+    version: number;
+    created_at: string;
+    updated_at: string;
+    [key: string]: unknown;
+}
+export interface TrackerRecordInput {
+    kind: TrackerKind;
+    id?: string;
+    company: string;
+    project_id: string;
+    [key: string]: unknown;
+}
+export interface TrackerStore {
+    read(kind: TrackerKind, id: string): TrackerRecord | null;
+    list(kind: TrackerKind): TrackerRecord[];
+    create(record: TrackerRecordInput): TrackerRecord;
+    update(kind: TrackerKind, id: string, expectedVersion: number, change: (current: TrackerRecord) => TrackerRecord): TrackerRecord;
+}
+export declare function createLocalTrackerStore(projectDirectory: string, now?: () => Date): TrackerStore;
+//# sourceMappingURL=tracker-store.d.ts.map