@indigoai-us/hq-cli 5.325.0 → 5.327.0

package/dist/lib/anywhere-runtime-flag-key.d.ts

@@ -0,0 +1,3 @@
+/** hq-flags key for the staged HQ Anywhere runtime. The registry default is off. */
+export declare const HQ_ANYWHERE_RUNTIME_FLAG = "hq-anywhere-runtime";
+//# sourceMappingURL=anywhere-runtime-flag-key.d.ts.map

package/dist/lib/anywhere-runtime-flag-key.js

@@ -0,0 +1,3 @@
+/** hq-flags key for the staged HQ Anywhere runtime. The registry default is off. */
+export const HQ_ANYWHERE_RUNTIME_FLAG = "hq-anywhere-runtime";
+//# sourceMappingURL=anywhere-runtime-flag-key.js.map

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

@@ -0,0 +1,53 @@
+/** Hosted hq-mcp forwarding used by the hqd mcp.call operation. */
+export declare class McpOpError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export interface McpToolResult {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+}
+export declare function jsonResult(value: unknown): McpToolResult;
+export declare const HQ_MCP_HTTP_TIMEOUT_MS = 30000;
+export declare function resolveHqMcpEndpoint(env?: NodeJS.ProcessEnv): URL;
+export interface HqMcpBridgeOptions {
+    endpoint?: URL;
+    env?: NodeJS.ProcessEnv;
+    getToken?: () => Promise<string>;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}
+/** A short-lived Streamable HTTP MCP client; no local hq-mcp process is started. */
+export declare class HqMcpBridge {
+    private readonly endpoint;
+    private readonly getToken;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    private readonly activeClients;
+    constructor(options?: HqMcpBridgeOptions);
+    listTools(): Promise<Array<{
+        name: string;
+        description?: string;
+        inputSchema: Record<string, unknown>;
+    }>>;
+    callTool(name: string, args: Record<string, unknown>, timeoutMs?: number): Promise<unknown>;
+    close(): void;
+    private withClient;
+    private toSafeError;
+}
+export interface RunWorkerRequest {
+    worker: string;
+    skill?: string;
+    args?: string;
+    company?: string;
+}
+/**
+ * Dispatch `/run <worker> <skill> <args>` in a detached headless Claude Code
+ * session rooted at HQ_ROOT. HQ_RUN_WORKER_CMD overrides the binary (tests).
+ */
+export declare function runWorker(req: RunWorkerRequest, hqRoot: string, env: NodeJS.ProcessEnv, now: Date): Promise<Record<string, unknown>>;
+//# sourceMappingURL=mcp.d.ts.map

package/dist/lib/daemon/ops/mcp.js

@@ -0,0 +1,217 @@
+/** Hosted hq-mcp forwarding used by the hqd mcp.call operation. */
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { McpEndpointError, resolveHqMcpEndpoint as resolveEndpoint } from "../mcp-endpoint.js";
+import { ensurePrivateDir, openPrivateAppend } from "../paths.js";
+export class McpOpError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "McpOpError";
+    }
+}
+export function jsonResult(value) {
+    const structured = value && typeof value === "object" && !Array.isArray(value) ? value : { value };
+    return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }], structuredContent: structured };
+}
+export const HQ_MCP_HTTP_TIMEOUT_MS = 30_000;
+export function resolveHqMcpEndpoint(env = process.env) {
+    try {
+        return resolveEndpoint(env);
+    }
+    catch (error) {
+        if (error instanceof McpEndpointError)
+            throw new McpOpError(error.code, error.message);
+        throw error;
+    }
+}
+async function defaultMcpToken() {
+    const { ensureCognitoToken, resolveCognitoTokenSource } = await import("../../../utils/cognito-session.js");
+    if (resolveCognitoTokenSource() !== "machine") {
+        const { getMcpAudienceToken, McpOAuthError } = await import("../mcp-oauth.js");
+        try {
+            return await getMcpAudienceToken();
+        }
+        catch (error) {
+            if (error instanceof McpOAuthError)
+                throw new McpOpError(error.code, error.message);
+            throw new McpOpError("hq_mcp_auth_required", "Hosted MCP sign-in is required. Run `hq mcp login` and retry.");
+        }
+    }
+    try {
+        // Send this box's existing machine token. The hosted hq-mcp audience check
+        // accepts it only when it was issued for hqMcpMachineClient; otherwise the
+        // server rejects it. This helper does not inspect the credential's client ID.
+        return await ensureCognitoToken({ tokenSource: "machine", interactive: false });
+    }
+    catch {
+        throw new McpOpError("hq_mcp_auth_required", "An hq-mcp machine token is unavailable. Configure this box with hq-pro's hqMcpMachineClient ID, then retry the daemon call.");
+    }
+}
+/** A short-lived Streamable HTTP MCP client; no local hq-mcp process is started. */
+export class HqMcpBridge {
+    endpoint;
+    getToken;
+    fetchImpl;
+    timeoutMs;
+    activeClients = new Set();
+    constructor(options = {}) {
+        this.endpoint = options.endpoint ?? resolveHqMcpEndpoint(options.env ?? process.env);
+        this.getToken = options.getToken ?? defaultMcpToken;
+        this.fetchImpl = options.fetchImpl ?? fetch;
+        this.timeoutMs = options.timeoutMs ?? HQ_MCP_HTTP_TIMEOUT_MS;
+    }
+    async listTools() {
+        return this.withClient(async (client) => {
+            const result = await client.listTools();
+            return result.tools.map((tool) => ({
+                name: tool.name,
+                ...(tool.description ? { description: tool.description } : {}),
+                inputSchema: tool.inputSchema,
+            }));
+        });
+    }
+    async callTool(name, args, timeoutMs = this.timeoutMs) {
+        return this.withClient(async (client, token) => {
+            const { tools } = await client.listTools();
+            if (!tools.some((tool) => tool.name === name)) {
+                throw new McpOpError("hq_mcp_tool_unavailable", `Hosted hq-mcp does not expose ${name}.`);
+            }
+            return await client.callTool({ name, arguments: args });
+        }, timeoutMs);
+    }
+    close() {
+        for (const client of this.activeClients) {
+            void client.close().catch(() => {
+                // The in-flight call is already being cancelled; shutdown owns its result.
+            });
+        }
+    }
+    async withClient(work, timeoutMs = this.timeoutMs) {
+        let token = "";
+        let transport;
+        let client;
+        let timeout;
+        let timedOut = false;
+        const abortController = new AbortController();
+        let httpErrorClass;
+        try {
+            const [clientModule, httpModule] = await Promise.all([
+                import("@modelcontextprotocol/sdk/client/index.js"),
+                import("@modelcontextprotocol/sdk/client/streamableHttp.js"),
+            ]);
+            httpErrorClass = httpModule.StreamableHTTPError;
+            token = await this.getToken();
+            if (!token.trim())
+                throw new McpOpError("hq_mcp_auth_required", "An hq-mcp audience token is required.");
+            transport = new httpModule.StreamableHTTPClientTransport(this.endpoint, {
+                requestInit: {
+                    headers: { Authorization: `Bearer ${token}` },
+                },
+                fetch: (input, init) => this.fetchImpl(input, {
+                    ...init,
+                    signal: init?.signal ? AbortSignal.any([abortController.signal, init.signal]) : abortController.signal,
+                }),
+            });
+            client = new clientModule.Client({ name: "hqd", version: "1" }, { capabilities: {} });
+            this.activeClients.add(client);
+            timeout = setTimeout(() => {
+                timedOut = true;
+                abortController.abort();
+                void client?.close().catch(() => {
+                    // The deadline already ended the request.
+                });
+            }, timeoutMs);
+            await client.connect(transport);
+            return await work(client, token);
+        }
+        catch (error) {
+            if (timedOut) {
+                throw new McpOpError("hq_mcp_timeout", `Hosted hq-mcp request did not finish within ${timeoutMs}ms.`);
+            }
+            throw this.toSafeError(error, token, httpErrorClass);
+        }
+        finally {
+            if (timeout)
+                clearTimeout(timeout);
+            if (client) {
+                this.activeClients.delete(client);
+                try {
+                    await client.close();
+                }
+                catch {
+                    // Closing a finished HTTP session cannot change the request result.
+                }
+            }
+            else if (transport) {
+                try {
+                    await transport.close();
+                }
+                catch {
+                    // Same as above; the transport owns no child process or token cache.
+                }
+            }
+        }
+    }
+    toSafeError(error, token, StreamableHTTPErrorClass) {
+        if (error instanceof McpOpError)
+            return error;
+        if (error instanceof McpEndpointError)
+            return new McpOpError(error.code, error.message);
+        const status = StreamableHTTPErrorClass && error instanceof StreamableHTTPErrorClass ? error.code : undefined;
+        if (status === 401 || status === 403) {
+            return new McpOpError("hq_mcp_auth_required", "Hosted hq-mcp rejected this token. Use the DCR plus PKCE person flow or configure the hq-mcp machine client ID on this box.");
+        }
+        const message = error instanceof Error ? error.message : "request failed";
+        const safe = token ? message.split(token).join("[redacted]") : message;
+        return new McpOpError("hq_mcp_error", `Hosted hq-mcp request failed: ${safe}`);
+    }
+}
+const SLUG_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+/**
+ * Dispatch `/run <worker> <skill> <args>` in a detached headless Claude Code
+ * session rooted at HQ_ROOT. HQ_RUN_WORKER_CMD overrides the binary (tests).
+ */
+export async function runWorker(req, hqRoot, env, now) {
+    if (!SLUG_RE.test(req.worker))
+        throw new McpOpError("bad_args", "worker must be a worker id (letters, digits, '.', '_', '-')");
+    if (req.skill !== undefined && !SLUG_RE.test(req.skill))
+        throw new McpOpError("bad_args", "skill must be a skill name");
+    const prompt = ["/run", req.worker, req.skill, req.args?.trim()].filter(Boolean).join(" ");
+    const logDir = path.join(hqRoot, "workspace", "orchestrator", "hqd-run-worker");
+    ensurePrivateDir(logDir);
+    const logPath = path.join(logDir, `${now.toISOString().replace(/[:.]/g, "-")}-${req.worker}.log`);
+    const fd = openPrivateAppend(logPath);
+    fs.chmodSync(logPath, 0o600);
+    const bin = env.HQ_RUN_WORKER_CMD?.trim() || "claude";
+    try {
+        const workerEnv = { ...env };
+        for (const key of Object.keys(workerEnv)) {
+            if (key.toUpperCase() === "HQ_SPAWN_COMPANY")
+                delete workerEnv[key];
+        }
+        if (req.company)
+            workerEnv.HQ_SPAWN_COMPANY = req.company;
+        const child = spawn(bin, ["-p", prompt], {
+            cwd: hqRoot,
+            env: workerEnv,
+            detached: true,
+            stdio: ["ignore", fd, fd],
+        });
+        await new Promise((resolve, reject) => {
+            child.once("spawn", resolve);
+            child.once("error", (err) => {
+                fs.appendFileSync(logPath, `\nhqd could not start ${bin}: ${err.message}\n`, { mode: 0o600 });
+                reject(new McpOpError("worker_spawn_failed", `could not start ${bin}: ${err.message}`));
+            });
+        });
+        child.unref();
+        return { dispatched: true, prompt, pid: child.pid ?? null, logPath, company: req.company ?? null };
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+//# sourceMappingURL=mcp.js.map

package/dist/lib/daemon/protocol.d.ts

@@ -7,10 +7,11 @@
  * out of order, so clients match them by `id`.
  */
 export declare const HQD_SOCKET_NAME = "hqd.sock";
-export declare const HQD_OPS: readonly ["ping", "resolve", "session.open", "session.get", "session.close", "policy.check", "policy.index", "journal.append", "memory.get", "memory.put", "mesh.presence", "shutdown"];
+export declare const HQD_OPS: readonly ["ping", "resolve", "session.open", "session.get", "session.close", "policy.check", "policy.index", "journal.append", "memory.get", "memory.put", "mesh.presence", "mcp.call", "shutdown"];
 export type HqdOp = (typeof HQD_OPS)[number];
 /** A request line larger than this is rejected and the connection closed. */
 export declare const HQD_MAX_LINE_BYTES: number;
+export declare const HQD_DEFAULT_REQUEST_TIMEOUT_MS = 2000;
 export interface HqdRequest {
     id: string | number;
     op: string;