@indigoai-us/hq-cli 5.326.0 → 5.327.0

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## [Unreleased]
 
+## [5.327.0] — 2026-10-02
+- Reduce hook-time startup imports for repo-run-registry and isolate hook-helper handlers from sibling modules.
+- Keep package-root Sentry diagnostics off the fast-route import path unless root diagnostics are needed.
+- `hq mcp login` adds browser-based OAuth sign-in for hosted MCP.
+
 ## [5.326.0] — 2026-10-02
 - Company-scoped daemon tools now reject an explicit company that conflicts with the active session or repository binding.
 - Added a flag-gated `hq mcp serve` command and global install hook for the Anywhere runtime.

package/dist/command-catalog.generated.d.ts

@@ -3728,6 +3728,15 @@ export declare const COMMAND_CATALOG: readonly [{
         readonly arguments: readonly [];
         readonly options: readonly [];
         readonly subcommands: readonly [];
+    }, {
+        readonly name: "login";
+        readonly description: "Sign in to the hosted HQ MCP connector with browser OAuth";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly usage: "[options]";
+        readonly arguments: readonly [];
+        readonly options: readonly [];
+        readonly subcommands: readonly [];
     }, {
         readonly name: "status";
         readonly description: "Show installed MCP packs/servers and their health in BOTH Claude and Codex (PARTIAL/DRIFT flagged; secrets redacted)";

package/dist/command-catalog.generated.js

@@ -4811,6 +4811,16 @@ export const COMMAND_CATALOG = [
                 "options": [],
                 "subcommands": []
             },
+            {
+                "name": "login",
+                "description": "Sign in to the hosted HQ MCP connector with browser OAuth",
+                "aliases": [],
+                "hidden": false,
+                "usage": "[options]",
+                "arguments": [],
+                "options": [],
+                "subcommands": []
+            },
             {
                 "name": "status",
                 "description": "Show installed MCP packs/servers and their health in BOTH Claude and Codex (PARTIAL/DRIFT flagged; secrets redacted)",

package/dist/commands/auth.js

@@ -264,7 +264,9 @@ export function registerAuthCommands(program) {
     authCmd
         .command("logout")
         .description("Clear the cached HQ Cognito session")
-        .action(() => {
+        .action(async () => {
+        const { clearMcpOAuthCaches } = await import("../lib/daemon/mcp-oauth.js");
+        clearMcpOAuthCaches();
         const existing = loadCachedTokens();
         if (!existing) {
             console.log(chalk.yellow("No cached HQ session"));

package/dist/commands/core-detect-stale-review-base-fast.d.ts

@@ -0,0 +1,2 @@
+export declare function runDetectStaleReviewBaseFast(args: readonly string[], _stdin: string, _cwd: string, hqRoot: string | undefined): Promise<number>;
+//# sourceMappingURL=core-detect-stale-review-base-fast.d.ts.map

package/dist/commands/core-detect-stale-review-base-fast.js

@@ -0,0 +1,23 @@
+/** Fast-route adapter isolated from the other hook-helper command modules. */
+import { resolveBundledAsset } from "../utils/hq-roots-core.js";
+import { runDetectStaleReviewBase, DETECT_STALE_REVIEW_BASE_ASSET } from "./core-detect-stale-review-base-native.js";
+function writeResult(result) {
+    if (result.stdout)
+        process.stdout.write(result.stdout);
+    if (result.stderr)
+        process.stderr.write(result.stderr);
+    return result.code;
+}
+export async function runDetectStaleReviewBaseFast(args, _stdin, _cwd, hqRoot) {
+    let root = hqRoot;
+    if (!root) {
+        const { resolveLiveRoot } = await import("../utils/hq-roots-core.js");
+        root = resolveLiveRoot();
+    }
+    return writeResult(runDetectStaleReviewBase(args, {
+        cwd: root,
+        env: { ...process.env, HQ_ROOT: root },
+        scriptPath: resolveBundledAsset(DETECT_STALE_REVIEW_BASE_ASSET),
+    }));
+}
+//# sourceMappingURL=core-detect-stale-review-base-fast.js.map

package/dist/commands/core-register-project-native.js

@@ -4,7 +4,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { spawnSync } from "node:child_process";
 import { serializeJqJson } from "../lib/core-utils/jq-json-serializer.js";
-import { resolveBundledAsset } from "../utils/hq-roots.js";
+import { resolveBundledAsset } from "../utils/hq-roots-core.js";
 export const REGISTER_PROJECT_ASSET = "core/scripts/register-project.sh";
 const USAGE = "usage: register-project.sh <company> <project> | --audit <company> | --backfill <company> --only-active [--yes] | --retry-pending <company>";
 const MIN_HQ_CLI = "5.139.0";

package/dist/commands/core-repo-run-registry-fast.d.ts

@@ -0,0 +1,2 @@
+export declare function runRepoRunRegistryFast(args: readonly string[], _stdin: string, _cwd: string, hqRoot: string | undefined, _commandName: string, _hqRootArg?: string, worktreeScopeFixEnabled?: boolean): Promise<number>;
+//# sourceMappingURL=core-repo-run-registry-fast.d.ts.map

package/dist/commands/core-repo-run-registry-fast.js

@@ -0,0 +1,35 @@
+/** Fast-route adapter isolated from the other hook-helper command modules. */
+import { runBundledScript } from "../utils/run-bundled-script.js";
+import { runRepoRunRegistry, REPO_RUN_REGISTRY_ASSET } from "./core-repo-run-registry-native.js";
+function writeResult(result) {
+    if (result.stdout)
+        process.stdout.write(result.stdout);
+    if (result.stderr)
+        process.stderr.write(result.stderr);
+    return result.code;
+}
+async function liveRoot(hqRoot) {
+    if (hqRoot)
+        return hqRoot;
+    const { resolveLiveRoot } = await import("../utils/hq-roots-core.js");
+    return resolveLiveRoot();
+}
+export async function runRepoRunRegistryFast(args, _stdin, _cwd, hqRoot, _commandName, _hqRootArg, worktreeScopeFixEnabled = false) {
+    const root = await liveRoot(hqRoot);
+    return writeResult(runRepoRunRegistry(args, {
+        root,
+        cwd: root,
+        env: process.env,
+        worktreeScopeFixEnabled,
+        runShellFallback: (fallbackArgs) => {
+            const { code } = runBundledScript({
+                asset: REPO_RUN_REGISTRY_ASSET,
+                args: [...fallbackArgs],
+                cwd: root,
+                hqRoot: root,
+            });
+            return { code, stdout: "", stderr: "" };
+        },
+    }));
+}
+//# sourceMappingURL=core-repo-run-registry-fast.js.map

package/dist/commands/core-rrr-worktree-scope-fix-fast-flag.d.ts

@@ -0,0 +1,7 @@
+/** Light company-scoped reader for the repo-run-registry worktree-scope flag. */
+/**
+ * Resolve the same default-off, company-scoped flag without loading the full
+ * flag registry and work-context graph on the ordinary UID-scoped path.
+ */
+export declare function coreRrrWorktreeScopeFixFastFlagEnabled(env?: NodeJS.ProcessEnv): Promise<boolean>;
+//# sourceMappingURL=core-rrr-worktree-scope-fix-fast-flag.d.ts.map

package/dist/commands/core-rrr-worktree-scope-fix-fast-flag.js

@@ -0,0 +1,25 @@
+/** Light company-scoped reader for the repo-run-registry worktree-scope flag. */
+import { readLocalOverride } from "@indigoai-us/hq-flags-client";
+import { readFlagSnapshotFile } from "../lib/flag-snapshot-file.js";
+import { resolveFastProcessFlagCompanyContext } from "../lib/process-flag-company-context-fast.js";
+/**
+ * Resolve the same default-off, company-scoped flag without loading the full
+ * flag registry and work-context graph on the ordinary UID-scoped path.
+ */
+export async function coreRrrWorktreeScopeFixFastFlagEnabled(env = process.env) {
+    const flagKey = "core-rrr-worktree-scope-fix";
+    const override = readLocalOverride(flagKey, env);
+    if (override !== null)
+        return override;
+    try {
+        const context = await resolveFastProcessFlagCompanyContext(env);
+        if (!context.companyUid)
+            return false;
+        return readFlagSnapshotFile(context.companyUid, { env })?.flags[flagKey] === true;
+    }
+    catch {
+        // Keep the fast gate's established fail-closed default for unavailable scope or cache data.
+        return false;
+    }
+}
+//# sourceMappingURL=core-rrr-worktree-scope-fix-fast-flag.js.map

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

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { resolveSessionHelperRuntime } from "./core-session-helper-runtime.js";
-import { resolveBundledAsset } from "../utils/hq-roots.js";
+import { resolveBundledAsset } from "../utils/hq-roots-core.js";
 const USAGE = `session-journal.sh: usage:
   session-journal.sh write "<title>" [--files f1,f2,...] [--body-file PATH] [--session KEY]
   session-journal.sh list [--date YYYY-MM-DD]

package/dist/commands/core-share-suggestion-state-fast.d.ts

@@ -0,0 +1,2 @@
+export declare function runShareSuggestionStateFast(args: readonly string[], stdin: string, _cwd: string, hqRoot: string | undefined): Promise<number>;
+//# sourceMappingURL=core-share-suggestion-state-fast.d.ts.map

package/dist/commands/core-share-suggestion-state-fast.js

@@ -0,0 +1,25 @@
+/** Fast-route adapter isolated from the other hook-helper command modules. */
+import { runShareSuggestionState } from "./core-share-suggestion-state-native.js";
+function writeResult(result) {
+    if (result.stdout)
+        process.stdout.write(result.stdout);
+    if (result.stderr)
+        process.stderr.write(result.stderr);
+    return result.code;
+}
+async function liveRoot(hqRoot) {
+    if (hqRoot)
+        return hqRoot;
+    const { resolveLiveRoot } = await import("../utils/hq-roots-core.js");
+    return resolveLiveRoot();
+}
+export async function runShareSuggestionStateFast(args, stdin, _cwd, hqRoot) {
+    const root = await liveRoot(hqRoot);
+    return writeResult(runShareSuggestionState(args, stdin, {
+        root,
+        cwd: root,
+        env: process.env,
+        stdinIsTty: process.stdin.isTTY,
+    }));
+}
+//# sourceMappingURL=core-share-suggestion-state-fast.js.map

package/dist/commands/logout.js

@@ -9,6 +9,8 @@ export function registerLogoutCommand(program) {
         .description('Log out and clear cached credentials')
         .action(async () => {
         try {
+            const { clearMcpOAuthCaches } = await import('../lib/daemon/mcp-oauth.js');
+            clearMcpOAuthCaches();
             const existing = loadCachedTokens();
             if (!existing) {
                 console.log(chalk.yellow('No cached HQ session'));

package/dist/commands/mcp-status.js

@@ -396,6 +396,13 @@ export function registerMcpCommand(program) {
         const { runMcpServe } = await import('./mcp-serve.js');
         await runMcpServe();
     });
+    mcp
+        .command('login')
+        .description('Sign in to the hosted HQ MCP connector with browser OAuth')
+        .action(async () => {
+        const { loginHostedMcp } = await import('../lib/daemon/mcp-oauth.js');
+        await loginHostedMcp();
+    });
     mcp
         .command('status')
         .alias('list')

package/dist/fast-core.js

@@ -39,11 +39,8 @@ export async function runFastCore(argv, parsed = parseFastCore(argv)) {
     const useShell = entry.kind === "native" && Boolean(entry.familyFlagKey) && !familyEnabled;
     let worktreeScopeFixEnabled;
     if (entry.name === "repo-run-registry") {
-        const [{ CORE_RRR_WORKTREE_SCOPE_FIX_FLAG }, { fastFlagEnabled }] = await Promise.all([
-            import("./commands/core-rrr-worktree-scope-fix-flag.js"),
-            import("./native-fast-route.js"),
-        ]);
-        worktreeScopeFixEnabled = await fastFlagEnabled(CORE_RRR_WORKTREE_SCOPE_FIX_FLAG, process.env, { numericEnvironmentOverride: false });
+        const { coreRrrWorktreeScopeFixFastFlagEnabled } = await import("./commands/core-rrr-worktree-scope-fix-fast-flag.js");
+        worktreeScopeFixEnabled = await coreRrrWorktreeScopeFixFastFlagEnabled(process.env);
     }
     const shouldInjectRoot = useShell
         ? entry.shellHqRoot === "live" || (entry.shellHqRoot === "reconcile-default" &&
@@ -57,7 +54,7 @@ export async function runFastCore(argv, parsed = parseFastCore(argv)) {
     // its expected-user-error formatting remains authoritative.
     let hqRoot;
     if (shouldInjectRoot) {
-        const { resolveLiveRoot } = await import("./utils/hq-roots.js");
+        const { resolveLiveRoot } = await import("./utils/hq-roots-core.js");
         try {
             hqRoot = resolveLiveRoot(parsed.hqRootArg ? { hqRoot: parsed.hqRootArg } : {});
         }

package/dist/fast-scaffold.js

@@ -175,7 +175,11 @@ export const FAST_SCAFFOLD_SCRIPTS = [
     ...["share-suggestion-state", "repo-run-registry", "detect-stale-review-base"].map((name) => ({
         name,
         kind: "native",
-        modulePath: "./commands/core-hook-state-helpers-native.js",
+        modulePath: name === "share-suggestion-state"
+            ? "./commands/core-share-suggestion-state-fast.js"
+            : name === "repo-run-registry"
+                ? "./commands/core-repo-run-registry-fast.js"
+                : "./commands/core-detect-stale-review-base-fast.js",
         exportName: name === "share-suggestion-state"
             ? "runShareSuggestionStateFast"
             : name === "repo-run-registry"

package/dist/lib/daemon/mcp-endpoint.d.ts

@@ -0,0 +1,8 @@
+export declare class McpEndpointError extends Error {
+    readonly code = "hq_mcp_config_error";
+}
+/** Derive the hosted MCP sibling from the same hq-pro URL used by hq-cli. */
+export declare function resolveHqMcpEndpoint(env?: NodeJS.ProcessEnv): URL;
+/** OAuth endpoints share the origin with the Streamable HTTP MCP endpoint. */
+export declare function resolveHqMcpOAuthOrigin(env?: NodeJS.ProcessEnv): URL;
+//# sourceMappingURL=mcp-endpoint.d.ts.map

package/dist/lib/daemon/mcp-endpoint.js

@@ -0,0 +1,30 @@
+import { DEFAULT_VAULT_API_URL } from "../../utils/cognito-session.js";
+export class McpEndpointError extends Error {
+    code = "hq_mcp_config_error";
+}
+/** Derive the hosted MCP sibling from the same hq-pro URL used by hq-cli. */
+export function resolveHqMcpEndpoint(env = process.env) {
+    const apiUrl = env.HQ_VAULT_API_URL?.trim() || DEFAULT_VAULT_API_URL;
+    let api;
+    try {
+        api = new URL(apiUrl);
+    }
+    catch {
+        throw new McpEndpointError("HQ's configured API URL is invalid; check HQ_VAULT_API_URL.");
+    }
+    if (api.protocol !== "https:" || !api.hostname.startsWith("hqapi.")) {
+        throw new McpEndpointError("Hosted hq-mcp requires an HTTPS hqapi host in HQ_VAULT_API_URL.");
+    }
+    api.hostname = `hq-mcp.${api.hostname.slice("hqapi.".length)}`;
+    api.pathname = "/mcp";
+    api.search = "";
+    api.hash = "";
+    return api;
+}
+/** OAuth endpoints share the origin with the Streamable HTTP MCP endpoint. */
+export function resolveHqMcpOAuthOrigin(env = process.env) {
+    const endpoint = resolveHqMcpEndpoint(env);
+    endpoint.pathname = "/";
+    return endpoint;
+}
+//# sourceMappingURL=mcp-endpoint.js.map

package/dist/lib/daemon/mcp-oauth.d.ts

@@ -0,0 +1,24 @@
+export declare class McpOAuthError extends Error {
+    readonly code = "hq_mcp_auth_required";
+    constructor(message: string);
+}
+export interface McpOAuthOptions {
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+    oauthOrigin?: URL;
+    fetchImpl?: typeof fetch;
+    openBrowser?: (url: string) => Promise<unknown>;
+    writeOutput?: (message: string) => void;
+    isEnabled?: () => boolean;
+    isMachine?: () => boolean;
+    now?: () => number;
+    callbackTimeoutMs?: number;
+}
+export declare function mcpOAuthCacheFile(options?: McpOAuthOptions): string;
+/** Perform hosted DCR + PKCE login and cache only the hq-mcp audience tokens. */
+export declare function loginHostedMcp(options?: McpOAuthOptions): Promise<void>;
+/** Load or refresh a person's hosted MCP token without printing token material. */
+export declare function getMcpAudienceToken(options?: McpOAuthOptions): Promise<string>;
+/** Remove all per-origin hosted MCP OAuth caches during either HQ logout flow. */
+export declare function clearMcpOAuthCaches(options?: Pick<McpOAuthOptions, "env" | "home">): void;
+//# sourceMappingURL=mcp-oauth.d.ts.map

package/dist/lib/daemon/mcp-oauth.js

@@ -0,0 +1,298 @@
+import { createHash, randomBytes } from "node:crypto";
+import * as fs from "node:fs";
+import * as http from "node:http";
+import * as os from "node:os";
+import * as path from "node:path";
+import open from "open";
+import { resolveCognitoTokenSource } from "../../utils/cognito-session.js";
+import { anywhereRuntimeEnabled } from "../../commands/anywhere-runtime-flag.js";
+import { resolveHqMcpOAuthOrigin } from "./mcp-endpoint.js";
+const MCP_SCOPE = "openid email profile hq-mcp/use";
+const EXPIRY_SKEW_MS = 60_000;
+const DEFAULT_CALLBACK_TIMEOUT_MS = 5 * 60_000;
+const MAX_RESPONSE_BYTES = 64 * 1024;
+export class McpOAuthError extends Error {
+    code = "hq_mcp_auth_required";
+    constructor(message) {
+        super(message);
+        this.name = "McpOAuthError";
+    }
+}
+function cacheFile(env, home, origin) {
+    const stateDir = env.HQ_STATE_DIR?.trim() || path.join(home, ".hq");
+    const originHash = createHash("sha256").update(origin.origin).digest("hex").slice(0, 16);
+    return path.join(path.resolve(stateDir), `mcp-oauth-tokens-${originHash}.json`);
+}
+function readCache(file) {
+    try {
+        const value = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (!value || typeof value !== "object")
+            return undefined;
+        const cache = value;
+        if (cache.version !== 1 || typeof cache.origin !== "string" || !cache.origin ||
+            typeof cache.clientId !== "string" || !cache.clientId ||
+            typeof cache.accessToken !== "string" || !cache.accessToken ||
+            typeof cache.refreshToken !== "string" || !cache.refreshToken ||
+            typeof cache.expiresAt !== "number" || !Number.isFinite(cache.expiresAt))
+            return undefined;
+        return cache;
+    }
+    catch (error) {
+        if (error.code === "ENOENT" || error instanceof SyntaxError)
+            return undefined;
+        throw new McpOAuthError("The hosted MCP token cache could not be read. Check its permissions or run `hq mcp login` again.");
+    }
+}
+function writeCache(file, cache) {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const temporary = `${file}.tmp-${process.pid}-${randomBytes(6).toString("hex")}`;
+    const fd = fs.openSync(temporary, "wx", 0o600);
+    try {
+        fs.writeFileSync(fd, JSON.stringify(cache));
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    try {
+        fs.renameSync(temporary, file);
+        fs.chmodSync(file, 0o600);
+    }
+    catch (error) {
+        try {
+            fs.unlinkSync(temporary);
+        }
+        catch { /* retain the original write error */ }
+        throw error;
+    }
+}
+function asObject(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+async function postForm(url, form, fetchImpl) {
+    let response;
+    try {
+        response = await fetchImpl(url, {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded" },
+            body: form.toString(),
+            signal: AbortSignal.timeout(30_000),
+        });
+    }
+    catch {
+        throw new McpOAuthError("Hosted MCP sign-in could not reach the OAuth service. Retry `hq mcp login`.");
+    }
+    if (!response.ok) {
+        throw new McpOAuthError("Hosted MCP OAuth request failed (HTTP " + response.status + "). Retry `hq mcp login`.");
+    }
+    let data;
+    try {
+        const raw = await response.text();
+        if (raw.length > MAX_RESPONSE_BYTES)
+            throw new Error("response too large");
+        data = JSON.parse(raw);
+    }
+    catch {
+        throw new McpOAuthError("Hosted MCP OAuth returned an invalid response. Retry `hq mcp login`.");
+    }
+    const result = asObject(data);
+    if (!result)
+        throw new McpOAuthError("Hosted MCP OAuth returned an invalid response. Retry `hq mcp login`.");
+    return result;
+}
+function validTokens(data, now, previous) {
+    if (typeof data.access_token !== "string" || !data.access_token ||
+        typeof data.expires_in !== "number" || !Number.isFinite(data.expires_in) || data.expires_in <= 0)
+        throw new McpOAuthError("Hosted MCP OAuth did not return a usable access token.");
+    const refreshToken = typeof data.refresh_token === "string" && data.refresh_token
+        ? data.refresh_token
+        : previous?.refreshToken;
+    if (!refreshToken)
+        throw new McpOAuthError("Hosted MCP OAuth did not return a refresh token. Run `hq mcp login` again.");
+    return {
+        version: 1,
+        origin: previous?.origin ?? "",
+        clientId: previous?.clientId ?? "",
+        accessToken: data.access_token,
+        refreshToken,
+        expiresAt: now + data.expires_in * 1000,
+    };
+}
+function oauthUrl(origin, endpoint) {
+    return new URL(endpoint, origin);
+}
+function newPkce() {
+    const verifier = randomBytes(32).toString("base64url");
+    return { verifier, challenge: createHash("sha256").update(verifier).digest("base64url") };
+}
+async function runLogin(options) {
+    const env = options.env ?? process.env;
+    if (!(options.isEnabled ?? (() => anywhereRuntimeEnabled(env)))()) {
+        throw new McpOAuthError("HQ Anywhere is not enabled. Enable the hq-anywhere-runtime flag to use `hq mcp login`.");
+    }
+    if ((options.isMachine ?? (() => resolveCognitoTokenSource(env) === "machine"))()) {
+        throw new McpOAuthError("`hq mcp login` is for person accounts; this box uses machine credentials.");
+    }
+    const origin = options.oauthOrigin ?? resolveHqMcpOAuthOrigin(env);
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const output = options.writeOutput ?? ((message) => process.stdout.write(`${message}\n`));
+    const pkce = newPkce();
+    const state = randomBytes(24).toString("base64url");
+    let authorizationCode;
+    let callbackError;
+    let resolveCallback;
+    const callback = new Promise((resolve) => { resolveCallback = resolve; });
+    const server = http.createServer((request, response) => {
+        const url = new URL(request.url ?? "/", "http://127.0.0.1");
+        if (request.method !== "GET" || url.pathname !== "/oauth/callback") {
+            response.writeHead(404).end("Not found");
+            return;
+        }
+        if (url.searchParams.get("state") !== state) {
+            callbackError = new Error("state");
+        }
+        else if (url.searchParams.has("error")) {
+            callbackError = new Error("authorization");
+        }
+        else {
+            authorizationCode = url.searchParams.get("code") ?? undefined;
+            if (!authorizationCode)
+                callbackError = new Error("code");
+        }
+        response.writeHead(callbackError ? 400 : 200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" });
+        response.end(callbackError ? "Sign-in failed. Return to the HQ CLI." : "Sign-in complete. Return to the HQ CLI.");
+        resolveCallback();
+    });
+    let timeout;
+    try {
+        await new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(0, "127.0.0.1", resolve);
+        });
+        const address = server.address();
+        if (!address || typeof address === "string")
+            throw new McpOAuthError("Could not start the local OAuth callback listener.");
+        const redirectUri = `http://127.0.0.1:${address.port}/oauth/callback`;
+        let registrationResponse;
+        try {
+            registrationResponse = await fetchImpl(oauthUrl(origin, "/oauth/register"), {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({
+                    redirect_uris: [redirectUri], token_endpoint_auth_method: "none",
+                    grant_types: ["authorization_code", "refresh_token"], response_types: ["code"],
+                    client_name: "HQ CLI",
+                }),
+                signal: AbortSignal.timeout(30_000),
+            });
+        }
+        catch {
+            throw new McpOAuthError("Hosted MCP client registration failed. Retry `hq mcp login`.");
+        }
+        if (!registrationResponse.ok)
+            throw new McpOAuthError(`Hosted MCP client registration failed (HTTP ${registrationResponse.status}).`);
+        let registration;
+        try {
+            registration = asObject(await registrationResponse.json());
+        }
+        catch { /* handled below */ }
+        if (!registration || typeof registration.client_id !== "string" || !registration.client_id.startsWith("dcr_")) {
+            throw new McpOAuthError("Hosted MCP returned an invalid client registration.");
+        }
+        const clientId = registration.client_id;
+        const authorize = oauthUrl(origin, "/oauth/authorize");
+        authorize.search = new URLSearchParams({
+            response_type: "code", client_id: clientId, redirect_uri: redirectUri,
+            code_challenge: pkce.challenge, code_challenge_method: "S256", state, scope: MCP_SCOPE,
+        }).toString();
+        const remoteShell = Boolean(env.SSH_CONNECTION || env.SSH_CLIENT || env.SSH_TTY);
+        if (remoteShell) {
+            output(`Open this URL on your workstation to sign in to hosted hq-mcp:\n${authorize.toString()}\nForward the callback port first with: ssh -L ${address.port}:127.0.0.1:${address.port} <this-host>`);
+            if (options.openBrowser)
+                await options.openBrowser(authorize.toString());
+        }
+        else
+            try {
+                await (options.openBrowser ?? ((url) => open(url)))(authorize.toString());
+            }
+            catch {
+                output(`Open this URL to sign in to hosted hq-mcp:\n${authorize.toString()}`);
+            }
+        timeout = setTimeout(() => {
+            callbackError = new Error("timeout");
+            resolveCallback();
+        }, options.callbackTimeoutMs ?? DEFAULT_CALLBACK_TIMEOUT_MS);
+        await callback;
+        if (callbackError || !authorizationCode)
+            throw new McpOAuthError("Hosted MCP sign-in did not complete. Retry `hq mcp login`.");
+        const tokens = await postForm(oauthUrl(origin, "/oauth/token"), new URLSearchParams({
+            grant_type: "authorization_code", client_id: clientId, code: authorizationCode,
+            redirect_uri: redirectUri, code_verifier: pkce.verifier,
+        }), fetchImpl);
+        const now = (options.now ?? Date.now)();
+        const cache = validTokens(tokens, now);
+        cache.origin = origin.origin;
+        cache.clientId = clientId;
+        return cache;
+    }
+    finally {
+        if (timeout)
+            clearTimeout(timeout);
+        await new Promise((resolve) => server.close(() => resolve()));
+    }
+}
+export function mcpOAuthCacheFile(options = {}) {
+    const env = options.env ?? process.env;
+    return cacheFile(env, options.home ?? os.homedir(), options.oauthOrigin ?? resolveHqMcpOAuthOrigin(env));
+}
+/** Perform hosted DCR + PKCE login and cache only the hq-mcp audience tokens. */
+export async function loginHostedMcp(options = {}) {
+    const cache = await runLogin(options);
+    writeCache(mcpOAuthCacheFile(options), cache);
+    const writeOutput = options.writeOutput ?? ((message) => process.stdout.write(`${message}\n`));
+    writeOutput("Signed in to hosted hq-mcp. The MCP audience token is stored in the private HQ token cache.");
+}
+/** Load or refresh a person's hosted MCP token without printing token material. */
+export async function getMcpAudienceToken(options = {}) {
+    const file = mcpOAuthCacheFile(options);
+    const cache = readCache(file);
+    const now = (options.now ?? Date.now)();
+    if (!cache || cache.origin !== (options.oauthOrigin ?? resolveHqMcpOAuthOrigin(options.env ?? process.env)).origin)
+        throw new McpOAuthError("Sign in to hosted hq-mcp with `hq mcp login` first.");
+    if (cache.expiresAt > now + EXPIRY_SKEW_MS)
+        return cache.accessToken;
+    const origin = options.oauthOrigin ?? resolveHqMcpOAuthOrigin(options.env ?? process.env);
+    const tokens = await postForm(oauthUrl(origin, "/oauth/token"), new URLSearchParams({
+        grant_type: "refresh_token", client_id: cache.clientId, refresh_token: cache.refreshToken,
+    }), options.fetchImpl ?? fetch);
+    const refreshed = validTokens(tokens, now, cache);
+    refreshed.clientId = cache.clientId;
+    writeCache(file, refreshed);
+    return refreshed.accessToken;
+}
+/** Remove all per-origin hosted MCP OAuth caches during either HQ logout flow. */
+export function clearMcpOAuthCaches(options = {}) {
+    const env = options.env ?? process.env;
+    const stateDir = path.resolve(env.HQ_STATE_DIR?.trim() || path.join(options.home ?? os.homedir(), ".hq"));
+    let entries;
+    try {
+        entries = fs.readdirSync(stateDir);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw new McpOAuthError("The hosted MCP token cache could not be cleared. Check its directory permissions.");
+    }
+    for (const entry of entries) {
+        if (entry !== "mcp-oauth-tokens.json" && !/^mcp-oauth-tokens-[a-f0-9]{16}\.json$/.test(entry))
+            continue;
+        try {
+            fs.unlinkSync(path.join(stateDir, entry));
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw new McpOAuthError("The hosted MCP token cache could not be cleared. Check its file permissions.");
+        }
+    }
+}
+//# sourceMappingURL=mcp-oauth.js.map

package/dist/lib/daemon/ops/mcp.d.ts

@@ -13,7 +13,6 @@ export interface McpToolResult {
 }
 export declare function jsonResult(value: unknown): McpToolResult;
 export declare const HQ_MCP_HTTP_TIMEOUT_MS = 30000;
-/** Derive the hosted MCP sibling from the same hq-pro URL used by hq-cli. */
 export declare function resolveHqMcpEndpoint(env?: NodeJS.ProcessEnv): URL;
 export interface HqMcpBridgeOptions {
     endpoint?: URL;