@indigoai-us/hq-cli 5.345.86 → 5.345.87

package/dist/lib/bot/lock.js

@@ -0,0 +1,313 @@
+/**
+ * One writer per bot at a time.
+ *
+ * `hq bot create`, `adopt`, `restore`, `rm` and `set` all change the same
+ * bot's folder, and an adopt also rotates the bot's machine secret. Two of
+ * them running at once for the same bot (the desktop's automatic restore and
+ * its first-run create, a minute after sign-in) used to race on a
+ * check-then-write of bot.json: the loser either threw "already set up on this
+ * computer" or, worse, wrote a credential the winner had already rotated away.
+ *
+ * The lock is a file under the bots folder, `~/.hq/bots/.locks/<name>.lock`,
+ * created with O_CREAT|O_EXCL. It sits beside the bot's folder rather than in
+ * it: a folder that exists only to hold a lock would read as "a different bot
+ * already has this name" to the code that picks a restored bot's folder, and
+ * as "something is left here" to `hq bot rm`. Its body names the holder (pid,
+ * host, start time, a random token), so:
+ *   - a holder whose process is gone, or that has held it for longer than
+ *     {@link BOT_LOCK_STALE_MS}, is reclaimed;
+ *   - release only removes the lock it took (the token must match), so a
+ *     reclaim by another process never makes this process remove someone
+ *     else's lock.
+ *
+ * The lock is re-entrant within one async call chain (AsyncLocalStorage):
+ * create holds it and calls the shared adopt path, which takes it again
+ * without waiting on itself. Two separate chains in one process still
+ * serialize, exactly like two processes.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { botsRoot } from "./paths.js";
+/** Not a valid bot name (it starts with a dot), so no bot can collide with it. */
+export const BOT_LOCKS_DIRNAME = ".locks";
+/** A holder older than this is treated as crashed, whatever its pid says. */
+export const BOT_LOCK_STALE_MS = 10 * 60 * 1000;
+/** How long a second writer waits for the first before giving up. */
+export const BOT_LOCK_WAIT_MS = 3 * 60 * 1000;
+/** A lock file with no readable body yet: its creator may still be writing it. */
+const UNREADABLE_GRACE_MS = 5_000;
+export class BotLockBusyError extends Error {
+    botName;
+    holder;
+    expected = true;
+    constructor(botName, holder) {
+        super(`Another hq bot command is changing "${botName}" right now${holder?.command ? ` (${holder.command})` : ""}. Try again in a moment.`);
+        this.botName = botName;
+        this.holder = holder;
+        this.name = "BotLockBusyError";
+    }
+}
+export function botLockPath(name, root) {
+    return path.join(root ?? botsRoot(), BOT_LOCKS_DIRNAME, `${name}.lock`);
+}
+/** Alive unless the OS says there is no such process. EPERM is a live process we may not signal. */
+function defaultIsPidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+function parseHolder(raw) {
+    try {
+        const v = JSON.parse(raw);
+        if (typeof v.pid !== "number" || typeof v.startedAt !== "string" || typeof v.token !== "string")
+            return null;
+        return {
+            pid: v.pid,
+            host: typeof v.host === "string" ? v.host : "",
+            startedAt: v.startedAt,
+            token: v.token,
+            command: typeof v.command === "string" ? v.command : "",
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Why an existing lock may be taken over, or null while its holder is live.
+ * Exported for tests.
+ */
+export function botLockStaleReason(raw, mtimeMs, opts) {
+    const holder = parseHolder(raw);
+    if (!holder) {
+        // Created but not yet written, or torn by a crash. Give a live creator a
+        // moment to finish writing before calling it abandoned.
+        return opts.now - mtimeMs > UNREADABLE_GRACE_MS ? "unreadable lock" : null;
+    }
+    const started = Date.parse(holder.startedAt);
+    if (Number.isNaN(started))
+        return "unreadable start time";
+    if (opts.now - started > opts.staleMs)
+        return `held since ${holder.startedAt}`;
+    // ~/.hq/bots is per machine, so the pid is this machine's. The host name is
+    // not compared: macOS changes it with the network, which would leave a
+    // crashed holder blocking for the whole stale age.
+    if (!opts.isPidAlive(holder.pid))
+        return `holder pid ${holder.pid} has exited`;
+    return null;
+}
+const heldStorage = new AsyncLocalStorage();
+/** Locks this process holds, so a hard exit (process.exit in a failure path) still lets go. */
+const heldByProcess = new Map();
+let exitHookInstalled = false;
+function installExitHook() {
+    if (exitHookInstalled)
+        return;
+    exitHookInstalled = true;
+    process.on("exit", releaseAllHeldBotLocks);
+}
+/**
+ * Let go of every lock this process holds. Runs on process exit, so a command
+ * that ends through process.exit (every `hq bot` failure does) frees its bot
+ * at once instead of leaving it to the stale-holder reclaim.
+ */
+export function releaseAllHeldBotLocks() {
+    for (const [file, token] of [...heldByProcess])
+        releaseFile(file, token);
+}
+function releaseFile(file, token) {
+    // Moved aside before it is judged, so a lock someone else took after
+    // reclaiming ours (a very long hold) is put back rather than deleted.
+    const aside = `${file}.release-${process.pid}-${randomUUID()}`;
+    try {
+        fs.renameSync(file, aside);
+        const raw = fs.readFileSync(aside, "utf8");
+        if (parseHolder(raw)?.token !== token) {
+            try {
+                fs.linkSync(aside, file);
+            }
+            catch {
+                /* a newer holder is already in place */
+            }
+        }
+    }
+    catch {
+        /* already gone, or unreadable: nothing of ours to remove */
+    }
+    fs.rmSync(aside, { force: true });
+    heldByProcess.delete(file);
+    // Leave the bots folder as it was when no lock is held. A concurrent
+    // acquirer that loses its folder here gets ENOENT and makes it again.
+    try {
+        fs.rmdirSync(path.dirname(file));
+    }
+    catch {
+        /* other locks are held, or it is already gone */
+    }
+}
+function tryCreate(file, body) {
+    let fd;
+    try {
+        fd = fs.openSync(file, "wx", 0o600);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "EEXIST")
+            return false;
+        // Windows refuses to open a file that is pending deletion (a release in
+        // progress) with EPERM/EACCES rather than EEXIST: that is contention too.
+        if (process.platform === "win32" && (code === "EPERM" || code === "EACCES"))
+            return false;
+        if (code === "ENOENT") {
+            // The locks folder went away between mkdir and open (a wiped ~/.hq).
+            // Make it again and let the caller retry.
+            fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+            return false;
+        }
+        throw err;
+    }
+    try {
+        fs.writeSync(fd, body);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    return true;
+}
+/**
+ * Remove a stale lock, but only the one that was judged stale: it is renamed
+ * aside first, and if what was renamed is not what was read (a new holder got
+ * in between), it is put back.
+ */
+function reclaim(file, staleRaw) {
+    // Another waiter may have reclaimed it and taken its own lock since we read
+    // it: only the lock judged stale is ever moved. Either way the file changed,
+    // so the caller may try again at once.
+    try {
+        if (fs.readFileSync(file, "utf8") !== staleRaw)
+            return true;
+    }
+    catch {
+        return true;
+    }
+    const aside = `${file}.stale-${process.pid}-${randomUUID()}`;
+    try {
+        fs.renameSync(file, aside);
+    }
+    catch (err) {
+        // Gone already (someone else reclaimed or released it): try again. Any
+        // other refusal leaves the stale lock in place: wait before trying again.
+        return err.code === "ENOENT";
+    }
+    let moved = "";
+    try {
+        moved = fs.readFileSync(aside, "utf8");
+    }
+    catch {
+        /* treat as different */
+    }
+    if (moved !== staleRaw) {
+        // A live holder's lock: restore it. link fails if yet another holder now
+        // exists, which still leaves exactly one lock in place.
+        try {
+            fs.linkSync(aside, file);
+        }
+        catch {
+            try {
+                fs.writeFileSync(file, moved, { flag: "wx", mode: 0o600 });
+            }
+            catch {
+                /* another holder is in place */
+            }
+        }
+    }
+    fs.rmSync(aside, { force: true });
+    return true;
+}
+/** Take the bot's lock (waiting for a live holder), run `fn`, and let go. */
+export async function withBotLock(name, fn, opts = {}) {
+    const current = heldStorage.getStore();
+    const depth = current?.names.get(name) ?? 0;
+    if (depth > 0) {
+        current.names.set(name, depth + 1);
+        try {
+            return await fn();
+        }
+        finally {
+            current.names.set(name, depth);
+        }
+    }
+    const file = botLockPath(name, opts.root);
+    const now = opts.now ?? Date.now;
+    const isPidAlive = opts.isPidAlive ?? defaultIsPidAlive;
+    const staleMs = opts.staleMs ?? BOT_LOCK_STALE_MS;
+    const waitMs = opts.waitMs ?? BOT_LOCK_WAIT_MS;
+    const pollMs = opts.pollMs ?? 150;
+    const host = os.hostname();
+    const token = randomUUID();
+    const body = JSON.stringify({
+        pid: process.pid,
+        host,
+        startedAt: new Date(now()).toISOString(),
+        token,
+        command: opts.command ?? "",
+    });
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const deadline = now() + waitMs;
+    let waited = false;
+    let lastHolder = null;
+    for (;;) {
+        if (tryCreate(file, body))
+            break;
+        let raw;
+        let mtimeMs = now();
+        try {
+            raw = fs.readFileSync(file, "utf8");
+            mtimeMs = fs.statSync(file).mtimeMs;
+        }
+        catch {
+            raw = null; // released between our create and our read: just retry
+        }
+        if (raw !== null) {
+            lastHolder = parseHolder(raw);
+            const why = botLockStaleReason(raw, mtimeMs, { now: now(), staleMs, isPidAlive, host });
+            // Retry at once only when the stale lock is really gone. A reclaim that
+            // could not move it (Windows refusing a rename, a read-only folder) falls
+            // through to the deadline and the poll wait, so this never spins.
+            if (why) {
+                opts.onReclaim?.(lastHolder, why);
+                if (reclaim(file, raw))
+                    continue;
+            }
+            if (!waited) {
+                waited = true;
+                opts.onWait?.(lastHolder);
+            }
+        }
+        if (now() >= deadline)
+            throw new BotLockBusyError(name, lastHolder);
+        await new Promise((r) => setTimeout(r, pollMs));
+    }
+    installExitHook();
+    heldByProcess.set(file, token);
+    const held = { names: new Map(current?.names ?? []) };
+    held.names.set(name, 1);
+    try {
+        return await heldStorage.run(held, fn);
+    }
+    finally {
+        // Work that `fn` started and left running no longer holds the lock.
+        held.names.set(name, 0);
+        releaseFile(file, token);
+    }
+}
+//# sourceMappingURL=lock.js.map

package/package.json

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