@indigoai-us/hq-cli 5.345.159 → 5.345.161

package/dist/commands/core-session-journal-native.js

@@ -1,5 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
 const USAGE = `session-journal.sh: usage:
   session-journal.sh write "<title>" [--files f1,f2,...] [--body-file PATH] [--session KEY]
@@ -163,6 +164,58 @@ function isAgedPidlessCounterLock(lock, now) {
         return false;
     }
 }
+function reclaimStaleCounterTempDirs(lock, now) {
+    const parent = path.dirname(lock);
+    // Publishers create <lock>.tmp.XXXXXX, matching the shell helper. Older native
+    // builds used <lock>.tmp-XXXXXX, so reclaim aged orphans with either prefix.
+    const prefixes = [`${path.basename(lock)}.tmp.`, `${path.basename(lock)}.tmp-`];
+    let names;
+    try {
+        names = fs.readdirSync(parent);
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        if (!prefixes.some((prefix) => name.startsWith(prefix)))
+            continue;
+        const temp = path.join(parent, name);
+        if (!isAgedPidlessCounterLock(temp, now))
+            continue;
+        const read = (file) => {
+            try {
+                return fs.readFileSync(path.join(temp, file), "utf8").trim();
+            }
+            catch {
+                return "";
+            }
+        };
+        const owner = read("pid");
+        const windowsOwner = read("winpid");
+        const token = read("owner-token");
+        if (owner && !/^\d+$/u.test(owner))
+            continue;
+        if (windowsOwner && !/^\d+$/u.test(windowsOwner))
+            continue;
+        if (owner && Number(owner) > 1 && counterLockOwnerIsAlive(temp, Number(owner)))
+            continue;
+        if (!owner && windowsOwner && Number(windowsOwner) > 1 && processIsAlive(Number(windowsOwner)))
+            continue;
+        if (read("pid") !== owner || read("winpid") !== windowsOwner || read("owner-token") !== token
+            || !isAgedPidlessCounterLock(temp, now))
+            continue;
+        if (owner && counterLockOwnerIsAlive(temp, Number(owner)))
+            continue;
+        if (windowsOwner && Number(windowsOwner) > 1 && processIsAlive(Number(windowsOwner)))
+            continue;
+        const stale = `${temp}.stale-${process.pid}-${Math.random().toString(16).slice(2)}`;
+        try {
+            fs.renameSync(temp, stale);
+            fs.rmSync(stale, { recursive: true, force: true });
+        }
+        catch { /* another waiter cleaned it or the owner resumed */ }
+    }
+}
 function reclaimStaleCounterLock(lock, now) {
     let rawOwner;
     try {
@@ -184,6 +237,11 @@ function reclaimStaleCounterLock(lock, now) {
         return false;
     const owner = rawOwner ? Number.parseInt(rawOwner, 10) : 0;
     const windowsOwner = rawWindowsPid ? Number.parseInt(rawWindowsPid, 10) : 0;
+    let observedToken = "";
+    try {
+        observedToken = fs.readFileSync(path.join(lock, "owner-token"), "utf8").trim();
+    }
+    catch { /* legacy lock */ }
     if (rawOwner && (owner <= 1 || counterLockOwnerIsAlive(lock, owner)))
         return false;
     if (!rawOwner && windowsOwner > 1 && processIsAlive(windowsOwner))
@@ -219,7 +277,12 @@ function reclaimStaleCounterLock(lock, now) {
     catch {
         currentRawWindowsPid = "";
     }
-    const sameOwner = currentRawOwner === rawOwner && currentRawWindowsPid === rawWindowsPid;
+    let currentToken = "";
+    try {
+        currentToken = fs.readFileSync(path.join(lock, "owner-token"), "utf8").trim();
+    }
+    catch { /* legacy lock */ }
+    const sameOwner = currentRawOwner === rawOwner && currentRawWindowsPid === rawWindowsPid && currentToken === observedToken;
     const stillStale = rawOwner
         ? sameOwner && !counterLockOwnerIsAlive(lock, owner)
         : sameOwner && !(windowsOwner > 1 && processIsAlive(windowsOwner)) && isAgedPidlessCounterLock(lock, now);
@@ -239,7 +302,15 @@ function reclaimStaleCounterLock(lock, now) {
     catch { /* best effort */ }
     return false;
 }
-function withCounterLock(lock, env, writers, now, action) {
+function readLockToken(lock) {
+    try {
+        return fs.readFileSync(path.join(lock, "owner-token"), "utf8").trim();
+    }
+    catch {
+        return "";
+    }
+}
+function withCounterLock(lock, env, writers, now, action, beforeCounterAction) {
     let i = 0;
     let acquired = false;
     let tries = env.HQ_JOURNAL_COUNTER_LOCK_TRIES ?? "250";
@@ -247,22 +318,82 @@ function withCounterLock(lock, env, writers, now, action) {
         tries = "250";
     const retryLimit = Number.parseInt(tries, 10);
     while (i < retryLimit) {
+        reclaimStaleCounterTempDirs(lock, now);
         try {
-            fs.mkdirSync(lock);
-            acquired = true;
+            const temp = fs.mkdtempSync(`${lock}.tmp.`);
+            const ownerToken = randomUUID();
             try {
                 if (process.platform === "win32")
-                    fs.writeFileSync(path.join(lock, "winpid"), `${process.pid}\n`, { flag: "wx" });
-                fs.writeFileSync(path.join(lock, "pid"), `${process.pid}\n`, { flag: "wx" });
+                    fs.writeFileSync(path.join(temp, "winpid"), `${process.pid}\n`, { flag: "wx" });
+                fs.writeFileSync(path.join(temp, "pid"), `${process.pid}\n`, { flag: "wx" });
+                fs.writeFileSync(path.join(temp, "owner-token"), `${ownerToken}\n`, { flag: "wx" });
+                const publishClaim = `${lock}.publish`;
+                try {
+                    fs.mkdirSync(publishClaim);
+                }
+                catch (error) {
+                    try {
+                        fs.rmSync(temp, { recursive: true, force: true });
+                    }
+                    catch { /* best effort */ }
+                    if (error.code === "EEXIST" && reclaimStaleCounterLock(publishClaim, now))
+                        continue;
+                    throw error;
+                }
+                try {
+                    fs.writeFileSync(path.join(publishClaim, "owner-token"), `${ownerToken}\n`, { flag: "wx" });
+                    fs.writeFileSync(path.join(publishClaim, "pid"), `${process.pid}\n`, { flag: "wx" });
+                    // renameSync can replace an existing empty PID-less directory on
+                    // POSIX. Refuse a pre-existing lock while publishers are serialized.
+                    if (readLockToken(publishClaim) !== ownerToken || fs.existsSync(lock))
+                        throw new Error("counter lock already exists");
+                    fs.renameSync(temp, lock);
+                }
+                finally {
+                    if (readLockToken(publishClaim) === ownerToken)
+                        fs.rmSync(publishClaim, { recursive: true, force: true });
+                }
+                acquired = true;
             }
-            catch {
+            catch (error) {
+                try {
+                    fs.rmSync(temp, { recursive: true, force: true });
+                }
+                catch { /* best effort */ }
+                throw error;
+            }
+            if (!acquired)
+                continue;
+            if (readLockToken(lock) !== ownerToken) {
+                acquired = false;
+                i++;
+                continue;
+            }
+            beforeCounterAction?.();
+            if (readLockToken(lock) !== ownerToken) {
+                acquired = false;
+                i++;
+                continue;
+            }
+            const completed = action(ownerToken);
+            if (!completed) {
+                if (readLockToken(lock) === ownerToken) {
+                    try {
+                        fs.rmSync(lock, { recursive: true, force: true });
+                    }
+                    catch { /* best effort */ }
+                }
+                acquired = false;
+                i++;
+                continue;
+            }
+            if (readLockToken(lock) === ownerToken) {
                 try {
                     fs.rmSync(lock, { recursive: true, force: true });
                 }
                 catch { /* best effort */ }
-                return;
             }
-            break;
+            return;
         }
         catch {
             if (reclaimStaleCounterLock(lock, now))
@@ -276,22 +407,6 @@ function withCounterLock(lock, env, writers, now, action) {
         writers.stderr("session-journal: tool-counter: lock remained busy; skipped update\n");
         return;
     }
-    try {
-        action();
-    }
-    finally {
-        let owner = 0;
-        try {
-            owner = Number.parseInt(fs.readFileSync(path.join(lock, "pid"), "utf8"), 10) || 0;
-        }
-        catch { /* lock disappeared */ }
-        if (owner === process.pid) {
-            try {
-                fs.rmSync(lock, { recursive: true, force: true });
-            }
-            catch { /* best effort */ }
-        }
-    }
 }
 function nextSequence(dir) {
     let names = [];
@@ -313,7 +428,7 @@ function options(args, valueFlags) {
     }
     return values;
 }
-function runToolCounter(root, action, sessionArg, env, now, writers) {
+function runToolCounter(root, action, sessionArg, env, now, writers, beforeCounterAction) {
     const rawKey = sessionArg || env.HQ_JOURNAL_SESSION || env.HQ_HOOK_SESSION_ID || "";
     const key = counterKey(rawKey);
     const date = now().toISOString().slice(0, 10);
@@ -335,27 +450,36 @@ function runToolCounter(root, action, sessionArg, env, now, writers) {
         writers.stderr(`${sessionJournalAsset}: line ${line}: ${printableCounter}: Is a directory\n`);
     };
     if (action === "increment") {
-        withCounterLock(lock, env, writers, now, () => {
+        withCounterLock(lock, env, writers, now, (ownerToken) => {
+            if (readLockToken(lock) !== ownerToken)
+                return false;
+            const next = readCounter(counter) + 1;
+            if (readLockToken(lock) !== ownerToken)
+                return false;
             try {
-                fs.writeFileSync(counter, `${readCounter(counter) + 1}\n`);
+                fs.writeFileSync(counter, `${next}\n`);
             }
             catch (error) {
-                reportDirectoryWriteFailure(error, 457);
+                reportDirectoryWriteFailure(error, 545);
             }
-        });
+            return true;
+        }, beforeCounterAction);
     }
     else if (action === "read") {
         writers.stdout(`${readCounter(counter)}\n`);
     }
     else if (action === "reset") {
-        withCounterLock(lock, env, writers, now, () => {
+        withCounterLock(lock, env, writers, now, (ownerToken) => {
+            if (readLockToken(lock) !== ownerToken)
+                return false;
             try {
                 fs.writeFileSync(counter, "0\n");
             }
             catch (error) {
-                reportDirectoryWriteFailure(error, 465);
+                reportDirectoryWriteFailure(error, 556);
             }
-        });
+            return true;
+        }, beforeCounterAction);
     }
     else {
         writers.stderr("session-journal: tool-counter: subcommand required (increment|read|reset)\n");
@@ -519,7 +643,7 @@ function executeSessionJournal(args, cwd, hqRoot, dependencies, writers) {
     if (command === "tool-counter") {
         const action = rest[0] ?? "";
         const session = options(rest.slice(1), ["--session"]).get("--session") ?? "";
-        runToolCounter(root, action, session, runtime.env, runtime.now, writers);
+        runToolCounter(root, action, session, runtime.env, runtime.now, writers, dependencies.beforeCounterAction);
         return 0;
     }
     writers.stderr(USAGE);

package/dist/commands/db-remote-deps.js

@@ -74,7 +74,18 @@ export function describeRemoteError(error) {
         return "Remote databases are not available yet.";
     }
     if (status === 402 || code === "PLAN_REQUIRED") {
-        return "Remote databases require the Team plan.";
+        // US-024: the server's usage pause message, else its own sentence. The
+        // CLI names no plan: the flat plans are closed.
+        const pause = error.usagePause;
+        if (pause && typeof pause.message === "string" && pause.message) {
+            return typeof pause.actionUrl === "string" && pause.actionUrl
+                ? `${pause.message}\nBilling: ${pause.actionUrl}`
+                : pause.message;
+        }
+        const serverMessage = error.serverMessage;
+        if (typeof serverMessage === "string" && serverMessage)
+            return serverMessage;
+        return "Remote databases are not available on this company's current billing. Run `hq billing status` to check it.";
     }
     if (status === 403)
         return "You are not a member of this company, or this app belongs to another company.";

package/dist/commands/feedback.d.ts

@@ -91,5 +91,17 @@ export declare function postFeedbackUpdate(opts: {
     publicUrl: string | null;
     slack: string | null;
 }>;
+/** Mirror of hq-pro normalizeAssignee: a prs_ uid as-is, an email lowercased. */
+export declare function normalizeFeedbackAssignee(value: string): string;
+/**
+ * Reassign a ticket. A person's own login may move a ticket that another
+ * person claimed; agent and operator service tokens get 409
+ * TICKET_CLAIMED_BY_HUMAN from the server for those tickets.
+ */
+export declare function assignFeedback(opts: {
+    id: string;
+    token: string;
+    assignee: string;
+}): Promise<void>;
 export declare function registerFeedbackCommand(program: Command): void;
 //# sourceMappingURL=feedback.d.ts.map

package/dist/commands/feedback.js

@@ -285,6 +285,57 @@ export async function postFeedbackUpdate(opts) {
         slack: typeof data.publicUpdateSlack === "string" ? data.publicUpdateSlack : null,
     };
 }
+const ASSIGNEE_RE = /^(?:prs_[A-Za-z0-9]+|[^\s@]+@[^\s@]+\.[^\s@]+)$/;
+/** Mirror of hq-pro normalizeAssignee: a prs_ uid as-is, an email lowercased. */
+export function normalizeFeedbackAssignee(value) {
+    const trimmed = value.trim();
+    if (!ASSIGNEE_RE.test(trimmed)) {
+        throw new Error(`Invalid --to '${value}': expected an email address or a prs_ uid.`);
+    }
+    return trimmed.startsWith("prs_") ? trimmed : trimmed.toLowerCase();
+}
+/**
+ * Reassign a ticket. A person's own login may move a ticket that another
+ * person claimed; agent and operator service tokens get 409
+ * TICKET_CLAIMED_BY_HUMAN from the server for those tickets.
+ */
+export async function assignFeedback(opts) {
+    const res = await vaultApiFetch({
+        token: opts.token,
+        path: `/v1/feedback/${opts.id}`,
+        method: "PATCH",
+        body: { assignee: opts.assignee },
+    });
+    if (res.ok)
+        return;
+    const data = (await res.json().catch(() => ({})));
+    const message = typeof data.error === "string" ? data.error : res.statusText;
+    if (data.code === "TICKET_CLAIMED_BY_HUMAN") {
+        throw new Error(`${message} Run hq feedback assign from your own hq login (hq login), not an agent or operator token.`);
+    }
+    throw new Error(`Failed to assign ${opts.id}: ${message}`);
+}
+function registerAssignSubcommand(feedbackCmd) {
+    feedbackCmd
+        .command("assign")
+        .description("Reassign a ticket to a person, including one another person has claimed")
+        .argument("<id>", "Feedback id (feedback_<uuid>)")
+        .requiredOption("--to <assignee>", "New assignee: an email address or a prs_ uid")
+        .action(async (id, opts) => {
+        try {
+            assertFeedbackId(id);
+            const assignee = normalizeFeedbackAssignee(opts.to);
+            const token = await resolveStaffToken();
+            assertVaultApiRequestSupported({ token, path: `/v1/feedback/${id}` });
+            await assignFeedback({ id, token, assignee });
+            console.log(`Assigned: ${id} -> ${assignee}`);
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+}
 function registerLinkSubcommand(feedbackCmd) {
     feedbackCmd
         .command("link")
@@ -447,5 +498,6 @@ export function registerFeedbackCommand(program) {
     registerLinkSubcommand(feedbackCmd);
     registerUpdateSubcommand(feedbackCmd);
     registerFeedbackShowCommand(feedbackCmd);
+    registerAssignSubcommand(feedbackCmd);
 }
 //# sourceMappingURL=feedback.js.map

package/dist/commands/files-browse.d.ts

@@ -459,6 +459,14 @@ export declare const STORAGE_DOWNLOAD_FAILED_CODE = "FILES_STORAGE_DOWNLOAD_FAIL
  * firewall that does not allow the bucket host, and we say so.
  */
 export declare function presignedDownloadError(key: string, url: string, dl: Response): Promise<Error>;
+/**
+ * Turn a presigned download that never got an HTTP response (connection
+ * refused or reset, DNS failure, timeout, or a TLS failure) into an error that
+ * names the storage host and tells the operator to allow it. Returns
+ * undefined for any other error so the caller rethrows it unchanged. Only the
+ * URL host is used; the signed query string never reaches the message.
+ */
+export declare function presignedDownloadTransportError(key: string, url: string, err: unknown): Error | undefined;
 export declare function createCompanyPresignClient(input: {
     token: string;
     companyUid: string;

package/dist/commands/files-browse.js

@@ -760,6 +760,82 @@ export async function presignedDownloadError(key, url, dl) {
         ...(storageCode ? { storageCode } : {}),
     });
 }
+/** Socket-level error codes that mean the storage host could not be reached. */
+const TRANSPORT_BLOCK_CODES = new Set([
+    "ECONNREFUSED",
+    "ECONNRESET",
+    "ETIMEDOUT",
+    "EHOSTUNREACH",
+    "ENETUNREACH",
+    "EPIPE",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "UND_ERR_CONNECT_TIMEOUT",
+    "UND_ERR_HEADERS_TIMEOUT",
+    "UND_ERR_SOCKET",
+]);
+/** TLS failures, usually a TLS-inspecting proxy whose certificate Node does not trust. */
+const TLS_BLOCK_CODES = new Set([
+    "CERT_HAS_EXPIRED",
+    "DEPTH_ZERO_SELF_SIGNED_CERT",
+    "SELF_SIGNED_CERT_IN_CHAIN",
+    "UNABLE_TO_GET_ISSUER_CERT",
+    "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
+    "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+    "ERR_TLS_CERT_ALTNAME_INVALID",
+    "ERR_SSL_WRONG_VERSION_NUMBER",
+    "EPROTO",
+]);
+function errorChainCode(err) {
+    let cur = err;
+    for (let depth = 0; depth < 5 && cur && typeof cur === "object"; depth++) {
+        const code = cur.code;
+        if (typeof code === "string" && code.length > 0)
+            return code;
+        cur = cur.cause;
+    }
+    return undefined;
+}
+/**
+ * Turn a presigned download that never got an HTTP response (connection
+ * refused or reset, DNS failure, timeout, or a TLS failure) into an error that
+ * names the storage host and tells the operator to allow it. Returns
+ * undefined for any other error so the caller rethrows it unchanged. Only the
+ * URL host is used; the signed query string never reaches the message.
+ */
+export function presignedDownloadTransportError(key, url, err) {
+    const name = err?.name;
+    const timedOut = name === "TimeoutError";
+    const code = timedOut ? "TIMEOUT" : errorChainCode(err);
+    if (!code)
+        return undefined;
+    const tls = TLS_BLOCK_CODES.has(code) || code.startsWith("ERR_TLS_") || code.startsWith("ERR_SSL_");
+    if (!timedOut && !tls && !TRANSPORT_BLOCK_CODES.has(code))
+        return undefined;
+    let host = "the storage host";
+    try {
+        host = new URL(url).host;
+    }
+    catch {
+        // keep the generic label
+    }
+    const what = tls
+        ? `the TLS connection to ${host} failed (${code}). A proxy that inspects HTTPS traffic is the usual cause`
+        : timedOut
+            ? `the connection to ${host} timed out. A firewall or egress rule that drops traffic is the usual cause`
+            : `the connection to ${host} failed (${code}). A firewall, proxy or egress rule on this network is the usual cause`;
+    const message = `Failed to download '${key}': ${what}. Your file access was granted; the ` +
+        `network blocked the storage host. Ask your network operator to allow ` +
+        `outbound HTTPS (TCP 443) to ${host} (HQ vault files are served from ` +
+        `*.s3.us-east-1.amazonaws.com), then retry.`;
+    return Object.assign(new Error(message, { cause: err }), {
+        code: STORAGE_DOWNLOAD_FAILED_CODE,
+        key,
+        blockedHost: host,
+        transportCode: code,
+        fromStorage: false,
+    });
+}
 export function createCompanyPresignClient(input) {
     const { token, companyUid, companySlug, baseUrl } = input;
     const denied = (message, key, extra) => Object.assign(new Error(message), {
@@ -829,7 +905,13 @@ export function createCompanyPresignClient(input) {
             }
             throw new Error(message);
         }
-        const dl = await fetch(first.url, { signal: AbortSignal.timeout(120_000) });
+        let dl;
+        try {
+            dl = await fetch(first.url, { signal: AbortSignal.timeout(120_000) });
+        }
+        catch (err) {
+            throw presignedDownloadTransportError(key, first.url, err) ?? err;
+        }
         if (!dl.ok) {
             throw await presignedDownloadError(key, first.url, dl);
         }

package/dist/commands/files.js

@@ -1,4 +1,5 @@
 import chalk from "chalk";
+import { aclLockedBy, describeAclLock } from "./acl-lock.js";
 import open from "open";
 import * as readline from "node:readline";
 import { resolveVaultCredential } from "../utils/resolve-vault-credential.js";
@@ -489,17 +490,21 @@ export function registerFilesCommand(program) {
                 throw new Error('Invalid ACL tree response');
             }
             const row = tree.directRow;
+            // The most-specific row has no grants, so broader grants do not apply.
+            const lockedBy = aclLockedBy(tree);
             if (opts.json) {
-                console.log(JSON.stringify({ ...tree, schemaVersion: 1, companyUid, exists: row !== null }, null, 2));
+                console.log(JSON.stringify({ ...tree, schemaVersion: 1, companyUid, exists: row !== null, lockedBy }, null, 2));
                 return;
             }
             // No own row AND nothing inherited or granted below — preserve the
             // original "no ACL record" exit path.
-            if (!row && tree.inherited.length === 0 && tree.children.length === 0) {
+            if (!row && !lockedBy && tree.inherited.length === 0 && tree.children.length === 0) {
                 console.error(chalk.red(`No ACL record exists for '${canonicalPrefix}'`));
                 process.exit(1);
             }
-            const aclStatus = row?.open ? "open" : "restricted";
+            const aclStatus = lockedBy
+                ? lockedBy.readUnknown ? "locked unless open" : "locked"
+                : row?.open ? "open" : "restricted";
             console.log(chalk.green(`ACL for ${displayAclPattern(tree.prefix)} (${aclStatus})`));
             if (isPrivateFolderPattern(tree.prefix)) {
                 console.log(chalk.gray(privateFolderExplanation(tree.prefix)));
@@ -507,9 +512,12 @@ export function registerFilesCommand(program) {
             if (row) {
                 console.log(`Creator: ${row.creatorUid}`);
             }
-            else {
+            else if (!lockedBy) {
                 console.log(chalk.gray("No direct ACL row — access flows from the inherited/descendant grants below."));
             }
+            if (lockedBy) {
+                console.log(chalk.yellow(describeAclLock(lockedBy, displayAclPattern(lockedBy.path))));
+            }
             if (tree.effectivePermission) {
                 console.log(`Your effective permission: ${tree.effectivePermission}`);
             }
@@ -560,9 +568,9 @@ export function registerFilesCommand(program) {
             const directEntries = tree.direct;
             if (directEntries.length === 0) {
                 if (row?.open) {
-                    console.log(chalk.gray("Open ACL — all active members have read access."));
+                    console.log(chalk.gray("No grants on this row (open: broader grants still apply). All active members have at least read access."));
                 }
-                else if (row) {
+                else if (row && !lockedBy) {
                     console.log(chalk.gray("No explicit grants on this prefix — only creator has access."));
                 }
             }
@@ -571,7 +579,11 @@ export function registerFilesCommand(program) {
                 printEntryTable(directEntries, false);
             }
             if (tree.inherited.length > 0) {
-                console.log("\nInherited (granted on an ancestor prefix):");
+                console.log(lockedBy
+                    ? lockedBy.readUnknown
+                        ? `\nGranted on ancestor prefixes (apply only if ${displayAclPattern(lockedBy.path)} is open):`
+                        : `\nGranted on ancestor prefixes (do not apply: locked by ${displayAclPattern(lockedBy.path)}):`
+                    : "\nInherited (granted on an ancestor prefix):");
                 printEntryTable(tree.inherited, true);
             }
             if (tree.children.length > 0) {

package/dist/commands/install-global.d.ts

@@ -83,6 +83,8 @@ export interface GlobalCommandOpts {
     trustCodexHooks?: (cwd: string, keys: readonly string[]) => Promise<RuntimeHookTrustResult>;
     /** Test seam: is the npm hq.cmd folder on the Windows PATH? Null off Windows. */
     shimPathCheck?: () => ShimPathCheck | null;
+    /** Test seam: the Windows npm prefix holding hq.cmd. Null off Windows. */
+    ps1ShimDir?: () => string | null;
 }
 export declare function resolveInstallRoot(explicit: string | undefined, options?: {
     env?: NodeJS.ProcessEnv;

package/dist/commands/install-global.js

@@ -27,7 +27,8 @@ import { readCompaniesManifestMap } from '../lib/work-context/repo-remote.js';
 import { resolveDefaultHqRoot } from '../utils/hq-root-resolver.js';
 import { trustCodexUserHooks } from '../utils/hook-trust.js';
 import { assertProviderWrappersInstallable, installProviderWrappers, providerWrapperInstallPaths, removeProviderWrappers } from '../lib/install/provider-wrappers.js';
-import { checkShimOnPath, ensureShimOnUserPath, shimPathWarning } from '../lib/windows/user-path.js';
+import { checkShimOnPath, ensureShimOnUserPath, npmShimDir, shimPathWarning } from '../lib/windows/user-path.js';
+import { removeHqCliPs1Shims } from '../lib/windows/ps1-shims.js';
 import { addAgentsMdBlock, addCodexHooks, classifyLegacySkills, codexAdapterPath, codexCharterSource, codexHookTrustKeys, codexTargets, hasAllCodexHooks, HQ_OWNED_MARKER, LEGACY_BACKUP_NAME, LEGACY_SKILLS_NAME, removeAgentsMdBlock, removeCodexHooks, } from '../lib/install/codex-targets.js';
 import { addClaudeMdBlock, addHqHooks, charterPath, claudeTargets, hasAllHqHooks, HQ_ANYWHERE_PACK, HQ_MCP_SERVER_NAME, hqSkillsSource, lineDiff, masterHookPath, shimPath, MCP_SUBPROCESS_PATH, removeClaudeMdBlock, removeHqHooks, SKILL_LINK_PREFIX, } from '../lib/install/claude-targets.js';
 export { hookTargetFor, isDaemonInstalled } from '../lib/install/hook-target.js';
@@ -1156,6 +1157,24 @@ export function resolveInstallRoot(explicit, options = {}) {
         throw Object.assign(new Error('Run from inside your HQ checkout, or pass --hq-root <dir>.'), { expected: true });
     }
 }
+function defaultPs1ShimDir() {
+    return process.platform === 'win32' ? npmShimDir(process.argv[1], fs.existsSync) : null;
+}
+/**
+ * PowerShell picks npm's hq.ps1 over hq.cmd, and a Restricted execution policy
+ * blocks it. Remove only npm's own hq-cli launchers; never change the policy.
+ */
+function removePs1ShimsReport(dir) {
+    const result = removeHqCliPs1Shims(dir);
+    const lines = [];
+    if (result.removed.length > 0) {
+        lines.push(`  windows: removed ${result.removed.map((f) => path.win32.basename(f)).join(', ')} so PowerShell now runs hq.cmd.`);
+    }
+    for (const failure of result.failed) {
+        lines.push(`  windows: could not remove ${failure.file} (${failure.reason}). Run hq.cmd instead of hq in PowerShell.`);
+    }
+    return lines;
+}
 /** Entry used by `hq install --global` (wired from pkg-install.ts). */
 export async function runInstallGlobal(opts) {
     const runtime = assertRuntime(opts.runtime);
@@ -1201,6 +1220,10 @@ export async function runInstallGlobal(opts) {
         if (shimPath)
             for (const line of shimPathWarning(shimPath))
                 (opts.log ?? console.log)(line);
+        const ps1Dir = (opts.ps1ShimDir ?? defaultPs1ShimDir)();
+        if (ps1Dir)
+            for (const line of removePs1ShimsReport(ps1Dir))
+                (opts.log ?? console.log)(line);
     }
 }
 /**

package/dist/commands/integrations-connect.js

@@ -1449,6 +1449,7 @@ export function registerConnectCommands(integrations) {
         .option("--auth <mode>", "Force the auth mode: none, key, or oauth (default: detect)")
         .option("--client-id <id>", "Client id of an OAuth app you registered with the provider yourself")
         .option("--client-secret-stdin", "Read that app's client secret from stdin")
+        .option("--scopes <list>", "Permissions to request, space- or comma-separated (default: the permissions the app was approved for last time)")
         .option("--no-browser", "Print the sign-in URL instead of opening a browser")
         .option("--timeout <seconds>", "How long to wait for a browser sign-in (default 300)")
         .option("--connect", "For a revoked row, run `connect <domain>` to re-add and revive it")

package/dist/commands/integrations-manage.d.ts

@@ -26,6 +26,8 @@ interface Principal {
  * guessing — a misparsed principal silently grants access to the wrong party.
  */
 export declare function parsePrincipal(raw: string): Principal;
+/** `--with` / `--to` / `--from` help. Groups resolve membership at call time. */
+export declare const PRINCIPAL_HELP = "Email, uid, vault group (grp_\u2026), or `everyone`";
 export declare function registerManageCommands(integrations: Command): void;
 /** Order-insensitive identity of an allowlist, for change detection. */
 export declare function allowlistFingerprint(grants: WriteAllowlistGrant[]): string;