@indigoai-us/hq-cli 5.345.32 → 5.345.34

package/dist/lib/mesh/story-status.js

@@ -5,27 +5,51 @@ const boardStoryStatusSet = new Set(BOARD_STORY_STATUSES);
  * need attention, while `dropped` is terminal; the Board has only one terminal
  * column (`done`).
  */
+export const LEDGER_STATES = [
+    "todo", "in_progress", "review", "waiting", "blocked", "done", "dropped",
+];
 const LEDGER_STATE_TO_BOARD_STATUS = {
     todo: "queued",
     in_progress: "in_progress",
+    review: "review",
+    // The four-column Board cannot represent waiting separately. Preserve the
+    // ledger state on each story so consumers can distinguish it from blocked.
+    waiting: "queued",
     in_review: "review",
     verification: "review",
     blocked: "review",
     done: "done",
     dropped: "done",
 };
+export const ACCEPTED_LEDGER_STATES = [
+    ...LEDGER_STATES, "in_review", "verification",
+];
+export class UnknownProjectStoryStateError extends Error {
+    source;
+    storyId;
+    value;
+    code = "PROJECT_STORY_STATE_INVALID";
+    constructor(source, storyId, value) {
+        super(`${source}.state for story ${storyId || "<missing id>"} has unsupported value ${JSON.stringify(value)}; accepted: ${ACCEPTED_LEDGER_STATES.join("|")}.`);
+        this.source = source;
+        this.storyId = storyId;
+        this.value = value;
+        this.name = "UnknownProjectStoryStateError";
+    }
+}
 export function mapSourceStoryStatus(story, source) {
+    if (Object.hasOwn(story, "state")) {
+        if (typeof story.state !== "string" || !Object.hasOwn(LEDGER_STATE_TO_BOARD_STATUS, story.state.trim())) {
+            throw new UnknownProjectStoryStateError(source, "id" in story && typeof story.id === "string" ? story.id : "", story.state);
+        }
+    }
     if (story.status !== undefined && story.status !== null) {
         if (typeof story.status !== "string" || !boardStoryStatusSet.has(story.status.trim())) {
             throw new Error(`${source}.status must be queued|in_progress|review|done.`);
         }
         return story.status.trim();
     }
-    if (Object.hasOwn(story, "state")) {
-        if (typeof story.state !== "string" ||
-            !Object.hasOwn(LEDGER_STATE_TO_BOARD_STATUS, story.state.trim())) {
-            throw new Error(`${source}.state must be todo|in_progress|in_review|verification|blocked|done|dropped.`);
-        }
+    if (typeof story.state === "string") {
         return LEDGER_STATE_TO_BOARD_STATUS[story.state.trim()];
     }
     return undefined;
@@ -39,9 +63,10 @@ export function mapReaderStoryStatus(story) {
     if (story.status !== undefined && story.status !== null) {
         return typeof story.status === "string" ? story.status : undefined;
     }
-    if (typeof story.state !== "string")
+    const stateValue = story.state ?? story.ledgerState;
+    if (typeof stateValue !== "string")
         return undefined;
-    const state = story.state.trim();
+    const state = stateValue.trim();
     return Object.hasOwn(LEDGER_STATE_TO_BOARD_STATUS, state)
         ? LEDGER_STATE_TO_BOARD_STATUS[state]
         : undefined;

package/dist/utils/self-update.d.ts

@@ -159,6 +159,8 @@ export interface SelfUpdateDeps {
      * the target we just installed. Defaults to {@link checkUpdateConvergence}.
      */
     checkConvergence?: (targetVersion: string) => boolean;
+    /** Probe the previous command path after a failed install has been rolled back. */
+    checkRestoredInstall?: (targetVersion: string) => boolean;
     /**
      * Persist that `version` installed but never took effect, so the startup path
      * stops auto-retrying it. Defaults to {@link markLatestIneffective}.

package/dist/utils/self-update.js

@@ -65,7 +65,7 @@ import chalk from "chalk";
 import { Sentry } from "../sentry.js";
 import { isCliTelemetryDisabled } from "./cli-telemetry.js";
 import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
-import { buildBunInstallArgv, buildPnpmInstallArgv, buildPrefixedInstallArgv, buildSpawnPlan, canWriteNpmInstall, captureNonWritableNpmPrefixNotice, claimNonWritableNpmPrefixNotice, checkUpdateConvergence, derivePnpmHome, detachUpdateSupervisor, isBunManagedPackageDir, isLocalDependencyInstall, isPnpmManagedPackageDir, nonWritablePrefixNote, openInstallOutput, pnpmUpdateEnv, resolveRunningInstall, runUpdateCommand, runSupervisedUpdateCommand, } from "./version-gate.js";
+import { buildBunInstallArgv, buildPnpmInstallArgv, buildPrefixedInstallArgv, buildSpawnPlan, canWriteNpmInstall, captureNonWritableNpmPrefixNotice, claimNonWritableNpmPrefixNotice, checkUpdateConvergence, derivePnpmHome, detachUpdateSupervisor, isBunManagedPackageDir, isLocalDependencyInstall, isPnpmManagedPackageDir, nonWritablePrefixNote, openInstallOutput, pnpmUpdateEnv, resolveRunningInstall, runUpdateCommand, runSupervisedUpdateCommand, UPDATE_RECURSION_GUARD_ENV, } from "./version-gate.js";
 import { canStageInstall, stagedNpmInstall } from "./staged-install.js";
 import { acquireUpdateLock as acquireSharedUpdateLock } from "./update-lock.js";
 import { markLatestIneffective } from "./version-check.js";
@@ -75,7 +75,7 @@ import { createCurrentPackageUseLeaseHandoff, PACKAGE_USE_LEASE_HANDOFF_ENV, rel
  * Set on the re-exec'd child so it can never self-update (and re-exec) again.
  * One update + one re-exec per user invocation, ever.
  */
-export const REEXEC_GUARD_ENV = "HQ_RESCUE_SELF_UPDATED";
+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;
 /**
@@ -549,7 +549,7 @@ async function fetchLatestVersion() {
  */
 export function buildSelfUpdatePlan(install) {
     if (install.manager === "pnpm")
-        return { cmd: "pnpm", args: buildPnpmInstallArgv() };
+        return { cmd: "pnpm", args: buildPnpmInstallArgv(install) };
     if (install.manager === "bun")
         return { cmd: "bun", args: buildBunInstallArgv() };
     if (install.prefix)
@@ -780,28 +780,43 @@ async function updateAndReexec(argv, flavor, known, deps) {
     }
     const staged = canStageInstall(install) && (await readStagedSelfUpdateFlag(deps, env));
     const renamePath = deps.renamePath ?? fs.renameSync;
-    // The in-place update moves the package aside, and the installer's
-    // supervisor ships inside it, so run the installer through a copy.
-    const supervisor = staged ? null : (deps.detachSupervisor ?? detachUpdateSupervisor)();
     // The staged install keeps the running package in place until the swap and
     // restores it itself, so it takes no snapshot.
+    // The installer supervisor must be copied before snapshotInstall moves the
+    // active package that contains its source.
+    const supervisor = staged ? null : (deps.detachSupervisor ?? detachUpdateSupervisor)();
     const installSnapshot = staged ? null : snapshotInstall(install, renamePath);
     if (!staged && !installSnapshot) {
-        console.error(chalk.dim("  No backup could be made for this hq-cli install; proceeding without rollback protection."));
+        (deps.markIneffective ?? markLatestIneffective)(latest);
+        console.error(chalk.dim(`  Update to hq-cli ${latest} skipped; the current install could not be backed up.`));
+        supervisor?.dispose();
+        releaseLock();
+        return { action: "update-failed", latest };
     }
+    const checkRestoredInstall = deps.checkRestoredInstall ?? ((version) => checkUpdateConvergence(version, {
+        requireEvidence: true,
+        exactVersion: true,
+        currentInstall: () => install,
+    }));
     let result;
     const plan = buildSelfUpdatePlan(install);
-    // A pnpm global install needs PNPM_HOME to find its global bin dir. A
-    // minimal-environment parent (systemd, cron, non-login shell) lacks it and
-    // `pnpm add -g` aborts with ERR_PNPM_NO_GLOBAL_BIN_DIR (exit 1), so the
-    // self-update never lands until the box is next touched from an interactive
-    // shell. Derive PNPM_HOME from the running install so the update works
-    // regardless of the parent environment. No-op for npm/bun and when the
-    // parent already sets PNPM_HOME.
-    const updateEnv = pnpmUpdateEnv(install, env);
+    // pnpm needs its global bin path on PATH. Corepack must also ignore a
+    // packageManager pin in the caller's working directory so this install uses
+    // the system-wide package manager without changing its selected version.
+    const updateEnv = install.manager === "pnpm"
+        ? {
+            ...env,
+            ...(pnpmUpdateEnv(install, env) ?? {}),
+            // Package-manager lifecycle hooks can run hq while this install is still
+            // in progress. They must never start another update or manager lookup.
+            [REEXEC_GUARD_ENV]: "1",
+        }
+        : undefined;
     let restoredAfterFailure = false;
     try {
-        console.error(chalk.dim(`Updating hq-cli ${current} → ${latest}…`));
+        if (flavor.noun !== "command") {
+            console.error(chalk.dim(`Updating hq-cli ${current} → ${latest}…`));
+        }
         const defaultRunner = flavor.verbose ? runUpdateCommand : runUpdateQuiet;
         const runner = deps.runner ?? defaultRunner;
         // Forward env only when PNPM_HOME had to be injected, so the common path
@@ -841,14 +856,21 @@ async function updateAndReexec(argv, flavor, known, deps) {
         }
         if (!result.ok && installSnapshot) {
             restoredAfterFailure = restoreInstall(installSnapshot, renamePath);
-            if (restoredAfterFailure)
-                discardInstallSnapshot(installSnapshot);
+            if (restoredAfterFailure) {
+                restoredAfterFailure = checkRestoredInstall(current);
+                if (restoredAfterFailure)
+                    discardInstallSnapshot(installSnapshot);
+            }
         }
     }
     catch (error) {
         if (installSnapshot) {
-            if (restoreInstall(installSnapshot, renamePath))
+            if (restoreInstall(installSnapshot, renamePath) && checkRestoredInstall(current)) {
                 discardInstallSnapshot(installSnapshot);
+            }
+            else {
+                console.error(chalk.red("  Could not restore and verify the previous hq-cli install after the update process failed."));
+            }
         }
         throw error;
     }
@@ -857,6 +879,12 @@ async function updateAndReexec(argv, flavor, known, deps) {
         releaseLock();
     }
     if (!result.ok) {
+        (deps.markIneffective ?? markLatestIneffective)(latest);
+        if (flavor.noun === "command") {
+            await captureSelfUpdateOutcome("update-failed", current, latestValid, install.manager, result, env, false);
+            console.error(chalk.yellow(`⚠ hq-cli update to ${latest} failed; continuing on ${current}.`));
+            return { action: "update-failed", latest };
+        }
         if (restoredAfterFailure) {
             console.error(chalk.dim("  The previous hq-cli install was restored."));
         }
@@ -902,8 +930,6 @@ async function updateAndReexec(argv, flavor, known, deps) {
         }
         return { action: "update-failed", latest };
     }
-    if (installSnapshot)
-        discardInstallSnapshot(installSnapshot);
     // Read-your-writes: a "successful" `npm install -g` proves only that the
     // prefix was rewritten, NOT that the `hq` this user's PATH resolves is the
     // copy we just wrote. When a ghost/shadowing install keeps winning PATH
@@ -917,14 +943,26 @@ async function updateAndReexec(argv, flavor, known, deps) {
     // So verify before announcing success. On non-convergence: mark the target
     // ineffective (suppresses auto-retry for a cooldown), skip the pointless
     // re-exec into a stale copy, and let the command run on the current version.
-    const checkConvergence = deps.checkConvergence ?? checkUpdateConvergence;
+    const checkConvergence = deps.checkConvergence ?? ((version) => checkUpdateConvergence(version, { requireEvidence: true, currentInstall: () => install }));
     const converged = checkConvergence(latestValid);
     if (converged === false) {
+        let restored = true;
+        if (installSnapshot) {
+            restored = restoreInstall(installSnapshot, renamePath);
+            if (restored)
+                restored = checkRestoredInstall(current);
+            if (restored)
+                discardInstallSnapshot(installSnapshot);
+            else
+                console.error(chalk.red("  Could not restore and verify the previous hq-cli install after verification failed."));
+        }
         (deps.markIneffective ?? markLatestIneffective)(latest);
         console.error(chalk.dim(`  Continuing the ${flavor.noun} on ${current}.`));
         await captureSelfUpdateOutcome("update-ineffective", current, latestValid, install.manager, undefined, env, flavor.noun === "rescue");
-        return { action: "update-ineffective", latest };
+        return { action: restored ? "update-ineffective" : "update-failed", latest };
     }
+    if (installSnapshot)
+        discardInstallSnapshot(installSnapshot);
     // A resident mesh daemon keeps the old JS loaded after a global install.
     // Service restart is best-effort and cannot turn a successful update red.
     try {

package/dist/utils/version-check.d.ts

@@ -16,7 +16,7 @@ export declare function staleAgainstCachedLatest(now?: number): string | null;
 /**
  * Record that installing `version` did not move the on-PATH `hq` forward, so
  * {@link staleAgainstCachedLatest} stops auto-retrying it for a cooldown. Called
- * by the self-updater's convergence check. Best-effort: a write failure only
+ * by the self-updater after an install failure or failed convergence check. Best-effort: a write failure only
  * means the loop guard is skipped this once, never a broken CLI.
  */
 export declare function markLatestIneffective(version: string, now?: number): void;

package/dist/utils/version-check.js

@@ -15,7 +15,7 @@ export const CLI_VERSION_NUDGE_FLAG = "cli.version-update-nudge";
  * break the per-invocation loop on a busy agent box, short enough that a box
  * whose PATH is later fixed recovers on its own without a manual `hq rescue`.
  */
-const INEFFECTIVE_COOLDOWN_MS = 6 * 60 * 60 * 1000; // 6h
+const INEFFECTIVE_COOLDOWN_MS = 24 * 60 * 60 * 1000; // 24h
 function cachePath() {
     return path.join(os.homedir(), ".hq", "version-check.json");
 }
@@ -157,7 +157,7 @@ export function staleAgainstCachedLatest(now = Date.now()) {
 /**
  * Record that installing `version` did not move the on-PATH `hq` forward, so
  * {@link staleAgainstCachedLatest} stops auto-retrying it for a cooldown. Called
- * by the self-updater's convergence check. Best-effort: a write failure only
+ * by the self-updater after an install failure or failed convergence check. Best-effort: a write failure only
  * means the loop guard is skipped this once, never a broken CLI.
  */
 export function markLatestIneffective(version, now = Date.now()) {

package/dist/utils/version-gate.d.ts

@@ -29,6 +29,8 @@
  */
 import { buildSpawnPlan, quoteForWindowsShell } from "./windows-spawn.js";
 import { type UpdateLockHandle } from "./update-lock.js";
+/** Prevent an update package manager's lifecycle child from starting another updater. */
+export declare const UPDATE_RECURSION_GUARD_ENV = "HQ_RESCUE_SELF_UPDATED";
 export type VersionGatePhase = "preflight" | "lock_acquired" | "installer_running" | "verifying" | "rollback" | "complete" | "failed" | "unknown";
 /** The last closed version-gate phase observed in this process. */
 export declare function getVersionGatePhase(): VersionGatePhase;
@@ -205,19 +207,13 @@ export declare function nonWritablePrefixNote(prefix: string, platform?: NodeJS.
  */
 export declare function derivePnpmHome(install: RunningInstall): string | null;
 /**
- * Environment for the pnpm self-update spawn. `pnpm add -g` aborts with
- * `ERR_PNPM_NO_GLOBAL_BIN_DIR` (exit 1) when neither `PNPM_HOME` nor a
- * `global-bin-dir` setting is present — the exact failure seen when `hq`
- * self-updates from a minimal-environment parent (a systemd `--user` service,
- * cron, or any non-login shell that never sourced the profile exporting
- * `PNPM_HOME`). When the running install is pnpm-managed and the parent lacks
- * `PNPM_HOME`, inject one derived from the install's own path so the update can
- * find the global bin dir it is about to rewrite.
- *
- * A no-op for npm/bun installs, and for any environment that already sets
- * `PNPM_HOME` (never overridden — the caller's value wins). Returns `undefined`
- * when nothing needs injecting, so callers can spawn with the inherited
- * environment unchanged (and pass no `env` at all).
+ * Environment for the pnpm self-update spawn. pnpm requires its configured
+ * global bin directory to be on PATH; pnpm 12.5.1 reports
+ * `ERR_PNPM_GLOBAL_BIN_DIR_NOT_IN_PATH` otherwise. Minimal-environment parents
+ * may also lack PNPM_HOME, so derive it from the running install when needed.
+ *
+ * A no-op for npm/bun installs. Never override a caller's PNPM_HOME. Returns
+ * `undefined` only when the inherited environment already has both values.
  */
 export declare function pnpmUpdateEnv(install: RunningInstall, base?: NodeJS.ProcessEnv): NodeJS.ProcessEnv | undefined;
 export declare function buildPrefixedInstallArgv(prefix: string): string[];
@@ -226,7 +222,16 @@ export declare function buildPrefixedInstallArgv(prefix: string): string[];
  * PATH shim as part of the install, so the next invocation genuinely resolves
  * the new version — which is the whole point of routing here instead of npm.
  */
-export declare function buildPnpmInstallArgv(): string[];
+export declare function buildPnpmInstallArgv(install?: RunningInstall): string[];
+/**
+ * Read the pnpm global install's current store and virtual-store locations.
+ * Newer pnpm versions can change both defaults, so a self-update must carry
+ * forward the paths recorded for the install it is replacing.
+ */
+export declare function pnpmInstallDirs(install: RunningInstall): {
+    storeDir: string;
+    virtualStoreDir: string;
+} | null;
 /** Argv for updating a Bun-managed global install. */
 export declare function buildBunInstallArgv(): string[];
 /**
@@ -419,6 +424,8 @@ declare function probeCliVersion(bin: string): string | null;
  * here may crash or block the CLI.
  */
 export declare function checkUpdateConvergence(targetVersion: string, deps?: {
+    requireEvidence?: boolean;
+    exactVersion?: boolean;
     resolveBin?: () => string | null;
     probeVersion?: (bin: string) => string | null;
     currentInstall?: () => RunningInstall;

package/dist/utils/version-gate.js

@@ -35,6 +35,7 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import chalk from "chalk";
+import * as yaml from "js-yaml";
 import semver from "semver";
 import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
 import { isVersionRequest } from "../version-request.js";
@@ -42,6 +43,8 @@ import { Sentry } from "../sentry.js";
 import { isCliTelemetryDisabled } from "./cli-telemetry.js";
 import { DEFAULT_VAULT_API_URL } from "./cognito-session.js";
 import { acquireUpdateLock, } from "./update-lock.js";
+/** Prevent an update package manager's lifecycle child from starting another updater. */
+export const UPDATE_RECURSION_GUARD_ENV = "HQ_RESCUE_SELF_UPDATED";
 const CLIENT_ID = "hq-cli";
 const ENDPOINT_PATH = "/v1/client-version/check";
 const FETCH_TIMEOUT_MS = 3_000;
@@ -572,27 +575,45 @@ export function derivePnpmHome(install) {
     return home || null;
 }
 /**
- * Environment for the pnpm self-update spawn. `pnpm add -g` aborts with
- * `ERR_PNPM_NO_GLOBAL_BIN_DIR` (exit 1) when neither `PNPM_HOME` nor a
- * `global-bin-dir` setting is present — the exact failure seen when `hq`
- * self-updates from a minimal-environment parent (a systemd `--user` service,
- * cron, or any non-login shell that never sourced the profile exporting
- * `PNPM_HOME`). When the running install is pnpm-managed and the parent lacks
- * `PNPM_HOME`, inject one derived from the install's own path so the update can
- * find the global bin dir it is about to rewrite.
+ * Environment for the pnpm self-update spawn. pnpm requires its configured
+ * global bin directory to be on PATH; pnpm 12.5.1 reports
+ * `ERR_PNPM_GLOBAL_BIN_DIR_NOT_IN_PATH` otherwise. Minimal-environment parents
+ * may also lack PNPM_HOME, so derive it from the running install when needed.
  *
- * A no-op for npm/bun installs, and for any environment that already sets
- * `PNPM_HOME` (never overridden — the caller's value wins). Returns `undefined`
- * when nothing needs injecting, so callers can spawn with the inherited
- * environment unchanged (and pass no `env` at all).
+ * A no-op for npm/bun installs. Never override a caller's PNPM_HOME. Returns
+ * `undefined` only when the inherited environment already has both values.
  */
 export function pnpmUpdateEnv(install, base = process.env) {
-    if (install.manager !== "pnpm" || base.PNPM_HOME)
+    if (install.manager !== "pnpm")
         return undefined;
-    const home = derivePnpmHome(install);
+    const home = base.PNPM_HOME || derivePnpmHome(install);
     if (!home)
         return undefined;
-    return { ...base, PNPM_HOME: home };
+    const binDir = path.join(home, "bin");
+    const pathKey = Object.keys(base).find((key) => key.toLowerCase() === "path") ?? "PATH";
+    const currentPath = base[pathKey] ?? "";
+    const normalizedBinDir = path.resolve(binDir);
+    const alreadyOnPath = currentPath.split(path.delimiter).some((entry) => {
+        if (!entry)
+            return false;
+        const normalizedEntry = path.resolve(entry);
+        return process.platform === "win32"
+            ? normalizedEntry.toLowerCase() === normalizedBinDir.toLowerCase()
+            : normalizedEntry === normalizedBinDir;
+    });
+    const result = {
+        ...base,
+        [UPDATE_RECURSION_GUARD_ENV]: "1",
+        // Corepack otherwise honors the packageManager in the user's current
+        // project, which can silently switch the update subprocess to that version.
+        COREPACK_ENABLE_PROJECT_SPEC: "0",
+        COREPACK_DEFAULT_TO_LATEST: "0",
+    };
+    if (!base.PNPM_HOME)
+        result.PNPM_HOME = home;
+    if (!alreadyOnPath)
+        result[pathKey] = [currentPath, binDir].filter(Boolean).join(path.delimiter);
+    return Object.keys(result).some((key) => result[key] !== base[key]) ? result : undefined;
 }
 export function buildPrefixedInstallArgv(prefix) {
     return ["install", "-g", "--prefix", prefix, LATEST_PACKAGE_SPEC];
@@ -602,8 +623,51 @@ export function buildPrefixedInstallArgv(prefix) {
  * PATH shim as part of the install, so the next invocation genuinely resolves
  * the new version — which is the whole point of routing here instead of npm.
  */
-export function buildPnpmInstallArgv() {
-    return ["add", "-g", LATEST_PACKAGE_SPEC];
+export function buildPnpmInstallArgv(install) {
+    const args = ["add", "-g", LATEST_PACKAGE_SPEC];
+    const dirs = install ? pnpmInstallDirs(install) : null;
+    if (dirs)
+        args.push("--store-dir", dirs.storeDir, "--virtual-store-dir", dirs.virtualStoreDir);
+    return args;
+}
+/**
+ * Read the pnpm global install's current store and virtual-store locations.
+ * Newer pnpm versions can change both defaults, so a self-update must carry
+ * forward the paths recorded for the install it is replacing.
+ */
+export function pnpmInstallDirs(install) {
+    if (install.manager !== "pnpm" || !install.packageRoot)
+        return null;
+    const normalized = install.packageRoot.replace(/\\/g, "/");
+    const global = normalized.match(/^(.*\/global\/\d+\/node_modules)(?:\/|$)|^(.*\/global\/v\d+\/[^/]+\/node_modules)(?:\/|$)/);
+    const globalNodeModules = global?.[1] ?? global?.[2];
+    if (!globalNodeModules)
+        return null;
+    const metadataPath = path.join(globalNodeModules, ".modules.yaml");
+    try {
+        const metadata = yaml.load(readFileSync(metadataPath, "utf8"));
+        const storeDir = typeof metadata?.storeDir === "string" && metadata.storeDir
+            ? metadata.storeDir
+            : path.join(derivePnpmHome(install) ?? path.dirname(path.dirname(globalNodeModules)), "store", "v11");
+        const configuredVirtualStore = typeof metadata?.virtualStoreDir === "string"
+            ? metadata.virtualStoreDir
+            : ".pnpm";
+        const virtualStoreDir = path.isAbsolute(configuredVirtualStore)
+            ? configuredVirtualStore
+            : path.resolve(globalNodeModules, configuredVirtualStore);
+        return { storeDir, virtualStoreDir };
+    }
+    catch {
+        // The metadata file is absent in older pnpm global layouts. The global
+        // install root still determines its virtual store and default PNPM_HOME.
+        const pnpmHome = derivePnpmHome(install);
+        if (!pnpmHome)
+            return null;
+        return {
+            storeDir: path.join(pnpmHome, "store", "v11"),
+            virtualStoreDir: path.join(globalNodeModules, ".pnpm"),
+        };
+    }
 }
 /** Argv for updating a Bun-managed global install. */
 export function buildBunInstallArgv() {
@@ -1078,7 +1142,7 @@ function performUpdate(command, runner = runUpdateCommand) {
  */
 function manualUpdateCommand(install, decision) {
     if (install.manager === "pnpm")
-        return `pnpm ${buildPnpmInstallArgv().join(" ")}`;
+        return `pnpm ${buildPnpmInstallArgv(install).join(" ")}`;
     if (install.manager === "bun")
         return `bun ${buildBunInstallArgv().join(" ")}`;
     if (install.prefix)
@@ -1112,7 +1176,7 @@ function nudgeUpdateRecommended(decision, install = resolveRunningInstall()) {
         return;
     }
     const command = install.manager === "pnpm"
-        ? `pnpm ${buildPnpmInstallArgv().join(" ")}`
+        ? `pnpm ${buildPnpmInstallArgv(install).join(" ")}`
         : install.manager === "bun"
             ? `bun ${buildBunInstallArgv().join(" ")}`
             : decision.updateCommand;
@@ -1193,7 +1257,8 @@ export function parseReportedCliVersion(stdout) {
 /** `<bin> --version` output (trimmed), or null on any failure/timeout. */
 function probeCliVersion(bin) {
     try {
-        const result = spawnSync(bin, ["--version"], {
+        const isJavaScriptEntry = path.extname(bin).toLowerCase() === ".js";
+        const result = spawnSync(isJavaScriptEntry ? process.execPath : bin, isJavaScriptEntry ? [bin, "--version"] : ["--version"], {
             encoding: "utf-8",
             timeout: CONVERGENCE_TIMEOUT_MS,
         });
@@ -1224,19 +1289,30 @@ function probeCliVersion(bin) {
  */
 export function checkUpdateConvergence(targetVersion, deps = {}) {
     try {
-        const bin = (deps.resolveBin ?? resolveHqOnPath)();
+        let bin;
+        try {
+            bin = (deps.resolveBin ?? resolveHqOnPath)();
+        }
+        catch {
+            bin = null;
+        }
         if (!bin) {
-            console.error(chalk.yellow("⚠ Updated, but couldn't resolve `hq` on PATH to verify the new version took effect."));
-            // Unverifiable, not disproven — the caller keeps its success report.
-            return true;
+            const install = (deps.currentInstall ?? resolveRunningInstall)();
+            bin = installedHqEntryPoint(install);
+            if (!bin) {
+                console.error(chalk.yellow("⚠ Updated, but couldn't resolve `hq` on PATH or from the install to verify the new version took effect."));
+                return !deps.requireEvidence;
+            }
         }
         const reported = (deps.probeVersion ?? probeCliVersion)(bin);
         if (!reported) {
             console.error(chalk.yellow(`⚠ Updated, but \`${bin} --version\` did not respond — couldn't verify the new version took effect.`));
-            return true; // unverifiable, see above
+            return !deps.requireEvidence; // unverifiable, see above
         }
         if (reported === targetVersion)
             return true; // converged — the normal case
+        if (deps.exactVersion)
+            return false;
         //
         // The install runs `@latest`, not `@<targetVersion>`, so it can legitimately
         // land a version NEWER than the `latestVersion` the gate was handed: the npm
@@ -1284,8 +1360,23 @@ export function checkUpdateConvergence(targetVersion, deps = {}) {
         return false;
     }
     catch {
-        // Verification is best-effort; never break the CLI over a probe.
-        return true;
+        // Keep the current fail-closed behavior for a thrown version probe: an
+        // exception may mean the newly-written executable cannot be loaded.
+        return !deps.requireEvidence;
+    }
+}
+function installedHqEntryPoint(install) {
+    if (!install.packageRoot)
+        return null;
+    try {
+        const manifest = JSON.parse(readFileSync(path.join(install.packageRoot, "package.json"), "utf8"));
+        const entry = typeof manifest.bin === "string" ? manifest.bin : manifest.bin?.hq;
+        return typeof entry === "string" && entry
+            ? path.resolve(install.packageRoot, entry)
+            : null;
+    }
+    catch {
+        return null;
     }
 }
 /**
@@ -1404,7 +1495,7 @@ function attemptRequiredUpdate(decision, deps, install) {
     let primaryArgs;
     if (install.manager === "pnpm") {
         primaryCmd = "pnpm";
-        primaryArgs = buildPnpmInstallArgv();
+        primaryArgs = buildPnpmInstallArgv(install);
     }
     else if (install.manager === "bun") {
         primaryCmd = "bun";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.345.32",
+  "version": "5.345.34",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -47,6 +47,7 @@
   "dependencies": {
     "@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-flags-client": "^0.1.2",
     "@modelcontextprotocol/sdk": "1.29.0",
@@ -59,6 +60,7 @@
     "js-yaml": "^4.1.0",
     "mqtt": "5.15.2",
     "open": "^10.1.0",
+    "pg": "^8.23.1",
     "semver": "^7.8.5",
     "simple-git": "^3.27.0",
     "smol-toml": "1.6.1",
@@ -69,6 +71,7 @@
     "@types/better-sqlite3": "^7.6.13",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.0.0",
+    "@types/pg": "^8.23.1",
     "@types/semver": "^7.8.0",
     "@vitest/coverage-v8": "4.1.6",
     "aedes": "1.1.2",