@indigoai-us/hq-cli 5.197.0 → 5.198.1

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/lanes/types.d.ts

@@ -706,6 +706,8 @@ export interface LanesConfig {
     providers: Record<LaneProvider, ProviderConfig>;
     throttle: ThrottleConfig;
     liveness: LivenessWindows;
+    /** Seconds an unanswered question waits at a session audience before advancing. */
+    session_question_timeout_secs: number;
 }
 export declare function parseMajorSchema(schemaVersion: string, expectedPrefix: string, expectedMajor: number): void;
 export declare function parseLaneEnvelope(raw: unknown): LaneEnvelope;

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.1",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {