@indigoai-us/hq-cli 5.197.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/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

package/dist/lib/lanes/tracker-store.js

@@ -0,0 +1,277 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { randomUUID } from "node:crypto";
+import { LanesError } from "./errors.js";
+const KIND_SET = new Set(["blocker", "kpi", "okr", "directive"]);
+const ID_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/;
+function storeError(error, message, details = {}) {
+    return new LanesError(error, message, details);
+}
+function validateId(id) {
+    if (!ID_RE.test(id) || id === "." || id === "..") {
+        throw storeError("tracker_id_invalid", "Tracker record id must be a safe path segment", { id });
+    }
+}
+function recordPath(root, kind, id) {
+    validateId(id);
+    if (!KIND_SET.has(kind))
+        throw storeError("tracker_kind_invalid", "Unknown tracker record kind", { kind });
+    return path.join(root, kind, `${id}.json`);
+}
+function assertRealDirectory(directory) {
+    try {
+        const stat = fs.lstatSync(directory);
+        if (!stat.isDirectory() || stat.isSymbolicLink()) {
+            throw storeError("tracker_store_path_invalid", "Tracker storage path must be a real directory", { path: directory });
+        }
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+        fs.mkdirSync(directory, { mode: 0o700 });
+    }
+}
+function ensureKindDirectory(root, kind) {
+    assertRealDirectory(root);
+    const directory = path.join(root, kind);
+    assertRealDirectory(directory);
+    return directory;
+}
+function existingKindDirectory(root, kind) {
+    try {
+        const rootStat = fs.lstatSync(root);
+        if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) {
+            throw storeError("tracker_store_path_invalid", "Tracker storage path must be a real directory", { path: root });
+        }
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+    const directory = path.join(root, kind);
+    try {
+        const kindStat = fs.lstatSync(directory);
+        if (!kindStat.isDirectory() || kindStat.isSymbolicLink()) {
+            throw storeError("tracker_store_path_invalid", "Tracker kind path must be a real directory", { path: directory });
+        }
+        return directory;
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+}
+function parseRecord(text, expectedKind, id, file) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        throw storeError("tracker_record_malformed", "Tracker record contains invalid JSON", { kind: expectedKind, id, path: file });
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw storeError("tracker_record_invalid", "Tracker record must be a JSON object", { kind: expectedKind, id, path: file });
+    }
+    const record = value;
+    if (record.schema_version !== "hq-lanes-tracker-record.v1" ||
+        record.kind !== expectedKind ||
+        record.id !== id ||
+        typeof record.company !== "string" || !record.company ||
+        typeof record.project_id !== "string" || !record.project_id ||
+        !Number.isSafeInteger(record.version) || (record.version ?? 0) < 1 ||
+        typeof record.created_at !== "string" || typeof record.updated_at !== "string") {
+        throw storeError("tracker_record_invalid", "Tracker record is missing valid common fields", { kind: expectedKind, id, path: file });
+    }
+    return record;
+}
+function writeExclusive(file, contents) {
+    const dir = path.dirname(file);
+    const temp = path.join(dir, `.${path.basename(file)}.${randomUUID()}.tmp`);
+    try {
+        fs.writeFileSync(temp, contents, { encoding: "utf8", flag: "wx", mode: 0o600 });
+        // link is an atomic create-if-absent operation; rename would overwrite a
+        // concurrent creator's record if a generated id ever collided.
+        fs.linkSync(temp, file);
+    }
+    catch (err) {
+        if (err.code === "EEXIST") {
+            throw storeError("tracker_record_exists", "Tracker record id already exists", { path: file });
+        }
+        throw err;
+    }
+    finally {
+        removeTempFile(temp);
+    }
+}
+function removeTempFile(file) {
+    try {
+        fs.unlinkSync(file);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+}
+function withRecordLock(file, action) {
+    const lock = `${file}.lock`;
+    let fd;
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            fd = fs.openSync(lock, "wx", 0o600);
+            fs.writeSync(fd, `${process.pid}\n`);
+            break;
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            // Recover a lock only when it is old and its owner is gone. Rechecking
+            // inode and mtime before unlinking avoids deleting a freshly replaced lock.
+            let first;
+            try {
+                first = fs.lstatSync(lock);
+            }
+            catch (statError) {
+                if (statError.code === "ENOENT")
+                    continue;
+                throw statError;
+            }
+            if (Date.now() - first.mtimeMs < 5 * 60_000) {
+                throw storeError("tracker_write_busy", "Tracker record is being updated; retry the command", { path: file });
+            }
+            let owner = null;
+            try {
+                const raw = fs.readFileSync(lock, "utf8").trim();
+                const parsed = Number(raw);
+                if (Number.isSafeInteger(parsed) && parsed > 0)
+                    owner = parsed;
+            }
+            catch (readError) {
+                if (readError.code !== "ENOENT")
+                    throw readError;
+            }
+            if (owner !== null) {
+                try {
+                    process.kill(owner, 0);
+                    throw storeError("tracker_write_busy", "Tracker record is being updated; retry the command", { path: file });
+                }
+                catch (probeError) {
+                    if (probeError instanceof LanesError)
+                        throw probeError;
+                    if (probeError.code !== "ESRCH")
+                        throw probeError;
+                }
+            }
+            try {
+                const second = fs.lstatSync(lock);
+                if (second.ino === first.ino && second.dev === first.dev && second.mtimeMs === first.mtimeMs)
+                    fs.unlinkSync(lock);
+            }
+            catch (unlinkError) {
+                if (unlinkError.code !== "ENOENT")
+                    throw unlinkError;
+            }
+        }
+    }
+    if (fd === undefined)
+        throw storeError("tracker_write_busy", "Tracker record is being updated; retry the command", { path: file });
+    try {
+        return action();
+    }
+    finally {
+        fs.closeSync(fd);
+        fs.unlinkSync(lock);
+    }
+}
+export function createLocalTrackerStore(projectDirectory, now = () => new Date()) {
+    const root = path.join(projectDirectory, "tracker");
+    const read = (kind, id) => {
+        const file = recordPath(root, kind, id);
+        let text;
+        try {
+            const stat = fs.lstatSync(file);
+            if (!stat.isFile() || stat.isSymbolicLink()) {
+                throw storeError("tracker_record_invalid", "Tracker record path must be a regular file", { kind, id, path: file });
+            }
+            text = fs.readFileSync(file, "utf8");
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return null;
+            throw err;
+        }
+        return parseRecord(text, kind, id, file);
+    };
+    return {
+        read,
+        list(kind) {
+            const directory = existingKindDirectory(root, kind);
+            if (directory === null)
+                return [];
+            return fs.readdirSync(directory)
+                .filter((name) => name.endsWith(".json"))
+                .sort()
+                .map((name) => {
+                const id = name.slice(0, -5);
+                return read(kind, id);
+            })
+                .filter((record) => record !== null)
+                .sort((a, b) => b.updated_at.localeCompare(a.updated_at) || a.id.localeCompare(b.id));
+        },
+        create(input) {
+            const kind = input.kind;
+            const directory = ensureKindDirectory(root, kind);
+            const id = typeof input.id === "string" && input.id ? input.id : randomUUID();
+            const time = now().toISOString();
+            const record = {
+                ...input,
+                schema_version: "hq-lanes-tracker-record.v1",
+                kind,
+                id,
+                company: input.company,
+                project_id: input.project_id,
+                version: 1,
+                created_at: time,
+                updated_at: time,
+            };
+            writeExclusive(path.join(directory, `${id}.json`), `${JSON.stringify(record, null, 2)}\n`);
+            return record;
+        },
+        update(kind, id, expectedVersion, change) {
+            const file = recordPath(root, kind, id);
+            const directory = ensureKindDirectory(root, kind);
+            return withRecordLock(file, () => {
+                const current = read(kind, id);
+                if (!current)
+                    throw storeError("tracker_record_not_found", `Tracker ${kind} record ${id} was not found`, { kind, id });
+                if (current.version !== expectedVersion) {
+                    throw storeError("tracker_version_conflict", `Tracker record version conflict: expected ${expectedVersion}, found ${current.version}`, {
+                        kind, id, expected: expectedVersion, actual: current.version,
+                    });
+                }
+                const changed = change(current);
+                if (changed.id !== current.id || changed.kind !== current.kind || changed.company !== current.company || changed.project_id !== current.project_id || changed.created_at !== current.created_at) {
+                    throw storeError("tracker_update_invalid", "Tracker update cannot change record identity", { kind, id });
+                }
+                const next = {
+                    ...changed,
+                    schema_version: "hq-lanes-tracker-record.v1",
+                    version: current.version + 1,
+                    created_at: current.created_at,
+                    updated_at: now().toISOString(),
+                };
+                const temp = path.join(directory, `.${id}.${randomUUID()}.tmp`);
+                try {
+                    fs.writeFileSync(temp, `${JSON.stringify(next, null, 2)}\n`, { encoding: "utf8", flag: "wx", mode: 0o600 });
+                    fs.renameSync(temp, file);
+                }
+                finally {
+                    removeTempFile(temp);
+                }
+                return next;
+            });
+        },
+    };
+}
+//# sourceMappingURL=tracker-store.js.map

package/dist/lib/search-index/embed-lock.d.ts

@@ -12,9 +12,10 @@ export type EmbedLockProcessEvents = Pick<NodeJS.Process, 'once'> & {
 };
 export type EmbedLockRunResult = 'ran' | 'skipped' | 'busy' | 'unavailable';
 /**
- * Serializes embeddings started through hq-cli only. A bare `qmd embed` (or
- * another tool that does not call this module) cannot participate, because qmd
- * is a third-party package and does not know about HQ's lock protocol.
+ * Serializes QMD writes started through HQ-managed hq-cli paths. A bare `qmd
+ * update` / `qmd embed` (or another tool that does not call this module) cannot
+ * participate, because qmd is a third-party package and does not know about
+ * HQ's lock protocol.
  */
 export declare const EMBED_LOCK_NAME = "qmd-reindex-bg.lock";
 export declare function defaultEmbedLockDependencies(env?: NodeJS.ProcessEnv): EmbedLockDependencies;
@@ -26,7 +27,7 @@ export declare function releaseEmbedLock(home: string, dependencies: EmbedLockDe
 /** Install signal and exit cleanup for a lock owner, returning an optional unregister hook. */
 export declare function installEmbedLockCleanup(cleanup: () => void, processEvents?: EmbedLockProcessEvents, exit?: (code: number) => void): () => void;
 /**
- * Run one synchronous embed while owning the shared lock.
+ * Run one synchronous QMD write or reindex pass while owning the shared lock.
  *
  * This deliberately does not install signal handlers. `run` is a synchronous
  * qmd child, so JavaScript cannot execute a cleanup handler until it returns;

package/dist/lib/search-index/embed-lock.js

@@ -1,9 +1,10 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 /**
- * Serializes embeddings started through hq-cli only. A bare `qmd embed` (or
- * another tool that does not call this module) cannot participate, because qmd
- * is a third-party package and does not know about HQ's lock protocol.
+ * Serializes QMD writes started through HQ-managed hq-cli paths. A bare `qmd
+ * update` / `qmd embed` (or another tool that does not call this module) cannot
+ * participate, because qmd is a third-party package and does not know about
+ * HQ's lock protocol.
  */
 export const EMBED_LOCK_NAME = 'qmd-reindex-bg.lock';
 export function defaultEmbedLockDependencies(env = process.env) {
@@ -261,7 +262,7 @@ export function installEmbedLockCleanup(cleanup, processEvents = process, exit =
     };
 }
 /**
- * Run one synchronous embed while owning the shared lock.
+ * Run one synchronous QMD write or reindex pass while owning the shared lock.
  *
  * This deliberately does not install signal handlers. `run` is a synchronous
  * qmd child, so JavaScript cannot execute a cleanup handler until it returns;

package/dist/lib/search-index/reindex-single-flight-flag.d.ts

@@ -0,0 +1,5 @@
+export declare const QMD_REINDEX_SINGLE_FLIGHT_FLAG = "qmd.reindex-single-flight";
+export declare const QMD_REINDEX_SINGLE_FLIGHT_FLAG_FALLBACK = false;
+/** Keep all HQ-managed QMD writers coordinated only for explicitly enabled canaries. */
+export declare function qmdReindexSingleFlightEnabled(): boolean;
+//# sourceMappingURL=reindex-single-flight-flag.d.ts.map

package/dist/lib/search-index/reindex-single-flight-flag.js

@@ -0,0 +1,8 @@
+import { resolveProcessFlagGate } from "../flag-registry.js";
+export const QMD_REINDEX_SINGLE_FLIGHT_FLAG = "qmd.reindex-single-flight";
+export const QMD_REINDEX_SINGLE_FLIGHT_FLAG_FALLBACK = false;
+/** Keep all HQ-managed QMD writers coordinated only for explicitly enabled canaries. */
+export function qmdReindexSingleFlightEnabled() {
+    return resolveProcessFlagGate(QMD_REINDEX_SINGLE_FLIGHT_FLAG, { fallback: QMD_REINDEX_SINGLE_FLIGHT_FLAG_FALLBACK }, () => QMD_REINDEX_SINGLE_FLIGHT_FLAG_FALLBACK);
+}
+//# sourceMappingURL=reindex-single-flight-flag.js.map

package/package.json

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