@indigoai-us/hq-cli 5.345.159 → 5.345.161

package/dist/utils/plan-gate-error.js

@@ -6,9 +6,9 @@
 import { PLAN_LIMIT_DIMENSION_LABELS, renderPersonalPlanFeatureNotice, } from "../lib/plan-limit-nag.js";
 import { withCliLimitEntrySurface } from "../lib/billing/plan-limit-upgrade-url.js";
 import { parseFreeMonth, } from "../lib/billing/free-month.js";
-import { isUsageOnly, pricingPlanFromBody, usageOnlyCardRequiredLines, USAGE_PRICING_POINTER, } from "../lib/billing/usage-only.js";
-/** Legacy plan names and prices a usage-only account must never be shown. */
-const LEGACY_PLAN_COPY = /Starter|Workforce|Individual|\$500|\$50\b|free month|upgrade/i;
+import { isUsageOnly, pricingPlanFromBody, usageOnlyCardRequiredLines, usagePauseFromBody, USAGE_PRICING_POINTER, } from "../lib/billing/usage-only.js";
+/** Retired plan names, prices and offers a usage-only account must never be shown. */
+const LEGACY_PLAN_COPY = /Starter|Workforce|Individual|\$500|\$50\b|free month|upgrade|plan limit/i;
 /** Copy a plan gate with the caller's pricing plan attached. */
 export function withPricingPlan(err, pricingPlan) {
     if (!pricingPlan || err.details.pricingPlan === pricingPlan)
@@ -100,23 +100,28 @@ function planLimitRefusalText(head, details) {
             `${formatResourceAmount(row.resource, row.used)} of ` +
             `${formatResourceAmount(row.resource, row.limit)} used.`);
     }
+    // The free month led to the flat-plan checkout, which is closed; it is
+    // never offered. The way out besides trimming is the switch to usage
+    // pricing, offered only when the server said the company is on an earlier
+    // plan (or that the flat plans are closed to it).
     const fixes = [];
-    const freeMonthUrl = safeUpgradeUrl(details.freeMonth?.url);
-    if (details.freeMonth?.eligible && freeMonthUrl) {
-        fixes.push(`Start your free month — add a card, first month free: ${freeMonthUrl}`);
-    }
     for (const [resource, target] of Object.entries(details.fixOptions ?? {})) {
-        fixes.push(`${resourceFixAction(resource)} to make room (your plan allows ` +
+        fixes.push(`${resourceFixAction(resource)} to make room (the limit is ` +
             `${formatResourceAmount(resource, target)}).`);
     }
     if (fixes.length > 0) {
-        fixes.push("Upgrade your plan.");
+        fixes.push(details.legacyPlansClosed || details.pricingPlan === "current"
+            ? "Switch to usage pricing: no plan fee, and these limits stop applying."
+            : "Open the company's Billing page.");
         lines.push("  Ways to sort it:");
         fixes.forEach((fix, index) => lines.push(`    ${index + 1}. ${fix}`));
     }
     return lines.join("\n");
 }
 function planGateReason(code, details) {
+    // The server's usage pause is the whole answer: its message, nothing added.
+    if (details.usagePause)
+        return details.usagePause.message;
     if (isUsageOnly(details.pricingPlan))
         return usageOnlyPlanGateReason(code, details);
     if (code === "PLAN_LIMIT_EXCEEDED") {
@@ -125,9 +130,9 @@ function planGateReason(code, details) {
             : typeof details.resource === "string" &&
                 typeof details.used === "number" &&
                 typeof details.limit === "number"
-                ? `Starter plan limit reached: ${details.resource} ${details.used}/${details.limit} used.`
+                ? `Limit reached: ${details.resource} ${details.used}/${details.limit} used.`
                 : details.resources?.length || details.fixOptions || details.freeMonth
-                    ? "Your plan limit has been reached."
+                    ? "This account has reached a limit."
                     : undefined;
         if (head)
             return planLimitRefusalText(head, details);
@@ -138,14 +143,19 @@ function planGateReason(code, details) {
         return renderPersonalPlanFeatureNotice(details.feature ?? "this feature", null);
     }
     if (code === "MEETING_PLAN_REQUIRED") {
-        return "HQ Workforce plan required to invite a meeting bot.";
+        return "Meeting notetaker bots are not available on this company's current billing.";
     }
     if (code === "BILLING_REQUIRED") {
-        return "Upgrade the company plan before enrolling an external agent.";
+        return "Set up billing for this company before enrolling an external agent.";
     }
-    return "HQ Workforce plan required for this feature.";
+    return "This feature is not available on this company's current billing.";
 }
-/** One renderer for server-selected upgrade links across CLI plan refusals. */
+/**
+ * One renderer for server-selected billing links across CLI refusals. The
+ * link is labelled `Billing:`, or `Switch:` when the server said it is the
+ * usage-pricing switch page. It never says "Upgrade": the flat plans that
+ * word led to are closed.
+ */
 export function formatUpgradeRefusal(reason, upgradeUrl, options = {}) {
     const safeUrl = safeUpgradeUrl(upgradeUrl);
     const cliLimitUrl = safeUrl ? withCliLimitEntrySurface(safeUrl) : undefined;
@@ -153,7 +163,11 @@ export function formatUpgradeRefusal(reason, upgradeUrl, options = {}) {
         return cliLimitUrl;
     if (!cliLimitUrl)
         return reason;
-    return `${reason}\nUpgrade: ${cliLimitUrl}`;
+    return `${reason}\n${options.legacyPlansClosed ? "Switch" : "Billing"}: ${cliLimitUrl}`;
+}
+/** The link a refusal offers: the usage pause's action, else the server's upgrade URL. */
+export function planGateActionUrl(err) {
+    return err.details.usagePause?.actionUrl ?? err.details.upgradeUrl;
 }
 function safeUpgradeUrl(value) {
     if (typeof value !== "string" ||
@@ -187,6 +201,9 @@ export function companyUidFromPlanUpgradeUrl(value) {
     return match?.[1];
 }
 function formatPlanGateErrorText(code, details) {
+    if (details.usagePause) {
+        return formatUpgradeRefusal(details.usagePause.message, details.usagePause.actionUrl);
+    }
     if (isUsageOnly(details.pricingPlan))
         return planGateReason(code, details);
     return formatUpgradeRefusal(planGateReason(code, details), details.upgradeUrl);
@@ -206,17 +223,21 @@ export function isPlanGateError(err) {
 }
 /** Plain, stable CLI copy for plan-gated resource creation. */
 export function formatPlanGateError(err, options = {}) {
+    // A usage pause: the server's message and its Billing link, nothing else.
+    if (err.details.usagePause) {
+        return formatUpgradeRefusal(err.details.usagePause.message, err.details.usagePause.actionUrl, { urlOnly: options.urlOnly });
+    }
     // A usage-only account has no plan to upgrade to: no upgrade link.
     if (isUsageOnly(err.details.pricingPlan))
         return planGateReason(err.code, err.details);
-    return formatUpgradeRefusal(planGateReason(err.code, err.details), err.details.upgradeUrl, options);
+    return formatUpgradeRefusal(planGateReason(err.code, err.details), err.details.upgradeUrl, { ...options, legacyPlansClosed: err.details.legacyPlansClosed === true });
 }
 export function canOfferTeamUpgrade(argv = process.argv) {
     return Boolean(process.stdin.isTTY && process.stderr.isTTY) &&
         !process.env.CI &&
         !argv.includes("--json");
 }
-/** Ask before opening the exact URL returned by the server. */
+/** Ask before opening the exact billing URL returned by the server. */
 export async function offerUpgradeLink(url, deps = {}) {
     const safeUrl = safeUpgradeUrl(url);
     if (!safeUrl)
@@ -226,13 +247,13 @@ export async function offerUpgradeLink(url, deps = {}) {
         return false;
     let answer;
     if (deps.ask) {
-        answer = await deps.ask("Open upgrade link now? [y/N] ");
+        answer = await deps.ask("Open the billing link now? [y/N] ");
     }
     else {
         const { createInterface } = await import("node:readline/promises");
         const readline = createInterface({ input: process.stdin, output: process.stderr });
         try {
-            answer = await readline.question("Open upgrade link now? [y/N] ");
+            answer = await readline.question("Open the billing link now? [y/N] ");
         }
         finally {
             readline.close();
@@ -249,38 +270,29 @@ export async function offerUpgradeLink(url, deps = {}) {
     }
     return true;
 }
-/** Legacy checkout callback retained for callers outside the shared refusal paths. */
-export async function offerTeamUpgrade(onConfirm, deps = {}) {
-    if (!(deps.interactive ?? canOfferTeamUpgrade(deps.argv)))
-        return false;
-    if (deps.ask) {
-        const answer = await deps.ask("Upgrade now? (opens checkout) [y/N] ");
-        if (!/^y(?:es)?$/i.test(answer.trim()))
-            return false;
-        await onConfirm();
-        return true;
-    }
-    const { createInterface } = await import("node:readline/promises");
-    const readline = createInterface({ input: process.stdin, output: process.stderr });
-    try {
-        const answer = await readline.question("Upgrade now? (opens checkout) [y/N] ");
-        if (!/^y(?:es)?$/i.test(answer.trim()))
-            return false;
-        await onConfirm();
-        return true;
-    }
-    finally {
-        readline.close();
-    }
-}
 /** Decode an already-read JSON envelope from either shared HTTP client. */
 export function planGateErrorFromPayload(status, body, companyUid) {
     if (status !== 402 || !body || typeof body !== "object")
         return null;
     const payload = body;
-    const decoded = decodePlanGatePayload(payload, companyUid);
+    const usagePause = usagePauseFromBody(payload);
+    // A usage pause in a body this decoder does not otherwise know is still a
+    // refusal: the server's message is the whole answer.
+    const decoded = decodePlanGatePayload(payload, companyUid) ??
+        (usagePause
+            ? new PlanGateError("PLAN_LIMIT_EXCEEDED", {
+                reason: usagePause.message,
+                ...(usagePause.actionUrl ? { upgradeUrl: usagePause.actionUrl } : {}),
+                ...(companyUid ? { companyUid } : {}),
+            })
+            : null);
+    if (!decoded)
+        return null;
     const pricingPlan = pricingPlanFromBody(payload);
-    return decoded && pricingPlan ? withPricingPlan(decoded, pricingPlan) : decoded;
+    const withPlan = pricingPlan ? withPricingPlan(decoded, pricingPlan) : decoded;
+    return usagePause
+        ? new PlanGateError(withPlan.code, { ...withPlan.details, usagePause })
+        : withPlan;
 }
 function decodePlanGatePayload(payload, companyUid) {
     // US-054: the personal feature denial. hq-pro identifies it with
@@ -392,6 +404,7 @@ function planLimitRefusalFromPayload(payload, upgradeUrl, companyUid) {
             : undefined;
     const resources = parseResources(payload.resources);
     const fixOptions = parseFixOptions(payload.fixOptions);
+    const legacyPlansClosed = payload.legacyPlansClosed === true;
     const parsedFreeMonth = parseFreeMonth(payload.freeMonth);
     const freeMonthUrl = safeUpgradeUrl(parsedFreeMonth?.url);
     const freeMonth = parsedFreeMonth
@@ -416,6 +429,7 @@ function planLimitRefusalFromPayload(payload, upgradeUrl, companyUid) {
         ...(upgradeUrl ? { upgradeUrl } : {}),
         ...(reason ? { reason } : {}),
         ...(companyUid ? { companyUid } : {}),
+        ...(legacyPlansClosed ? { legacyPlansClosed } : {}),
     });
 }
 /** Wire codes that mark a vault/sync error as a plan-limit refusal. */

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

@@ -136,6 +136,8 @@ export declare function acquireUpdateLock(now?: number): (() => void) | null;
 /** Injectable surface so the flow is unit-testable without network or spawns. */
 export interface SelfUpdateDeps {
     env?: NodeJS.ProcessEnv;
+    /** Platform whose npm launcher layout the update cleans up (tests inject win32). */
+    platform?: NodeJS.Platform;
     currentVersion?: string;
     fetchLatest?: () => Promise<string | null>;
     resolveInstall?: () => RunningInstall;

package/dist/utils/self-update.js

@@ -70,6 +70,7 @@ import { canStageInstall, stagedNpmInstall } from "./staged-install.js";
 import { acquireUpdateLock as acquireSharedUpdateLock } from "./update-lock.js";
 import { markLatestIneffective } from "./version-check.js";
 import { fileSelfUpdateBackoff } from "./self-update-backoff.js";
+import { removeHqCliPs1Shims } from "../lib/windows/ps1-shims.js";
 import { restartDaemonServiceIfInstalled } from "../lib/mesh/live/daemon/install.js";
 import { createCurrentPackageUseLeaseHandoff, PACKAGE_USE_LEASE_HANDOFF_ENV, releaseCurrentPackageUseLease, } from "./package-use-lease.js";
 /**
@@ -1041,6 +1042,13 @@ async function attemptUpdateAndReexec(argv, flavor, known, deps, env) {
             if (!bins.ok)
                 result = bins;
         }
+        // npm regenerates hq.ps1 on every Windows install. PowerShell prefers it to
+        // hq.cmd, and a Restricted execution policy then blocks every hq command.
+        if (result.ok && install.manager === "npm" && install.prefix && (deps.platform ?? process.platform) === "win32") {
+            for (const failure of removeHqCliPs1Shims(install.prefix).failed) {
+                console.error(chalk.yellow(`  Could not remove ${failure.file} (${failure.reason}). In PowerShell, run hq.cmd instead of hq.`));
+            }
+        }
         if (!result.ok && installSnapshot) {
             restoredAfterFailure = restoreInstall(installSnapshot, renamePath);
             if (restoredAfterFailure) {

package/dist/utils/staged-npm-install.js

@@ -4,6 +4,7 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { isMainModule } from "./is-main-module.js";
+import { removeHqCliPs1Shims } from "../lib/windows/ps1-shims.js";
 const PACKAGE_NAME = "@indigoai-us/hq-cli";
 const RANDOM_HEX_BYTES = 6;
 function packageRoot(prefix, platform) {
@@ -53,6 +54,13 @@ function temporaryRoot() {
 function randomSuffix() {
     return randomBytes(RANDOM_HEX_BYTES).toString("hex");
 }
+/** Best effort: a leftover npm hq .ps1 launcher must never fail an otherwise good update. */
+function removeStalePs1Shims(binDir) {
+    const result = removeHqCliPs1Shims(binDir);
+    for (const failure of result.failed) {
+        console.error("[hq-cli-update] could not remove PowerShell launcher; use hq.cmd", failure);
+    }
+}
 function bestEffortRemove(target) {
     if (!target)
         return;
@@ -149,7 +157,8 @@ export function activateStagedNpmPackage(prefix, stagePrefix, platform = process
                 continue;
             const executable = path.join(targetPackage, entry);
             if (platform === "win32") {
-                for (const extension of ["", ".cmd", ".ps1"]) {
+                // No .ps1: PowerShell prefers it over hq.cmd and a Restricted policy blocks it.
+                for (const extension of ["", ".cmd"]) {
                     const stagedFile = path.join(stageBinDir, `${name}${extension}`);
                     if (!existsSync(stagedFile))
                         continue;
@@ -178,7 +187,7 @@ export function activateStagedNpmPackage(prefix, stagePrefix, platform = process
         renameSync(candidatePackage, targetPackage);
         packageActivated = true;
         for (const name of names) {
-            for (const extension of platform === "win32" ? ["", ".cmd", ".ps1"] : [""]) {
+            for (const extension of platform === "win32" ? ["", ".cmd"] : [""]) {
                 const filename = `${name}${extension}`;
                 const target = path.join(targetBinDir, filename);
                 const staged = path.join(stagedBins, filename);
@@ -193,6 +202,8 @@ export function activateStagedNpmPackage(prefix, stagePrefix, platform = process
                 }
             }
         }
+        if (platform === "win32")
+            removeStalePs1Shims(targetBinDir);
         bestEffortRemove(packageBackedUp ? backupPackage : undefined);
         bestEffortRemove(backupBins);
         return { ok: true };

package/dist/utils/team-upgrade.d.ts

@@ -1,6 +1,15 @@
-export interface TeamUpgradeOptions {
-    company?: string;
-    companyUid?: string;
+/**
+ * `hq billing upgrade` for a company not on usage pricing (US-024).
+ *
+ * The flat plans are closed to new subscribers (hq-pro
+ * `billing.legacy-plans-closed`, owner decision 2026-10-19), so there is no
+ * checkout to open. The command points at the console's switch to usage
+ * pricing for the company. It POSTs nothing: the switch itself, and its owner
+ * gate, live on that page.
+ */
+export interface UsageSwitchOptions {
+    /** The company slug, for the company's switch page. */
+    companySlug?: string;
     noBrowser?: boolean;
     /** Testable override for environments where browser availability is known. */
     headless?: boolean;
@@ -9,9 +18,13 @@ export interface TeamUpgradeOptions {
     write?: (text: string) => void;
     error?: (text: string) => void;
 }
+/** The lines printed before the switch page link. Names no plan. */
+export declare function usageSwitchLines(url: string): string[];
+/** The fallback sentence when no console origin can be derived. */
+export declare const USAGE_SWITCH_NO_URL_MESSAGE = "Switch this company to usage pricing from its Billing page in the HQ Console.";
 /**
- * Start the owner-gated HQ Workforce Checkout flow. Stripe collects payment details
- * in its hosted browser page; the CLI never receives card data.
+ * Print (and open, unless told not to) the company's usage-pricing switch
+ * page. Returns the URL, or null when none could be built.
  */
-export declare function upgradeToTeam(opts?: TeamUpgradeOptions): Promise<string>;
+export declare function openUsageSwitch(opts?: UsageSwitchOptions): Promise<string | null>;
 //# sourceMappingURL=team-upgrade.d.ts.map

package/dist/utils/team-upgrade.js

@@ -1,58 +1,56 @@
 import { isHeadless } from "./headless.js";
 import open from "open";
-import { ensureCognitoToken } from "./cognito-session.js";
-import { getCompanyUid, vaultApiFetch } from "./vault-api.js";
-const CHECKOUT_SUCCESS_URL = "https://hq.computer/billing?checkout=success";
-const CHECKOUT_CANCEL_URL = "https://hq.computer/billing?checkout=cancel";
-function ownerUpgradeError() {
-    return Object.assign(new Error("Only a company owner can upgrade. Ask a company owner to upgrade."), { expected: true });
+import { usageSwitchPageUrl } from "../lib/billing/plan-limit-upgrade-url.js";
+import { resolveProcessFlagCompanyContext } from "../lib/process-flag-company-context.js";
+/** The lines printed before the switch page link. Names no plan. */
+export function usageSwitchLines(url) {
+    return [
+        "The flat plans are closed to new subscribers. To move this company onto usage pricing, switch from its Billing page.",
+        "Usage pricing has no plan fee: you pay for what you use.",
+        "Add a card first with `hq billing checkout`, then switch here (company owners only):",
+        url,
+    ];
 }
+/** The fallback sentence when no console origin can be derived. */
+export const USAGE_SWITCH_NO_URL_MESSAGE = "Switch this company to usage pricing from its Billing page in the HQ Console.";
 /**
- * Start the owner-gated HQ Workforce Checkout flow. Stripe collects payment details
- * in its hosted browser page; the CLI never receives card data.
+ * Print (and open, unless told not to) the company's usage-pricing switch
+ * page. Returns the URL, or null when none could be built.
  */
-export async function upgradeToTeam(opts = {}) {
-    const token = await ensureCognitoToken();
-    const companyUid = opts.companyUid ?? await getCompanyUid(token, opts.company);
-    const response = await vaultApiFetch({
-        token,
-        path: "/v1/billing/checkout/team",
-        method: "POST",
-        body: {
-            companyUid,
-            entrySurface: "cli_limit",
-            successUrl: CHECKOUT_SUCCESS_URL,
-            cancelUrl: CHECKOUT_CANCEL_URL,
-        },
-    });
-    if (!response.ok) {
-        const body = (await response.json().catch(() => ({})));
-        if (response.status === 403 || /owner/i.test(`${body.error ?? ""} ${body.message ?? ""}`)) {
-            throw ownerUpgradeError();
+export async function openUsageSwitch(opts = {}) {
+    const write = opts.write ?? ((text) => process.stdout.write(text));
+    const slug = opts.companySlug?.trim() || resolveProcessFlagCompanyContext().companySlug || undefined;
+    const url = usageSwitchPageUrl(slug);
+    if (!url) {
+        if (opts.json) {
+            write(`${JSON.stringify({ url: null, message: USAGE_SWITCH_NO_URL_MESSAGE })}\n`);
         }
-        throw Object.assign(new Error(`Could not start HQ Workforce checkout: ${body.error ?? body.message ?? response.statusText}`), { expected: true });
-    }
-    const { url } = (await response.json());
-    if (typeof url !== "string" || !url) {
-        throw new Error("Checkout response did not include a hosted checkout URL.");
+        else {
+            write(`${USAGE_SWITCH_NO_URL_MESSAGE}\n`);
+        }
+        return null;
     }
-    const write = opts.write ?? ((text) => process.stdout.write(text));
     if (opts.json) {
-        write(`${JSON.stringify({ url })}\n`);
+        write(`${JSON.stringify({
+            url,
+            legacyPlansClosed: true,
+            message: usageSwitchLines(url).slice(0, 3).join(" "),
+        })}\n`);
         return url;
     }
-    write("Opening HQ Workforce checkout ($500/mo) in your browser — finish there and you're upgraded.\n");
+    for (const line of usageSwitchLines(url))
+        write(`${line}\n`);
     const skipBrowser = opts.noBrowser || (opts.headless ?? isHeadless());
-    if (skipBrowser) {
-        write(`Open this URL to continue: ${url}\n`);
-        return url;
-    }
+    if (!skipBrowser)
+        await openInBrowser(url, opts);
+    return url;
+}
+async function openInBrowser(url, opts) {
     try {
         await (opts.openUrl ?? open)(url);
     }
     catch (err) {
         (opts.error ?? ((text) => process.stderr.write(text)))(`Couldn't launch your browser (${err instanceof Error ? err.message : String(err)}). Open this URL to continue: ${url}\n`);
     }
-    return url;
 }
 //# sourceMappingURL=team-upgrade.js.map

package/dist/utils/token-keychain.d.ts

@@ -11,14 +11,15 @@
  *   - signer:  Team ID HWFZ2QDTMR (login-keychain partition `teamid:HWFZ2QDTMR`)
  *
  * The read goes through `/usr/bin/security`, so there is no native module.
- * macOS asks the user once whether `security` may read the item; HQ accepts
+ * macOS may ask whether `security` may read the item; HQ accepts
  * that prompt (owner decision) and explains it first:
  *   - Before the first read, a one-line note is printed to stderr. It is only
- *     shown, and the first read only happens, in an interactive terminal, so
- *     a background process never raises the prompt unexplained.
- *   - A denied prompt, a timeout or any other failure falls back to the file
- *     quietly and is remembered in `~/.hq/keychain-access.json`, so HQ does
- *     not ask again on every run. `hq auth keychain --retry` clears it.
+ *     shown, and the first read only happens, in an interactive terminal.
+ *     A prior success may still have been one-time Allow: it does not prove
+ *     future reads cannot prompt. After a failure, background reads stop.
+ *   - A canceled/refused prompt falls back to the file and suppresses reads
+ *     until `hq auth keychain --retry`. Timeouts and other failures clear
+ *     remembered access: only a future interactive command can ask again.
  *   - "Item not found" is a plain miss and is not remembered as a denial.
  *
  * Choosing between the Keychain and the file (writes still go to the file):
@@ -38,7 +39,7 @@ export declare const KEYCHAIN_TEAM_ID = "HWFZ2QDTMR";
 export declare const KEYCHAIN_READ_TIMEOUT_MS = 3000;
 /** First read: long enough for a person to answer the macOS prompt. */
 export declare const KEYCHAIN_FIRST_READ_TIMEOUT_MS = 60000;
-export declare const KEYCHAIN_FIRST_READ_NOTE = "macOS will ask once whether HQ can read your sign-in from the Keychain. Choose Always Allow.";
+export declare const KEYCHAIN_FIRST_READ_NOTE = "macOS may ask whether HQ can read your sign-in from the Keychain. If asked, enter your login keychain password (usually your Mac login password). Choose Always Allow to avoid repeated prompts.";
 export interface KeychainTokenShape {
     accessToken: string;
     idToken: string;
@@ -55,6 +56,8 @@ export interface KeychainAccessState {
     noteShownAt?: string;
     allowedAt?: string;
     deniedAt?: string;
+    lastFailureAt?: string;
+    failureReason?: "timeout" | "unavailable" | "canceled" | "authorization";
 }
 export interface KeychainReadOptions {
     platform?: NodeJS.Platform;
@@ -69,7 +72,7 @@ export interface KeychainReadOptions {
     retry?: boolean;
     now?: () => Date;
 }
-export type KeychainReadOutcome = "hit" | "miss" | "denied" | "skipped-denied" | "skipped-not-interactive" | "disabled";
+export type KeychainReadOutcome = "hit" | "miss" | "denied" | "skipped-denied" | "skipped-not-interactive" | "unavailable" | "disabled";
 export declare function keychainTokenReadEnabled(opts?: KeychainReadOptions): boolean;
 export declare function keychainAccessStateFile(home?: string): string;
 export declare function readKeychainAccessState(home?: string): KeychainAccessState;

package/dist/utils/token-keychain.js

@@ -11,14 +11,15 @@
  *   - signer:  Team ID HWFZ2QDTMR (login-keychain partition `teamid:HWFZ2QDTMR`)
  *
  * The read goes through `/usr/bin/security`, so there is no native module.
- * macOS asks the user once whether `security` may read the item; HQ accepts
+ * macOS may ask whether `security` may read the item; HQ accepts
  * that prompt (owner decision) and explains it first:
  *   - Before the first read, a one-line note is printed to stderr. It is only
- *     shown, and the first read only happens, in an interactive terminal, so
- *     a background process never raises the prompt unexplained.
- *   - A denied prompt, a timeout or any other failure falls back to the file
- *     quietly and is remembered in `~/.hq/keychain-access.json`, so HQ does
- *     not ask again on every run. `hq auth keychain --retry` clears it.
+ *     shown, and the first read only happens, in an interactive terminal.
+ *     A prior success may still have been one-time Allow: it does not prove
+ *     future reads cannot prompt. After a failure, background reads stop.
+ *   - A canceled/refused prompt falls back to the file and suppresses reads
+ *     until `hq auth keychain --retry`. Timeouts and other failures clear
+ *     remembered access: only a future interactive command can ask again.
  *   - "Item not found" is a plain miss and is not remembered as a denial.
  *
  * Choosing between the Keychain and the file (writes still go to the file):
@@ -44,9 +45,15 @@ export const KEYCHAIN_READ_TIMEOUT_MS = 3_000;
 export const KEYCHAIN_FIRST_READ_TIMEOUT_MS = 60_000;
 /** `security` exit status for errSecItemNotFound. */
 const SECURITY_ITEM_NOT_FOUND = 44;
+/** errSecUserCanceled (-128), truncated to the process exit status. This
+ * cannot distinguish Deny from Cancel: do not retry either automatically. */
+const SECURITY_USER_CANCELED = 128;
+/** errSecAuthFailed (-25293). A denied authorization and a wrong password
+ * cannot be distinguished here, so either requires an explicit retry. */
+const SECURITY_AUTH_FAILED = 51;
 /** Reuse a read within one process for this long (avoids a spawn per request). */
 const READ_CACHE_MS = 30_000;
-export const KEYCHAIN_FIRST_READ_NOTE = "macOS will ask once whether HQ can read your sign-in from the Keychain. Choose Always Allow.";
+export const KEYCHAIN_FIRST_READ_NOTE = "macOS may ask whether HQ can read your sign-in from the Keychain. If asked, enter your login keychain password (usually your Mac login password). Choose Always Allow to avoid repeated prompts.";
 const defaultRunner = (args, timeoutMs) => {
     try {
         const result = spawnSync("/usr/bin/security", args, {
@@ -144,8 +151,8 @@ export function readKeychainTokensDetailed(opts = {}) {
         return { tokens, outcome };
     };
     let state = readKeychainAccessState(home);
-    if (opts.retry && state.deniedAt) {
-        const { deniedAt: _cleared, ...rest } = state;
+    if (opts.retry) {
+        const { deniedAt: _cleared, allowedAt: _allowed, ...rest } = state;
         state = rest;
         writeKeychainAccessState(home, state);
     }
@@ -166,15 +173,23 @@ export function readKeychainTokensDetailed(opts = {}) {
     const run = opts.runSecurity ?? defaultRunner;
     const result = run(["find-generic-password", "-s", KEYCHAIN_SERVICE, "-a", KEYCHAIN_ACCOUNT, "-w"], state.allowedAt ? KEYCHAIN_READ_TIMEOUT_MS : KEYCHAIN_FIRST_READ_TIMEOUT_MS);
     if (result.status === 0 && !result.timedOut) {
-        if (!state.allowedAt)
-            writeKeychainAccessState(home, { ...state, allowedAt: now().toISOString() });
+        const { deniedAt: _denied, lastFailureAt: _failed, failureReason: _reason, ...rest } = state;
+        writeKeychainAccessState(home, { ...rest, allowedAt: now().toISOString() });
         return remember(parseTokenJson(decodeSecurityOutput(result.stdout)), "hit");
     }
     if (result.status === SECURITY_ITEM_NOT_FOUND && !result.timedOut)
         return remember(null, "miss");
-    // Denied, timed out, or failed: fall back quietly and don't ask again.
-    writeKeychainAccessState(home, { ...state, deniedAt: now().toISOString() });
-    return remember(null, "denied");
+    // A previous success does not prove Always Allow: another read may prompt.
+    // Clear it on failure so a background process cannot prompt on the next run.
+    const { allowedAt: _allowed, deniedAt: _denied, ...rest } = state;
+    const lastFailureAt = now().toISOString();
+    if (!result.timedOut && (result.status === SECURITY_USER_CANCELED || result.status === SECURITY_AUTH_FAILED)) {
+        writeKeychainAccessState(home, { ...rest, deniedAt: lastFailureAt, lastFailureAt,
+            failureReason: result.status === SECURITY_USER_CANCELED ? "canceled" : "authorization" });
+        return remember(null, "denied");
+    }
+    writeKeychainAccessState(home, { ...rest, lastFailureAt, failureReason: result.timedOut ? "timeout" : "unavailable" });
+    return remember(null, "unavailable");
 }
 export function readKeychainTokens(opts = {}) {
     return readKeychainTokensDetailed(opts).tokens;
@@ -209,10 +224,16 @@ export function readPersonTokensWithKeychain(file = path.join(os.homedir(), ".hq
     catch {
         fromFile = null;
     }
-    const fromKeychain = readKeychainTokens(opts);
+    const result = readKeychainTokensDetailed(opts);
+    const fromKeychain = result.tokens;
     const chosen = pickNewerSession(fromKeychain, fromFile);
     if (!chosen)
         return { tokens: null, source: "none" };
+    if (chosen === fromFile && (result.outcome === "unavailable" || result.outcome === "denied")
+        && (opts.interactive ?? Boolean(process.stderr.isTTY)) && readCache && !readCache.fallbackNotified) {
+        (opts.notify ?? ((line) => process.stderr.write(`${line}\n`)))("Keychain access did not complete. HQ used your saved sign-in instead.");
+        readCache.fallbackNotified = true;
+    }
     return { tokens: chosen, source: chosen === fromKeychain ? "keychain" : "file" };
 }
 //# sourceMappingURL=token-keychain.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.345.159",
+  "version": "5.345.161",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -52,7 +52,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.97",
+    "@indigoai-us/hq-cloud": "6.18.99",
     "@indigoai-us/hq-flags-client": "^0.1.2",
     "@modelcontextprotocol/sdk": "1.29.0",
     "@sentry/node": "^10.49.0",
@@ -114,11 +114,11 @@
     "*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}": "eslint --cache --no-error-on-unmatched-pattern"
   },
   "optionalDependencies": {
-    "@indigoai-us/hq-hook-win32-x64": "5.345.159",
-    "@indigoai-us/hq-hook-win32-arm64": "5.345.159",
-    "@indigoai-us/hq-hook-darwin-x64": "5.345.159",
-    "@indigoai-us/hq-hook-darwin-arm64": "5.345.159",
-    "@indigoai-us/hq-hook-linux-x64": "5.345.159",
-    "@indigoai-us/hq-hook-linux-arm64": "5.345.159"
+    "@indigoai-us/hq-hook-win32-x64": "5.345.161",
+    "@indigoai-us/hq-hook-win32-arm64": "5.345.161",
+    "@indigoai-us/hq-hook-darwin-x64": "5.345.161",
+    "@indigoai-us/hq-hook-darwin-arm64": "5.345.161",
+    "@indigoai-us/hq-hook-linux-x64": "5.345.161",
+    "@indigoai-us/hq-hook-linux-arm64": "5.345.161"
   }
 }

package/scripts/install-hook-engine.mjs

@@ -1,4 +1,5 @@
 import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 // A source checkout has not built dist during pnpm install. Published tarballs
 // never contain src; a broken tarball warns and keeps existing bash hooks active.
 if (!existsSync(new URL('../dist/lib/hook-engine/resolve.js', import.meta.url)) && existsSync(new URL('../src/index.ts', import.meta.url))) process.exit(0);
@@ -8,3 +9,14 @@ try {
 } catch (error) {
   console.warn(`HQ native hook engine unavailable: ${error instanceof Error ? error.message : String(error)}. Existing bash hooks remain active. Repair: npm install -g @indigoai-us/hq-cli --include=optional`);
 }
+// npm writes hq.ps1 next to hq.cmd on Windows. PowerShell prefers it and the
+// default Restricted execution policy blocks it, so remove hq-cli's own .ps1
+// launchers. Best effort: hq doctor reports any that remain.
+try {
+  const { removePs1ShimsAfterNpmInstall } = await import('../dist/lib/windows/ps1-shims.js');
+  const packageDir = fileURLToPath(new URL('..', import.meta.url));
+  const result = removePs1ShimsAfterNpmInstall(packageDir, { platform: process.platform, global: process.env.npm_config_global === 'true' });
+  for (const failure of result?.failed ?? []) console.warn(`Could not remove ${failure.file} (${failure.reason}). In PowerShell, run hq.cmd instead of hq.`);
+} catch (error) {
+  console.warn(`HQ PowerShell launcher cleanup skipped: ${error instanceof Error ? error.message : String(error)}. If PowerShell blocks hq, run hq.cmd doctor --fix.`);
+}