@indigoai-us/hq-cli 5.345.35 → 5.345.37

package/dist/lib/index-render/companies.js

@@ -15,7 +15,8 @@ function description(root, company, name) {
         case "knowledge": return exists(root, `${base}/.git`) ? "Embedded git repo" : `Inline knowledge (${countImmediate(root, base, (n, f) => !isHidden(n) && fs.statSync(f).isDirectory())} subdirs)`;
         case "settings": return `${countImmediate(root, base, (n, f) => !isHidden(n) && fs.statSync(f).isDirectory())} integration(s)`;
         case "policies": return `${countImmediate(root, base, (n) => n.endsWith(".md"))} policy file(s)`;
-        case "projects": return `${countImmediate(root, base, (n, f) => !n.startsWith("_") && !isHidden(n) && fs.statSync(f).isDirectory())} project(s)`;
+        // Match `find -type d`: count actual directories, not symlinks to directories.
+        case "projects": return `${countImmediate(root, base, (n, f) => !n.startsWith("_") && !isHidden(n) && fs.lstatSync(f).isDirectory())} project(s)`;
         case "workers": return `${countImmediate(root, base, (n, f) => !isHidden(n) && fs.statSync(f).isDirectory())} worker(s)`;
         case "repos": return `${countImmediate(root, base, (n, f) => { const s = fs.lstatSync(f); return !isHidden(n) && (s.isDirectory() || s.isSymbolicLink()); })} repo link(s)`;
         case "registry": return `Resource registry (${countImmediate(root, `${base}/resources`, (n) => n.endsWith(".yaml"))} resource(s))`;

package/dist/lib/lanes/story-ledger.d.ts

@@ -1,6 +1,6 @@
 import { type LaneRecord, type LaneState } from "./types.js";
 export declare const LANE_STORY_LEDGER_FLAG = "lanes.story-ledger";
-declare const STORY_STATES: readonly ["todo", "in_progress", "blocked", "in_review", "verification", "done", "dropped"];
+declare const STORY_STATES: readonly ["todo", "in_progress", "review", "waiting", "blocked", "done", "dropped"];
 export interface ProjectStoryLedger {
     projectId: string;
     companySlug?: string;

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

@@ -8,8 +8,8 @@ export const LANE_STORY_LEDGER_FLAG = "lanes.story-ledger";
 const LOCK_TIMEOUT_MS = 10_000;
 const LOCK_STALE_MS = 60_000;
 const LOCK_RETRY_MS = 10;
-const STORY_STATES = ["todo", "in_progress", "blocked", "in_review", "verification", "done", "dropped"];
-const MANAGER_OWNED_STATES = new Set(["in_review", "verification", "done", "dropped"]);
+const STORY_STATES = ["todo", "in_progress", "review", "waiting", "blocked", "done", "dropped"];
+const MANAGER_OWNED_STATES = new Set(["review", "done", "dropped"]);
 const TERMINAL_STATES = new Set(["done", "failed", "interrupted", "cancelled", "killed"]);
 export function laneStoryLedgerEnabled() {
     return resolveProcessFlagGate(LANE_STORY_LEDGER_FLAG, { fallback: false }, () => false);
@@ -515,7 +515,7 @@ function validPriorQuestions(value, storyId) {
     }
     return value;
 }
-function setLaneStatusFields(story, lane, laneStoryStatus) {
+function setLaneStatusFields(story, lane, laneStoryStatus, isCurrentAttribution) {
     const laneStatus = story.lane_status;
     if (laneStatus !== undefined && !isJsonObject(laneStatus)) {
         throw new LanesError("story_ledger_invalid", "lane_status must be an object for story " + String(story.id), { story_id: story.id });
@@ -569,6 +569,9 @@ function setLaneStatusFields(story, lane, laneStoryStatus) {
     else {
         delete story.pending_questions;
     }
+    if (story.state === "in_review" || story.state === "verification") {
+        story.state = "review";
+    }
     if (MANAGER_OWNED_STATES.has(String(story.state))) {
         // A manager decision always wins over lane-derived status.
     }
@@ -576,7 +579,7 @@ function setLaneStatusFields(story, lane, laneStoryStatus) {
         story.state = "blocked";
     }
     else if (laneStoryStatus === "review") {
-        story.state = "in_review";
+        story.state = "review";
     }
     else if (laneStoryStatus === "done") {
         story.state = "done";
@@ -590,6 +593,22 @@ function setLaneStatusFields(story, lane, laneStoryStatus) {
             ? previous
             : "in_progress";
     }
+    if (typeof story.state === "string" && STORY_STATES.includes(story.state)) {
+        story.status = story.state;
+    }
+    if (story.state === "blocked") {
+        const reasons = blockers.map((entry) => {
+            const reason = typeof entry.blocked_on === "string" ? entry.blocked_on.trim() : "";
+            return reason || `Lane ${String(entry.lane_id)} is blocked`;
+        });
+        if (reasons.length > 0)
+            story.blocked_reason = [...new Set(reasons)].join("\n");
+    }
+    else {
+        delete story.blocked_reason;
+    }
+    if (!isCurrentAttribution && story.lane === lane.lane_id)
+        delete story.lane;
     if (blockers.length > 0)
         story.lane_status = { saved };
     else
@@ -611,7 +630,7 @@ function updateOneStory(current, ledger, lane, storyId, projectId, questionRefs)
         (laneStoriesForLedger(lane).length <= 1 ? lane.last_envelope?.blocked_reason : undefined);
     const laneState = storyLaneState(lane, laneStory?.status, pendingQuestionIds);
     setLaneEntry(story, lane, laneState, laneStory?.status, prLinks, pendingQuestionIds, blockedReason);
-    setLaneStatusFields(story, lane, laneStory?.status);
+    setLaneStatusFields(story, lane, laneStory?.status, lane.project_id === projectId && lane.story_id === storyId);
     if (prLinks.length > 0) {
         if (story.prs === undefined)
             story.prs = [];
@@ -695,6 +714,8 @@ function storyLaneState(lane, laneStoryStatus, pendingQuestionIds) {
 }
 function storyState(story) {
     const state = story.state;
+    if (state === "in_review" || state === "verification")
+        return "review";
     if (typeof state === "string" && STORY_STATES.includes(state)) {
         return state;
     }

package/dist/lib/provider-launcher.d.ts

@@ -0,0 +1,11 @@
+import { spawn as nodeSpawn } from "node:child_process";
+import type { Writable } from "node:stream";
+export type ProviderName = "claude" | "codex";
+export interface ProviderLauncherDependencies {
+    spawn?: typeof nodeSpawn;
+    stdout?: Writable;
+    stderr?: Writable;
+}
+export declare function providerLoginGuidance(provider: ProviderName, output: string): string | null;
+export declare function runProviderLauncher(providerValue: string, args: readonly string[], dependencies?: ProviderLauncherDependencies): Promise<number>;
+//# sourceMappingURL=provider-launcher.d.ts.map

package/dist/lib/provider-launcher.js

@@ -0,0 +1,59 @@
+import { spawn as nodeSpawn } from "node:child_process";
+export function providerLoginGuidance(provider, output) {
+    if (provider === "claude" && /not logged in|please run\s+\/login/i.test(output)) {
+        return "Claude Code is not signed in. Sign in with the provider command: claude /login";
+    }
+    if (provider === "codex" &&
+        /(?:http\s*)?401\b/i.test(output) &&
+        /missing bearer or basic authentication in header/i.test(output)) {
+        return "Codex is not signed in. Sign in with the provider command: codex login";
+    }
+    return null;
+}
+export async function runProviderLauncher(providerValue, args, dependencies = {}) {
+    const provider = providerValue;
+    if (provider !== "claude" && provider !== "codex") {
+        write(dependencies.stderr, `Unsupported provider '${providerValue}'. Choose claude or codex.\n`);
+        return 64;
+    }
+    if (provider === "claude" && !args.some((arg) => arg === "-p" || arg === "--print")) {
+        write(dependencies.stderr, "Provider launch supports noninteractive Claude Code commands. Include -p or --print after --.\n");
+        return 64;
+    }
+    if (provider === "codex" && args[0] !== "exec") {
+        write(dependencies.stderr, "Provider launch supports noninteractive Codex commands. Start the arguments after -- with exec.\n");
+        return 64;
+    }
+    const child = (dependencies.spawn ?? nodeSpawn)(provider, [...args], {
+        stdio: ["inherit", "pipe", "pipe"],
+        windowsHide: true,
+    });
+    let outputTail = "";
+    const capture = (stream, destination) => {
+        if (!stream)
+            return;
+        stream.on("data", (chunk) => {
+            const text = Buffer.isBuffer(chunk) ? chunk.toString("utf8") : chunk;
+            outputTail = `${outputTail}${text}`.slice(-16_384);
+            destination?.write(text);
+        });
+    };
+    capture(child.stdout, dependencies.stdout ?? process.stdout);
+    capture(child.stderr, dependencies.stderr ?? process.stderr);
+    return await new Promise((resolve) => {
+        child.once("error", () => {
+            write(dependencies.stderr, `Could not start ${provider === "claude" ? "Claude Code" : "Codex"}. Confirm the CLI is installed and available on PATH.\n`);
+            resolve(127);
+        });
+        child.once("close", (code) => {
+            const guidance = providerLoginGuidance(provider, outputTail);
+            if (guidance)
+                write(dependencies.stderr, `${guidance}\n`);
+            resolve(code ?? 1);
+        });
+    });
+}
+function write(stream, message) {
+    (stream ?? process.stderr).write(message);
+}
+//# sourceMappingURL=provider-launcher.js.map

package/dist/lib/workers-registry/index.js

@@ -241,18 +241,43 @@ export function generateWorkersRegistry(hqRoot, options = {}) {
     const output = registryText(options.now ?? new Date(), kept);
     const registry = path.join(hqRoot, 'core/workers/registry.yaml');
     let written = true;
+    let writeFailed = false;
     if (fs.existsSync(registry) && withoutTimestamp(fs.readFileSync(registry, 'utf8')) === withoutTimestamp(output))
         written = false;
     if (written) {
-        fs.mkdirSync(path.dirname(registry), { recursive: true });
-        fs.writeFileSync(registry, output);
-        log('generate-workers-registry: wrote core/workers/registry.yaml');
+        try {
+            fs.mkdirSync(path.dirname(registry), { recursive: true });
+            fs.writeFileSync(registry, output);
+            log('generate-workers-registry: wrote core/workers/registry.yaml');
+        }
+        catch (error) {
+            writeFailed = true;
+            written = false;
+            const code = error instanceof Error && 'code' in error && typeof error.code === 'string'
+                ? error.code
+                : 'unknown';
+            log(`generate-workers-registry: WARNING unable to write ${registry} (${code}) — grant write access to the registry path and re-run; a later run will rewrite the derived file once access is restored.`);
+            void import('../../sentry.js')
+                .then(({ Sentry }) => Sentry.captureMessage('generate-workers-registry: registry write failed; partial result returned', {
+                level: 'warning',
+                fingerprint: ['workers-registry', 'write-failed'],
+                tags: { registry_write_error: code },
+            }))
+                .catch(() => {
+                log('generate-workers-registry: WARNING unable to send the registry write failure report to Sentry.');
+            });
+        }
     }
     else {
         log('generate-workers-registry: core/workers/registry.yaml unchanged');
     }
     if (quarantined > 0) {
         log(`generate-workers-registry: wrote registry for all VALID workers; quarantined ${quarantined} problem(s) above (loud + partial, never a silent total block). Fix the reported worker.yaml file(s) and re-run to register them.`);
+    }
+    if (writeFailed) {
+        log('generate-workers-registry: registry was not written; the command completed with a partial result.');
+    }
+    if (quarantined > 0 || writeFailed) {
         return { status: 1, written, quarantined };
     }
     return { status: 0, written, quarantined };

package/dist/utils/package-use-lease.d.ts

@@ -50,5 +50,22 @@ export declare const __test__: {
     waitForUpdateRequest: typeof waitForUpdateRequest;
     setCurrentPackageUseLease(lease: PackageUseLease | null): void;
 };
+/**
+ * Run `wait` with this process's package-use lease DROPPED, then reacquire the
+ * lease before returning.
+ *
+ * `hq sync` runs under purpose `"command"`, and
+ * {@link releasePackageUseLeaseAfterCommandLoad} deliberately keeps that lease
+ * for the whole command. hq-cloud's per-root operation lock then waits — by
+ * default without a bound — for whichever process is already syncing, so an old
+ * `hq` install pinned `hq pkg update` for the entire length of somebody else's
+ * lock wait (HQ-DESKTOP-8H). Queuing is not using the package: drop the lease
+ * while this process is only waiting, and take it again once the wait is over.
+ *
+ * A reacquire that throws {@link PackageUseUpdatePendingError} is the correct
+ * outcome — an update landed while we queued — and propagates to the caller. On
+ * the failure path the original error wins and the reacquire is best-effort.
+ */
+export declare function withPackageUseLeaseReleasedDuring<T>(wait: () => Promise<T>, argv?: readonly string[], release?: () => void, reacquire?: (argv: readonly string[]) => unknown): Promise<T>;
 export {};
 //# sourceMappingURL=package-use-lease.d.ts.map

package/dist/utils/package-use-lease.js

@@ -413,4 +413,40 @@ export const __test__ = {
         currentPackageUseLease = lease;
     },
 };
+/**
+ * Run `wait` with this process's package-use lease DROPPED, then reacquire the
+ * lease before returning.
+ *
+ * `hq sync` runs under purpose `"command"`, and
+ * {@link releasePackageUseLeaseAfterCommandLoad} deliberately keeps that lease
+ * for the whole command. hq-cloud's per-root operation lock then waits — by
+ * default without a bound — for whichever process is already syncing, so an old
+ * `hq` install pinned `hq pkg update` for the entire length of somebody else's
+ * lock wait (HQ-DESKTOP-8H). Queuing is not using the package: drop the lease
+ * while this process is only waiting, and take it again once the wait is over.
+ *
+ * A reacquire that throws {@link PackageUseUpdatePendingError} is the correct
+ * outcome — an update landed while we queued — and propagates to the caller. On
+ * the failure path the original error wins and the reacquire is best-effort.
+ */
+export async function withPackageUseLeaseReleasedDuring(wait, argv = process.argv, release = releaseCurrentPackageUseLease, reacquire = acquireCurrentPackageUseLease) {
+    if (currentPackageUseLease === null)
+        return wait();
+    release();
+    let result;
+    try {
+        result = await wait();
+    }
+    catch (error) {
+        try {
+            reacquire(argv);
+        }
+        catch {
+            // The caller's error is the one worth reporting.
+        }
+        throw error;
+    }
+    reacquire(argv);
+    return result;
+}
 //# sourceMappingURL=package-use-lease.js.map

package/dist/utils/self-update.js

@@ -79,10 +79,11 @@ export const REEXEC_GUARD_ENV = UPDATE_RECURSION_GUARD_ENV;
 const REGISTRY_URL = `https://registry.npmjs.org/${encodeURIComponent(CLI_NAME)}/latest`;
 const FETCH_TIMEOUT_MS = 3_000;
 /**
- * Move the working CLI package beside itself before asking the package manager
- * to replace it. If the move is unavailable, the caller proceeds without
- * rollback protection. pnpm's .pnpm package tree is immutable store content,
- * so only its selecting public link is moved.
+ * Back up the working CLI package before asking the package manager to replace
+ * it. If the backup is unavailable, the caller proceeds without rollback
+ * protection. pnpm's .pnpm package tree is immutable store content, so back up
+ * its selecting public link while leaving that link available for pnpm's scan
+ * of existing global installs.
  */
 function findPnpmPublicLink(packageRoot) {
     const home = derivePnpmHome({ manager: "pnpm", prefix: null, packageRoot });
@@ -187,6 +188,114 @@ function snapshotNpmBinLinks(prefix, packageRoot) {
     }
     return links;
 }
+function snapshotPnpmBinShims(pnpmHome, packageRoot) {
+    const binMap = readNpmBinMap(packageRoot);
+    if (!binMap)
+        return [];
+    const binDirectory = path.join(pnpmHome, "bin");
+    const shims = [];
+    for (const name of Object.keys(binMap)) {
+        for (const suffix of ["", ".cmd", ".ps1"]) {
+            const shimPath = path.join(binDirectory, `${name}${suffix}`);
+            try {
+                const stat = fs.lstatSync(shimPath);
+                if (!stat.isFile())
+                    continue;
+                const content = fs.readFileSync(shimPath);
+                if (!pnpmShimTargetsPackage(content.toString("utf8"), packageRoot))
+                    continue;
+                shims.push({ path: shimPath, content, mode: stat.mode & 0o777 });
+            }
+            catch {
+                // A missing or unreadable command shim cannot be safely snapshotted.
+            }
+        }
+    }
+    return shims;
+}
+function pnpmShimTarget(content) {
+    const match = content.match(/^# cmd-shim-target=(.+)$/m);
+    return match?.[1]?.trim() || null;
+}
+function pnpmShimTargetsPackage(content, packageRoot) {
+    const target = pnpmShimTarget(content);
+    if (!target)
+        return false;
+    try {
+        return isPathInside(fs.realpathSync(target), packageRoot);
+    }
+    catch {
+        return false;
+    }
+}
+function pnpmShimTargetsGlobalInstall(content, binDirectory) {
+    const target = pnpmShimTarget(content);
+    if (!target)
+        return false;
+    return isPathInside(path.resolve(target), path.join(path.dirname(binDirectory), "global"));
+}
+function restorePnpmBinShims(snapshot) {
+    if (!snapshot.pnpmBinDirectory || !snapshot.pnpmBinPackageRoot || !snapshot.pnpmBinShims?.length)
+        return true;
+    let restored = true;
+    for (const shim of snapshot.pnpmBinShims) {
+        if (path.dirname(shim.path) !== snapshot.pnpmBinDirectory) {
+            reportBinLinkConflict(shim.path, "the saved pnpm shim path is outside the pnpm bin directory");
+            restored = false;
+            continue;
+        }
+        let existing;
+        try {
+            existing = fs.lstatSync(shim.path);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                reportBinLinkConflict(shim.path, errorMessage(error));
+                restored = false;
+                continue;
+            }
+        }
+        if (existing) {
+            if (!existing.isFile() || existing.isSymbolicLink()) {
+                reportBinLinkConflict(shim.path, "another entry owns this command name");
+                restored = false;
+                continue;
+            }
+            const currentText = fs.readFileSync(shim.path, "utf8");
+            if (!pnpmShimTargetsGlobalInstall(currentText, snapshot.pnpmBinDirectory)) {
+                reportBinLinkConflict(shim.path, "the existing file is not a pnpm global command shim");
+                restored = false;
+                continue;
+            }
+        }
+        const temporary = `${shim.path}.hq-cli-restore-${process.pid}-${randomBytes(4).toString("hex")}`;
+        try {
+            fs.mkdirSync(snapshot.pnpmBinDirectory, { recursive: true });
+            fs.writeFileSync(temporary, shim.content, { mode: shim.mode, flag: "wx" });
+            if (!existing) {
+                fs.linkSync(temporary, shim.path);
+                fs.rmSync(temporary, { force: true });
+            }
+            else {
+                const current = fs.lstatSync(shim.path);
+                if (!current.isFile() || current.isSymbolicLink()) {
+                    throw new Error("the pnpm shim changed while it was being restored");
+                }
+                const currentText = fs.readFileSync(shim.path, "utf8");
+                if (!pnpmShimTargetsGlobalInstall(currentText, snapshot.pnpmBinDirectory)) {
+                    throw new Error("the pnpm shim changed while it was being restored");
+                }
+                fs.renameSync(temporary, shim.path);
+            }
+        }
+        catch (error) {
+            fs.rmSync(temporary, { force: true });
+            reportBinLinkConflict(shim.path, errorMessage(error));
+            restored = false;
+        }
+    }
+    return restored;
+}
 function restoreNpmBinLinks(snapshot) {
     if (!snapshot.npmBinDirectory || !snapshot.npmBinPackageRoot || !snapshot.npmBinLinks?.length)
         return true;
@@ -391,12 +500,16 @@ function snapshotPathsAreSafe(snapshot) {
         snapshot.resolvedTarget,
         snapshot.publicLinkPath,
         snapshot.npmBinPackageRoot,
+        snapshot.pnpmBinPackageRoot,
     ].filter((value) => value !== undefined);
     if (!paths.every(isInsideNodeModules))
         return false;
     if (snapshot.npmBinLinks?.some((bin) => !snapshot.npmBinDirectory || path.dirname(bin.path) !== snapshot.npmBinDirectory ||
         !isPathInside(bin.path, snapshot.npmBinDirectory)))
         return false;
+    if (snapshot.pnpmBinShims?.some((shim) => !snapshot.pnpmBinDirectory || path.dirname(shim.path) !== snapshot.pnpmBinDirectory ||
+        !isPathInside(shim.path, snapshot.pnpmBinDirectory)))
+        return false;
     return true;
 }
 function snapshotInstall(install, renamePath = fs.renameSync) {
@@ -406,6 +519,7 @@ function snapshotInstall(install, renamePath = fs.renameSync) {
     let movedPath;
     let backupPath;
     let didMove = false;
+    let copiedPnpmLink = false;
     try {
         const entry = fs.lstatSync(packageRoot);
         let sourcePath = packageRoot;
@@ -440,9 +554,25 @@ function snapshotInstall(install, renamePath = fs.renameSync) {
         const npmBinLinks = backupKind === "package" && install.manager === "npm" && install.prefix
             ? snapshotNpmBinLinks(install.prefix, sourcePath)
             : undefined;
+        const pnpmHome = backupKind === "pnpm-public-link"
+            ? derivePnpmHome({ manager: "pnpm", prefix: null, packageRoot: sourcePath }) ?? undefined
+            : undefined;
+        const pnpmBinShims = pnpmHome ? snapshotPnpmBinShims(pnpmHome, sourcePath) : undefined;
         movedPath = backupKind === "pnpm-public-link" ? pnpmPublicLinkPath : sourcePath;
         backupPath = path.join(path.dirname(movedPath), `.hq-cli-backup-${process.pid}-${randomBytes(8).toString("hex")}`);
-        renamePath(movedPath, backupPath);
+        if (backupKind === "pnpm-public-link") {
+            // `pnpm add -g` scans every existing global package before it can update
+            // this one. Moving the active link makes its package.json disappear
+            // during that scan, so preserve a duplicate link for rollback instead.
+            const backupTarget = publicLink?.target ?? resolvedTarget ?? symlinkTarget;
+            if (!backupTarget)
+                return null;
+            fs.symlinkSync(backupTarget, backupPath, process.platform === "win32" ? "junction" : "dir");
+            copiedPnpmLink = true;
+        }
+        else {
+            renamePath(movedPath, backupPath);
+        }
         didMove = true;
         return {
             installPath: packageRoot,
@@ -458,12 +588,18 @@ function snapshotInstall(install, renamePath = fs.renameSync) {
             npmBinDirectory: npmBinLinks ? path.join(install.prefix, "bin") : undefined,
             npmBinPackageRoot: npmBinLinks ? sourcePath : undefined,
             npmBinLinks,
+            pnpmBinDirectory: pnpmBinShims?.length ? path.join(pnpmHome, "bin") : undefined,
+            pnpmBinPackageRoot: pnpmBinShims?.length ? sourcePath : undefined,
+            pnpmBinShims,
         };
     }
     catch {
         if (didMove && movedPath && backupPath) {
             try {
-                fs.renameSync(backupPath, movedPath);
+                if (copiedPnpmLink)
+                    fs.rmSync(backupPath, { recursive: true, force: true });
+                else
+                    fs.renameSync(backupPath, movedPath);
             }
             catch {
                 // The update may proceed without rollback if the move cannot be undone.
@@ -483,7 +619,7 @@ function restoreInstall(snapshot, renamePath = fs.renameSync) {
             fs.rmSync(publicLinkPath, { recursive: true, force: true });
             fs.mkdirSync(path.dirname(publicLinkPath), { recursive: true });
             renamePath(snapshot.backupPath, publicLinkPath);
-            return true;
+            return restorePnpmBinShims(snapshot);
         }
         fs.rmSync(snapshot.installPath, { recursive: true, force: true });
         if (snapshot.symlinkTarget !== undefined && snapshot.resolvedTarget !== undefined) {

package/dist/utils/sync-operation-lock.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Take hq-cloud's per-root operation lock for a sync pass from hq-cli, so the
+ * wait for an existing holder happens OUTSIDE this process's package-use lease.
+ *
+ * `sync()` normally wraps itself in `withOperationLock`, which waits for a live
+ * holder with no bound unless `HQ_OP_LOCK_TIMEOUT` says otherwise. `hq sync`
+ * runs under package-use purpose `"command"`, whose lease is held for the whole
+ * command, so the queued process pinned the installed `hq` version — and
+ * therefore blocked `hq pkg update` — for the entire length of somebody else's
+ * sync (HQ-DESKTOP-8H).
+ *
+ * Acquiring the lock here instead lets the lease be dropped across the wait and
+ * retaken the moment the lock is held, before any sync work runs.
+ * `operationLockAlreadyHeld` is the seam hq-cloud exposes for a caller that owns
+ * the lock; the lock is NOT reentrant in-process, so the flag is required rather
+ * than optional.
+ */
+import { type SyncOptions, type SyncResult } from "@indigoai-us/hq-cloud";
+import { type LockHandle } from "@indigoai-us/hq-cloud/operation-lock";
+export interface SyncUnderOperationLockDeps<Options, Result> {
+    sync: (options: Options & {
+        operationLockAlreadyHeld: true;
+    }) => Promise<Result>;
+    /** Injected in tests; defaults to hq-cloud's wait-capable acquisition. */
+    acquireLock?: (hqRoot: string) => Promise<LockHandle>;
+    /** Injected in tests; defaults to the real lease drop/retake. */
+    withLeaseReleased?: <T>(wait: () => Promise<T>) => Promise<T>;
+}
+export declare function syncUnderOperationLock<Options extends {
+    hqRoot: string;
+}, Result>(options: Options, deps: SyncUnderOperationLockDeps<Options, Result>): Promise<Result>;
+/**
+ * The production sync leg: hq-cloud's `sync()` under a lock this process takes
+ * itself. Every `hq sync` path in `src/commands/cloud.ts` calls this.
+ */
+export declare function syncLeg(options: SyncOptions): Promise<SyncResult>;
+//# sourceMappingURL=sync-operation-lock.d.ts.map

package/dist/utils/sync-operation-lock.js

@@ -0,0 +1,40 @@
+/**
+ * Take hq-cloud's per-root operation lock for a sync pass from hq-cli, so the
+ * wait for an existing holder happens OUTSIDE this process's package-use lease.
+ *
+ * `sync()` normally wraps itself in `withOperationLock`, which waits for a live
+ * holder with no bound unless `HQ_OP_LOCK_TIMEOUT` says otherwise. `hq sync`
+ * runs under package-use purpose `"command"`, whose lease is held for the whole
+ * command, so the queued process pinned the installed `hq` version — and
+ * therefore blocked `hq pkg update` — for the entire length of somebody else's
+ * sync (HQ-DESKTOP-8H).
+ *
+ * Acquiring the lock here instead lets the lease be dropped across the wait and
+ * retaken the moment the lock is held, before any sync work runs.
+ * `operationLockAlreadyHeld` is the seam hq-cloud exposes for a caller that owns
+ * the lock; the lock is NOT reentrant in-process, so the flag is required rather
+ * than optional.
+ */
+import { sync } from "@indigoai-us/hq-cloud";
+import { acquireOperationLockAsync, } from "@indigoai-us/hq-cloud/operation-lock";
+import { withPackageUseLeaseReleasedDuring } from "./package-use-lease.js";
+export async function syncUnderOperationLock(options, deps) {
+    const acquireLock = deps.acquireLock ?? ((hqRoot) => acquireOperationLockAsync(hqRoot, "sync"));
+    const withLeaseReleased = deps.withLeaseReleased ??
+        ((wait) => withPackageUseLeaseReleasedDuring(wait));
+    const handle = await withLeaseReleased(() => acquireLock(options.hqRoot));
+    try {
+        return await deps.sync({ ...options, operationLockAlreadyHeld: true });
+    }
+    finally {
+        handle.release();
+    }
+}
+/**
+ * The production sync leg: hq-cloud's `sync()` under a lock this process takes
+ * itself. Every `hq sync` path in `src/commands/cloud.ts` calls this.
+ */
+export function syncLeg(options) {
+    return syncUnderOperationLock(options, { sync });
+}
+//# sourceMappingURL=sync-operation-lock.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.345.35",
+  "version": "5.345.37",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -48,7 +48,7 @@
     "@aws-sdk/client-iot-data-plane": "^3.1096.0",
     "@aws-sdk/client-s3": "^3.1049.0",
     "@aws-sdk/dsql-signer": "^3.1146.0",
-    "@indigoai-us/hq-cloud": "~6.18.33",
+    "@indigoai-us/hq-cloud": "~6.18.50",
     "@indigoai-us/hq-flags-client": "^0.1.2",
     "@modelcontextprotocol/sdk": "1.29.0",
     "@sentry/node": "^10.49.0",