@indigoai-us/hq-cli 5.179.1 → 5.180.0

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+## [5.180.0] — 2026-09-24
+
 ## [5.179.1] — 2026-09-24
 
 ### Added
@@ -13,6 +15,11 @@
   person's inbox while the answer they need still reaches them. `hq dm inbox`
   and `hq dm thread` mark agent-audience messages with an `[agent]` tag.
 
+### Fixed
+
+- Windows checkpoint stamps now use atomic replacement and bounded retries for
+  transient filesystem errors, so a brief lock does not abort the checkpoint.
+
 ## [5.179.0] — 2026-09-24
 
 ### Fixed

package/dist/commands/core-checkpoint.d.ts

@@ -48,7 +48,11 @@ export type WriteStampsOptions = {
      * permission errno so the HqStateWriteError conversion can be proven without a
      * real unwritable path.
      */
-    fs?: Pick<typeof fs, "mkdirSync" | "writeFileSync">;
+    fs?: Pick<typeof fs, "mkdirSync" | "writeFileSync" | "renameSync" | "unlinkSync">;
+    /** Runtime seam for proving the Windows-only atomic path without host assumptions. */
+    platform?: NodeJS.Platform;
+    /** Synchronous delay seam for the bounded Windows lock retry. */
+    waitForRetry?: (delayMs: number) => void;
 };
 export declare function writeStamps(liveRoot: string, sessionId: string | undefined, options?: WriteStampsOptions): string[];
 /**

package/dist/commands/core-checkpoint.js

@@ -8,11 +8,13 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { randomUUID } from "node:crypto";
 import { execFileSync, spawn } from "node:child_process";
 import { homedir } from "node:os";
 import { resolveLiveRoot } from "../utils/hq-roots.js";
 import { peekIdToken } from "../utils/id-token.js";
 import { toHqStateWriteError } from "../utils/hq-state-write-error.js";
+import { checkpointStampWriteErrorFor, isCheckpointStampWriteError, } from "../utils/checkpoint-stamp-write-error.js";
 const DEFAULT_TRIGGER = "stop-gate";
 const BACKENDS = new Set(["auto", "claude", "codex", "grok", "none"]);
 // Pinned by operator directive 2026-09-15; change defaults here deliberately.
@@ -408,14 +410,65 @@ function writeHqState(targetPath, operation, perform) {
         perform();
     }
     catch (error) {
+        if (isCheckpointStampWriteError(error))
+            throw error;
         const typed = toHqStateWriteError(error, targetPath, operation);
         if (typed)
             throw typed;
         throw error;
     }
 }
+const WINDOWS_CHECKPOINT_WRITE_RETRY_CODES = new Set(["EBUSY", "EPERM", "UNKNOWN"]);
+const WINDOWS_CHECKPOINT_WRITE_RETRY_DELAYS_MS = [25, 50, 100];
+function waitForCheckpointWriteRetry(delayMs) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT)), 0, 0, delayMs);
+}
+function removeCheckpointStampTemp(tempPath, fsImpl, waitForRetry) {
+    for (let attempt = 0;; attempt += 1) {
+        try {
+            fsImpl.unlinkSync(tempPath);
+            return;
+        }
+        catch (error) {
+            const code = error?.code;
+            if (code === "ENOENT")
+                return;
+            if (typeof code === "string" &&
+                WINDOWS_CHECKPOINT_WRITE_RETRY_CODES.has(code) &&
+                attempt < WINDOWS_CHECKPOINT_WRITE_RETRY_DELAYS_MS.length) {
+                waitForRetry(WINDOWS_CHECKPOINT_WRITE_RETRY_DELAYS_MS[attempt]);
+                continue;
+            }
+            throw checkpointStampWriteErrorFor(error, "unlink") ?? error;
+        }
+    }
+}
+function writeCheckpointStampAtomically(targetPath, contents, fsImpl, waitForRetry) {
+    for (let attempt = 0;; attempt += 1) {
+        const tempPath = path.join(path.dirname(targetPath), `.hq-checkpoint-stamp.tmp.${process.pid}.${randomUUID()}`);
+        let failedOperation = "open";
+        try {
+            fsImpl.writeFileSync(tempPath, contents, { flag: "wx" });
+            failedOperation = "rename";
+            fsImpl.renameSync(tempPath, targetPath);
+            return;
+        }
+        catch (error) {
+            removeCheckpointStampTemp(tempPath, fsImpl, waitForRetry);
+            const code = error?.code;
+            if (typeof code !== "string" ||
+                !WINDOWS_CHECKPOINT_WRITE_RETRY_CODES.has(code) ||
+                attempt >= WINDOWS_CHECKPOINT_WRITE_RETRY_DELAYS_MS.length) {
+                throw checkpointStampWriteErrorFor(error, failedOperation) ?? error;
+            }
+            waitForRetry(WINDOWS_CHECKPOINT_WRITE_RETRY_DELAYS_MS[attempt]);
+        }
+    }
+}
 export function writeStamps(liveRoot, sessionId, options = {}) {
     const fsImpl = options.fs ?? fs;
+    const platform = options.platform ?? process.platform;
+    const waitForRetry = options.waitForRetry ?? waitForCheckpointWriteRetry;
     const stateDir = path.join(liveRoot, "workspace", "orchestrator", "hook-state");
     writeHqState(stateDir, "create the checkpoint state directory", () => fsImpl.mkdirSync(stateDir, { recursive: true }));
     const sessionKey = sessionId
@@ -427,7 +480,9 @@ export function writeStamps(liveRoot, sessionId, options = {}) {
         path.join(stateDir, `checkpoint-cli-last-${sessionKey}`),
     ];
     for (const stampPath of stampPaths) {
-        writeHqState(stampPath, "write its checkpoint state file", () => fsImpl.writeFileSync(stampPath, timestamp));
+        writeHqState(stampPath, "write its checkpoint state file", () => platform === "win32"
+            ? writeCheckpointStampAtomically(stampPath, timestamp, fsImpl, waitForRetry)
+            : fsImpl.writeFileSync(stampPath, timestamp));
     }
     return stampPaths;
 }

package/dist/main.js

@@ -25,6 +25,7 @@ import { qmdQueryDocumentMessage } from "./utils/qmd-query-document-error.js";
 import { qmdModelDownloadMessage } from "./utils/qmd-model-download-error.js";
 import { qmdWorkdirMissingMessage } from "./utils/qmd-workdir-missing-error.js";
 import { hqStateWriteErrorMessage } from "./utils/hq-state-write-error.js";
+import { checkpointStampWriteCaptureContext, checkpointStampWriteMessage, } from "./utils/checkpoint-stamp-write-error.js";
 import { incompleteInstallMessage, incompleteInstallCaptureContext, } from "./utils/incomplete-install-error.js";
 import { isExpectedUserError } from "./utils/expected-cli-error.js";
 import { isVarlockEnvError } from "./run/env-graph-guard.js";
@@ -734,6 +735,8 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         // caller-owned conditions. Keep them at error level and attach bounded,
         // installation-independent context so OneDrive/antivirus/path-length
         // hypotheses can be separated without creating one issue per host path.
+        const checkpointStampContext = checkpointStampWriteCaptureContext(err);
+        const checkpointStampMessage = checkpointStampWriteMessage(err);
         const fsContext = filesystemErrorCaptureContext(err);
         const fsMsg = fsContext ? filesystemErrorMessage(err) : null;
         if (qmdMsg) {
@@ -781,6 +784,10 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         else if (transportMsg) {
             deps.stderr.write(`hq: ${transportMsg}\n`);
         }
+        else if (checkpointStampContext && checkpointStampMessage) {
+            deps.sentry.captureException(err, checkpointStampContext);
+            deps.stderr.write(`hq: ${checkpointStampMessage}\n`);
+        }
         else if (fsMsg && fsContext) {
             deps.sentry.captureException(err, fsContext);
             deps.stderr.write(`hq: ${fsMsg}\n`);

package/dist/utils/checkpoint-stamp-write-error.d.ts

@@ -0,0 +1,28 @@
+export type CheckpointStampFsOperation = "open" | "write" | "rename" | "unlink";
+type CheckpointStampErrnoCode = "EBUSY" | "EPERM" | "UNKNOWN";
+type CheckpointStampWriteDiagnostics = {
+    fs_op: CheckpointStampFsOperation;
+    target_kind: "checkpoint_stamp";
+    errno_code: CheckpointStampErrnoCode;
+    platform: "win32";
+};
+export type CheckpointStampWriteCaptureContext = {
+    fingerprint: ["fs-write-failed", "checkpoint_stamp", CheckpointStampErrnoCode];
+    tags: CheckpointStampWriteDiagnostics;
+};
+export declare class CheckpointStampWriteError extends Error {
+    name: string;
+    readonly code: CheckpointStampErrnoCode;
+    readonly syscall: CheckpointStampFsOperation;
+    readonly checkpointStampWriteDiagnostics: CheckpointStampWriteDiagnostics;
+    constructor(diagnostics: CheckpointStampWriteDiagnostics, originalStack?: string);
+}
+/** Wrap only the captured Windows lock/error classes, keeping the original frames and dropping paths. */
+export declare function checkpointStampWriteErrorFor(error: unknown, fallbackOperation: CheckpointStampFsOperation): CheckpointStampWriteError | null;
+export declare function isCheckpointStampWriteError(error: unknown): boolean;
+/** Value-free report context for the Windows checkpoint stamp write boundary. */
+export declare function checkpointStampWriteCaptureContext(error: unknown): CheckpointStampWriteCaptureContext | null;
+/** User-facing text stays actionable without including the HQ or home path. */
+export declare function checkpointStampWriteMessage(error: unknown): string | null;
+export {};
+//# sourceMappingURL=checkpoint-stamp-write-error.d.ts.map

package/dist/utils/checkpoint-stamp-write-error.js

@@ -0,0 +1,99 @@
+const CHECKPOINT_STAMP_ERRNO_CODES = new Set([
+    "EBUSY",
+    "EPERM",
+    "UNKNOWN",
+]);
+const CHECKPOINT_STAMP_FS_OPERATIONS = new Set([
+    "open",
+    "write",
+    "rename",
+    "unlink",
+]);
+function errorLike(value) {
+    return value !== null && typeof value === "object" ? value : null;
+}
+function isCheckpointStampErrnoCode(value) {
+    return typeof value === "string" && CHECKPOINT_STAMP_ERRNO_CODES.has(value);
+}
+function isCheckpointStampFsOperation(value) {
+    return (typeof value === "string" &&
+        CHECKPOINT_STAMP_FS_OPERATIONS.has(value));
+}
+export class CheckpointStampWriteError extends Error {
+    name = "CheckpointStampWriteError";
+    code;
+    syscall;
+    checkpointStampWriteDiagnostics;
+    constructor(diagnostics, originalStack) {
+        super(`checkpoint stamp write failed during ${diagnostics.fs_op} (${diagnostics.errno_code})`);
+        this.code = diagnostics.errno_code;
+        this.syscall = diagnostics.fs_op;
+        this.checkpointStampWriteDiagnostics = diagnostics;
+        if (originalStack) {
+            const frames = originalStack.split("\n").slice(1);
+            if (frames.length > 0)
+                this.stack = `${this.name}: ${this.message}\n${frames.join("\n")}`;
+        }
+    }
+}
+/** Wrap only the captured Windows lock/error classes, keeping the original frames and dropping paths. */
+export function checkpointStampWriteErrorFor(error, fallbackOperation) {
+    const record = errorLike(error);
+    if (!record || !isCheckpointStampErrnoCode(record.code))
+        return null;
+    const fsOperation = isCheckpointStampFsOperation(record.syscall)
+        ? record.syscall
+        : fallbackOperation;
+    const diagnostics = {
+        fs_op: fsOperation,
+        target_kind: "checkpoint_stamp",
+        errno_code: record.code,
+        platform: "win32",
+    };
+    return new CheckpointStampWriteError(diagnostics, error instanceof Error ? error.stack : undefined);
+}
+function diagnosticsFor(error) {
+    const record = errorLike(error);
+    if (!record || record.name !== "CheckpointStampWriteError")
+        return null;
+    const diagnostics = error
+        .checkpointStampWriteDiagnostics;
+    if (diagnostics === null || typeof diagnostics !== "object")
+        return null;
+    const candidate = diagnostics;
+    if (!isCheckpointStampFsOperation(candidate.fs_op) ||
+        candidate.target_kind !== "checkpoint_stamp" ||
+        !isCheckpointStampErrnoCode(candidate.errno_code) ||
+        candidate.platform !== "win32") {
+        return null;
+    }
+    return {
+        fs_op: candidate.fs_op,
+        target_kind: "checkpoint_stamp",
+        errno_code: candidate.errno_code,
+        platform: "win32",
+    };
+}
+export function isCheckpointStampWriteError(error) {
+    return diagnosticsFor(error) !== null;
+}
+/** Value-free report context for the Windows checkpoint stamp write boundary. */
+export function checkpointStampWriteCaptureContext(error) {
+    const tags = diagnosticsFor(error);
+    if (!tags)
+        return null;
+    return {
+        // This is a grouping key. Keep it independent of installation paths.
+        fingerprint: ["fs-write-failed", tags.target_kind, tags.errno_code],
+        tags,
+    };
+}
+/** User-facing text stays actionable without including the HQ or home path. */
+export function checkpointStampWriteMessage(error) {
+    const diagnostics = diagnosticsFor(error);
+    if (!diagnostics)
+        return null;
+    return (`hq could not write a checkpoint state file (${diagnostics.errno_code} during ${diagnostics.fs_op}). ` +
+        "Check the checkpoint state folder and retry.");
+}
+//# sourceMappingURL=checkpoint-stamp-write-error.js.map

package/package.json

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