@indigoai-us/hq-cli 5.77.14 → 5.79.0

package/dist/utils/hq-roots.js

@@ -0,0 +1,212 @@
+/**
+ * Root resolution for CLI-hosted HQ scaffold code.
+ *
+ * When shell that used to live inside the HQ scaffold moves into this npm
+ * package, it loses the one thing it relied on: `BASH_SOURCE`/`$0` pointed at
+ * the user's live HQ tree, so "where am I" and "where is HQ" were the same
+ * answer. Inside a globally installed package they are three different answers,
+ * and conflating any two of them silently corrupts the wrong tree.
+ *
+ *   liveRoot    The user's HQ installation — companies/, workspace/, personal/,
+ *               the installed .claude/ and core/. This is runtime state. Hidden
+ *               runtime commands operate here.
+ *
+ *   packageRoot This npm package's own directory, where bundled scaffold assets
+ *               ship. Read-only in practice: a global install may sit in a
+ *               root-owned prefix. NEVER usable as liveRoot.
+ *
+ * There is deliberately no third "source root". Release-source tooling — the
+ * linters, generators, and validators that rewrite checked-in artifacts — stays
+ * scaffold-owned, so nothing here ever needs to resolve an hq-core checkout. See
+ * the scaffold-vs-cli-code-ownership policy for why.
+ *
+ * The invariant that matters most: `resolveLiveRoot` never consults
+ * `import.meta.url`. A relocated script asking "where is HQ" must get the live
+ * tree, not the package it happens to be bundled in.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { fileURLToPath } from "url";
+/** This package's name, used to identify its root when walking upward. */
+const CLI_PACKAGE_NAME = "@indigoai-us/hq-cli";
+/**
+ * A root that cannot be resolved is the caller's state — a wrong `--hq-root`, or a
+ * command run from outside any HQ tree. Marking
+ * these `expected` makes the top-level handler print the message and skip Sentry;
+ * an unmarked error there prints NOTHING and only ships a crash report, which is
+ * the worst possible outcome for a misconfiguration the user can fix.
+ *
+ * Deliberately not used for packaging faults — a missing bundled asset IS a
+ * defect and should reach Sentry.
+ */
+function rootError(message) {
+    const err = new Error(message);
+    err.expected = true;
+    return err;
+}
+/** Where bundled scaffold assets live, relative to the package root. */
+export const BUNDLED_ASSET_DIR = path.join("assets", "scaffold");
+/**
+ * Does this directory look like an HQ tree root?
+ *
+ * `companies/` is the load-bearing marker — it is the source of truth for
+ * tenants and exists in every real install. The second clause tolerates the
+ * three shapes a tree can legitimately be in: a full install, a scaffold
+ * checkout without a personal overlay, and a personal-only overlay.
+ */
+export function isHqRoot(dir) {
+    return (fs.existsSync(path.join(dir, "companies")) &&
+        (fs.existsSync(path.join(dir, ".claude")) ||
+            fs.existsSync(path.join(dir, "core")) ||
+            fs.existsSync(path.join(dir, "personal"))));
+}
+function realpathOrResolve(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+let cachedPackageRoot;
+/**
+ * This package's installed root — the directory holding its `package.json`.
+ *
+ * Walks up from the compiled module (`dist/utils/hq-roots.js`) until it finds a
+ * `package.json` whose name matches, rather than hard-coding `..` hops, so the
+ * answer survives a change in output layout.
+ */
+export function packageRoot() {
+    if (cachedPackageRoot === null) {
+        throw new Error(`Could not locate the ${CLI_PACKAGE_NAME} package root from ${import.meta.url}.`);
+    }
+    if (cachedPackageRoot !== undefined)
+        return cachedPackageRoot;
+    let dir = path.dirname(fileURLToPath(import.meta.url));
+    for (;;) {
+        const manifest = path.join(dir, "package.json");
+        if (fs.existsSync(manifest)) {
+            try {
+                const parsed = JSON.parse(fs.readFileSync(manifest, "utf8"));
+                if (parsed.name === CLI_PACKAGE_NAME) {
+                    cachedPackageRoot = realpathOrResolve(dir);
+                    return cachedPackageRoot;
+                }
+            }
+            catch {
+                // A malformed package.json on the way up is not our package; keep going.
+            }
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    cachedPackageRoot = null;
+    throw new Error(`Could not locate the ${CLI_PACKAGE_NAME} package root from ${import.meta.url}.`);
+}
+/** Reset the memoized package root. Tests only. */
+export function __resetPackageRootCache() {
+    cachedPackageRoot = undefined;
+}
+/**
+ * Resolve the user's live HQ installation.
+ *
+ * Precedence: `--hq-root` → `HQ_ROOT` → `CLAUDE_PROJECT_DIR` → walk up from cwd.
+ *
+ * ## An explicit root is trusted; a discovered one must be recognized
+ *
+ * The FIRST explicit candidate present wins outright — there is no fall-through
+ * past it, because silently operating on a different tree than the caller named
+ * is the worst available outcome.
+ *
+ * That explicit candidate is checked only for the two things that are always
+ * wrong: it must be a directory, and it must not be inside {@link packageRoot}
+ * (that is this package, not anyone's HQ). It is deliberately NOT required to
+ * satisfy {@link isHqRoot}.
+ *
+ * Requiring markers here was tried and was wrong: the scripts these roots feed
+ * accepted any `HQ_ROOT` before they moved, and several callers legitimately pass
+ * a minimal tree — e.g. `rebuild-threads-index` against a fixture holding nothing
+ * but `workspace/threads/`. Enforcing markers on an explicit value turned a
+ * relocation into a silent contract change and broke those callers.
+ *
+ * The cwd walk is the opposite case: there the marker check is the only thing
+ * that can identify a root at all, so it stays mandatory.
+ */
+export function resolveLiveRoot(opts = {}) {
+    const env = opts.env ?? process.env;
+    const candidates = [];
+    if (opts.hqRoot) {
+        candidates.push({ value: opts.hqRoot, source: "--hq-root" });
+    }
+    if (env.HQ_ROOT) {
+        candidates.push({ value: env.HQ_ROOT, source: "$HQ_ROOT" });
+    }
+    if (env.CLAUDE_PROJECT_DIR) {
+        candidates.push({
+            value: env.CLAUDE_PROJECT_DIR,
+            source: "$CLAUDE_PROJECT_DIR",
+        });
+    }
+    const explicit = candidates[0];
+    if (explicit) {
+        const resolved = realpathOrResolve(explicit.value);
+        if (isWithinPackage(resolved)) {
+            throw rootError(`${explicit.source} points inside the ${CLI_PACKAGE_NAME} package ` +
+                `(${resolved}). That is the CLI's own install directory, not an HQ tree.`);
+        }
+        if (!fs.existsSync(resolved) || !fs.statSync(resolved).isDirectory()) {
+            throw rootError(`${explicit.source} is not a directory: ${resolved}`);
+        }
+        return resolved;
+    }
+    // Walk up from cwd. Unlike the explicit tiers this is a guess, so failing to
+    // find a root here is reported as "run this from inside HQ" rather than as a
+    // bad value.
+    let dir = realpathOrResolve(opts.cwd ?? process.cwd());
+    for (;;) {
+        if (isHqRoot(dir) && !isWithinPackage(dir))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    throw rootError("Could not find your HQ installation. Run this from inside your HQ " +
+        "directory, or pass --hq-root <path> / set $HQ_ROOT.");
+}
+function isWithinPackage(candidate) {
+    let root;
+    try {
+        root = packageRoot();
+    }
+    catch {
+        // If we cannot locate our own package we cannot be inside it either.
+        return false;
+    }
+    const rel = path.relative(root, candidate);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+/**
+ * Absolute path to a scaffold asset bundled in this package.
+ *
+ * Refuses to resolve outside the asset directory so a manifest entry can never
+ * be coaxed into executing an arbitrary path, and fails loudly when the asset
+ * is missing — an absent asset means the packlist dropped it, which is a
+ * packaging bug worth surfacing rather than a runtime fallback.
+ */
+export function resolveBundledAsset(relativePath) {
+    const assetDir = path.join(packageRoot(), BUNDLED_ASSET_DIR);
+    const resolved = path.resolve(assetDir, relativePath);
+    const rel = path.relative(assetDir, resolved);
+    if (rel.startsWith("..") || path.isAbsolute(rel)) {
+        throw new Error(`Bundled asset path escapes ${BUNDLED_ASSET_DIR}: ${relativePath}`);
+    }
+    if (!fs.existsSync(resolved)) {
+        throw new Error(`Bundled asset is missing from the installed package: ${BUNDLED_ASSET_DIR}/${relativePath}\n` +
+            "This is a packaging fault — the file exists in source but was not published.");
+    }
+    return resolved;
+}
+//# sourceMappingURL=hq-roots.js.map

package/dist/utils/resolve-vault-credential.d.ts

@@ -1,5 +1,27 @@
 /** Vault API keys issued by `hq api-keys create` (hq-pro). */
 export declare const HQ_API_KEY_PREFIX = "hqk_";
+/**
+ * Capability catalog for identity-bound vault API keys. MUST match hq-pro's
+ * `src/api-keys/capabilities.ts` — the server is authoritative for what a key
+ * may do; this copy exists so the CLI can name capabilities in `api-keys
+ * create` and in its own fail-closed messages.
+ */
+export declare const API_KEY_CAPABILITIES: readonly ["secrets:read", "secrets:write", "secrets:share", "deploy:write", "deploy:read", "files:read", "files:write", "search:query", "agents:use", "mcp:call", "packs:install", "members:read", "members:write"];
+export type ApiKeyCapability = (typeof API_KEY_CAPABILITIES)[number];
+/** Deploy apps wildcard: every app the key owner can reach at use time. */
+export declare const DEPLOY_APP_ALL = "*";
+export declare function isApiKeyCapability(value: string): value is ApiKeyCapability;
+/**
+ * Capabilities hq-cli can exercise with an `HQ_API_KEY`. Vault surfaces use
+ * parallel Bearer `hqk_` routes under `/v1/keys/…` (rewritten in
+ * {@link vaultApiFetch}); `deploy:*` is consumed by hq-deploy via SigV4
+ * introspect. Surfaces without a keyed route still fail closed.
+ */
+export declare const CLI_API_KEY_CAPABILITIES: readonly ApiKeyCapability[];
+/** True when hq-cli has a Bearer `hqk_` route for this capability. */
+export declare function apiKeyCapabilityIsUsable(capability: ApiKeyCapability): boolean;
+/** Catalog capabilities hq-cli cannot use with an API key yet. */
+export declare function unusableApiKeyCapabilities(): ApiKeyCapability[];
 export type VaultCredential = {
     kind: "api-key";
     token: string;
@@ -23,8 +45,46 @@ export declare function resolveVaultCredential(options?: {
     interactive?: boolean;
 }): Promise<VaultCredential>;
 /**
- * Throw when HQ_API_KEY is set but the command only supports Cognito sessions
- * (list, set, ACL, api-keys admin, etc.).
+ * Fail-closed message for a surface an `HQ_API_KEY` cannot drive. Always names
+ * what an API key CAN do (granted) next to what it cannot (missing), so the
+ * caller can decide between minting a broader key and unsetting HQ_API_KEY.
+ */
+export declare function apiKeyCapabilityGateMessage(capability: ApiKeyCapability | null, commandLabel: string, options?: {
+    routeAvailable?: boolean;
+}): string;
+/**
+ * Capability gate for a command about to run under `HQ_API_KEY`.
+ *
+ * No-op when HQ_API_KEY is unset (the Cognito path is unchanged) and when the
+ * capability has a CLI-reachable Bearer `hqk_` route. Otherwise throws a
+ * fail-closed error listing granted vs missing capabilities.
+ *
+ * - `capability: null` — the surface has no capability at all (key
+ *   administration, interactive session flows).
+ * - `routeAvailable: false` — the capability exists in the catalog but this
+ *   specific surface has no `/v1/keys` route (e.g. the secrets HEAD probe).
+ *
+ * The server re-checks the key's real grants on every call; this gate only
+ * stops the CLI from quietly using a Cognito session instead of the key.
+ */
+export declare function requireApiKeyCapability(capability: ApiKeyCapability | null, commandLabel: string, options?: {
+    routeAvailable?: boolean;
+}): void;
+/**
+ * {@link resolveVaultCredential} behind {@link requireApiKeyCapability}: the
+ * gate runs BEFORE any credential work so a key that cannot drive the surface
+ * never reaches the network and never triggers an interactive login.
+ */
+export declare function resolveVaultCredentialForCapability(capability: ApiKeyCapability | null, commandLabel: string, options?: {
+    interactive?: boolean;
+    routeAvailable?: boolean;
+}): Promise<VaultCredential>;
+/**
+ * Render hq-pro's capability-denial body (`_api-key-auth.ts` returns
+ * `{ error, granted: string[], missing: string }` on a 403) as a message that
+ * names the key's REAL granted set next to what the call needed. This is the
+ * authoritative granted-vs-missing report; the client-side gate above can only
+ * describe what hq-cli supports.
  */
-export declare function assertCognitoOnlyCommand(commandLabel: string): void;
+export declare function formatApiKeyCapabilityDenial(body: unknown, fallback: string): string;
 //# sourceMappingURL=resolve-vault-credential.d.ts.map

package/dist/utils/resolve-vault-credential.js

@@ -1,6 +1,63 @@
 import { ensureCognitoToken } from "./cognito-session.js";
 /** Vault API keys issued by `hq api-keys create` (hq-pro). */
 export const HQ_API_KEY_PREFIX = "hqk_";
+/**
+ * Capability catalog for identity-bound vault API keys. MUST match hq-pro's
+ * `src/api-keys/capabilities.ts` — the server is authoritative for what a key
+ * may do; this copy exists so the CLI can name capabilities in `api-keys
+ * create` and in its own fail-closed messages.
+ */
+export const API_KEY_CAPABILITIES = [
+    "secrets:read",
+    "secrets:write",
+    "secrets:share",
+    "deploy:write",
+    "deploy:read",
+    "files:read",
+    "files:write",
+    "search:query",
+    "agents:use",
+    "mcp:call",
+    "packs:install",
+    "members:read",
+    "members:write",
+];
+/** Deploy apps wildcard: every app the key owner can reach at use time. */
+export const DEPLOY_APP_ALL = "*";
+const CAPABILITY_SET = new Set(API_KEY_CAPABILITIES);
+export function isApiKeyCapability(value) {
+    return CAPABILITY_SET.has(value);
+}
+/**
+ * Capabilities hq-cli can exercise with an `HQ_API_KEY`. Vault surfaces use
+ * parallel Bearer `hqk_` routes under `/v1/keys/…` (rewritten in
+ * {@link vaultApiFetch}); `deploy:*` is consumed by hq-deploy via SigV4
+ * introspect. Surfaces without a keyed route still fail closed.
+ */
+export const CLI_API_KEY_CAPABILITIES = [
+    "secrets:read",
+    "secrets:write",
+    "secrets:share",
+    "deploy:write",
+    "deploy:read",
+    "files:read",
+    "files:write",
+    "search:query",
+    "agents:use",
+    "mcp:call",
+    "packs:install",
+    "members:read",
+    "members:write",
+];
+const CLI_CAPABILITY_SET = new Set(CLI_API_KEY_CAPABILITIES);
+/** True when hq-cli has a Bearer `hqk_` route for this capability. */
+export function apiKeyCapabilityIsUsable(capability) {
+    return CLI_CAPABILITY_SET.has(capability);
+}
+/** Catalog capabilities hq-cli cannot use with an API key yet. */
+export function unusableApiKeyCapabilities() {
+    return API_KEY_CAPABILITIES.filter((cap) => !CLI_CAPABILITY_SET.has(cap));
+}
 /**
  * Raw HQ_API_KEY from the environment, trimmed. Undefined when unset/empty.
  * Does not validate prefix — use {@link resolveVaultCredential} for that.
@@ -34,15 +91,104 @@ export async function resolveVaultCredential(options) {
     });
     return { kind: "cognito", token };
 }
+function expectedError(message) {
+    // Marked expected so main.ts prints the message and skips Sentry: a key
+    // presented at a surface it cannot serve is the caller's configuration,
+    // not an hq-cli defect.
+    return Object.assign(new Error(message), { expected: true });
+}
+function formatCapabilityList(capabilities) {
+    return capabilities.length > 0 ? capabilities.join(", ") : "(none)";
+}
 /**
- * Throw when HQ_API_KEY is set but the command only supports Cognito sessions
- * (list, set, ACL, api-keys admin, etc.).
+ * Fail-closed message for a surface an `HQ_API_KEY` cannot drive. Always names
+ * what an API key CAN do (granted) next to what it cannot (missing), so the
+ * caller can decide between minting a broader key and unsetting HQ_API_KEY.
  */
-export function assertCognitoOnlyCommand(commandLabel) {
+export function apiKeyCapabilityGateMessage(capability, commandLabel, options) {
+    const head = capability === null
+        ? `HQ_API_KEY is set; '${commandLabel}' is not supported for API keys — ` +
+            `no capability grants it (it needs your Cognito session).`
+        : options?.routeAvailable === false
+            ? `HQ_API_KEY is set; '${commandLabel}' is not supported for API keys — ` +
+                `capability '${capability}' would apply but hq-pro serves no vault ` +
+                `API-key route for it yet.`
+            : `HQ_API_KEY is set; '${commandLabel}' is not supported for API keys — ` +
+                `it needs capability '${capability}'.`;
+    return [
+        head,
+        `  Granted to hq-cli with an API key: ${formatCapabilityList(CLI_API_KEY_CAPABILITIES)}`,
+        `  Missing (Cognito session required): ${formatCapabilityList(unusableApiKeyCapabilities())}`,
+        `  Unset HQ_API_KEY to use your Cognito session.`,
+    ].join("\n");
+}
+/**
+ * Capability gate for a command about to run under `HQ_API_KEY`.
+ *
+ * No-op when HQ_API_KEY is unset (the Cognito path is unchanged) and when the
+ * capability has a CLI-reachable Bearer `hqk_` route. Otherwise throws a
+ * fail-closed error listing granted vs missing capabilities.
+ *
+ * - `capability: null` — the surface has no capability at all (key
+ *   administration, interactive session flows).
+ * - `routeAvailable: false` — the capability exists in the catalog but this
+ *   specific surface has no `/v1/keys` route (e.g. the secrets HEAD probe).
+ *
+ * The server re-checks the key's real grants on every call; this gate only
+ * stops the CLI from quietly using a Cognito session instead of the key.
+ */
+export function requireApiKeyCapability(capability, commandLabel, options) {
     if (peekHqApiKey() === undefined)
         return;
-    throw new Error(`HQ_API_KEY is set; '${commandLabel}' is not supported for API keys. ` +
-        `API keys support scoped secret reads via \`hq secrets get\`, \`hq secrets exec\`, ` +
-        `and \`hq secrets env\`. Unset HQ_API_KEY to use your Cognito session.`);
+    if (capability !== null &&
+        options?.routeAvailable !== false &&
+        apiKeyCapabilityIsUsable(capability)) {
+        return;
+    }
+    throw expectedError(apiKeyCapabilityGateMessage(capability, commandLabel, options));
+}
+/**
+ * {@link resolveVaultCredential} behind {@link requireApiKeyCapability}: the
+ * gate runs BEFORE any credential work so a key that cannot drive the surface
+ * never reaches the network and never triggers an interactive login.
+ */
+export async function resolveVaultCredentialForCapability(capability, commandLabel, options) {
+    requireApiKeyCapability(capability, commandLabel, {
+        routeAvailable: options?.routeAvailable,
+    });
+    return resolveVaultCredential({ interactive: options?.interactive });
+}
+/**
+ * Render hq-pro's capability-denial body (`_api-key-auth.ts` returns
+ * `{ error, granted: string[], missing: string }` on a 403) as a message that
+ * names the key's REAL granted set next to what the call needed. This is the
+ * authoritative granted-vs-missing report; the client-side gate above can only
+ * describe what hq-cli supports.
+ */
+export function formatApiKeyCapabilityDenial(body, fallback) {
+    const record = body !== null && typeof body === "object"
+        ? body
+        : {};
+    const head = typeof record.error === "string"
+        ? record.error
+        : typeof record.message === "string"
+            ? record.message
+            : fallback;
+    const granted = Array.isArray(record.granted)
+        ? record.granted.filter((cap) => typeof cap === "string")
+        : [];
+    const missing = Array.isArray(record.missing)
+        ? record.missing.filter((cap) => typeof cap === "string")
+        : typeof record.missing === "string"
+            ? [record.missing]
+            : [];
+    if (granted.length === 0 && missing.length === 0) {
+        return head;
+    }
+    return [
+        head,
+        `  Granted: ${formatCapabilityList(granted)}`,
+        `  Missing: ${formatCapabilityList(missing)}`,
+    ].join("\n");
 }
 //# sourceMappingURL=resolve-vault-credential.js.map

package/dist/utils/run-bundled-script.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Runner for scaffold shell bundled inside this package.
+ *
+ * The scripts this executes used to be invoked directly by skills, hooks, and
+ * other scripts. Their callers observe argv, stdin, stdout, stderr, and the exit
+ * code — so this runner's job is to be transparent on all five, and to hand the
+ * script the same environment it used to get from living inside the HQ tree.
+ *
+ * Deliberate choices:
+ *
+ *   - `stdio: "inherit"`. Not piped. Piping would buffer output that callers
+ *     stream, reorder stdout against stderr, and require re-emitting bytes we
+ *     have no reason to touch. Inheriting also means a script that reads stdin
+ *     (the hook payload pattern) gets the real fd, unbuffered and unconsumed.
+ *
+ *   - an explicit interpreter (`bash` or `node`) rather than executing the file
+ *     directly. The executable bit does survive `npm publish` for files that
+ *     carry it, but relying on it makes correctness depend on a mode that a
+ *     repack, a filesystem, or a zip round-trip can quietly drop. Naming the
+ *     interpreter removes that dependency without changing script semantics.
+ *     The interpreter is chosen by extension — two of the relocated assets are
+ *     Node programs, and running those through bash fails with a shell syntax
+ *     error on the first `const`.
+ *
+ *   - the exit code is returned, never mapped. A script that exits 2 to block a
+ *     tool call must still exit 2 through this path.
+ *
+ *   - signals are surfaced as the conventional 128+n. A caller that kills a
+ *     script needs to see termination, not a success code.
+ */
+/**
+ * Which interpreter runs a bundled asset, chosen by extension.
+ *
+ * Exported so the manifest test can assert every declared asset maps to one,
+ * rather than discovering a mismatch at runtime on a user's machine.
+ */
+export declare function interpreterFor(asset: string): "node" | "bash";
+export type RunBundledScriptOptions = {
+    /** Path of the script under `assets/scaffold/`, e.g. `core/scripts/foo.sh`. */
+    asset: string;
+    /** Arguments passed through to the script, unchanged. */
+    args?: string[];
+    /** Working directory for the child. Defaults to the resolved live root. */
+    cwd: string;
+    /**
+     * The live HQ root. Exported as both `HQ_ROOT` and `CLAUDE_PROJECT_DIR`
+     * because relocated scripts read one, the other, or both — and inside the CLI
+     * neither is guaranteed to already be set by the caller.
+     */
+    hqRoot?: string;
+    /** Extra environment for the child, applied last. */
+    env?: Record<string, string | undefined>;
+};
+export type RunBundledScriptResult = {
+    /** The child's exit code, or 128+signal if it was terminated by one. */
+    code: number;
+};
+/**
+ * Execute a bundled scaffold script and return its exit code.
+ *
+ * Does not throw on a non-zero exit — a non-zero code is data here, not an
+ * error, because several relocated scripts use exit codes as their interface.
+ * Throws only when the script could not be started at all.
+ */
+export declare function runBundledScript(opts: RunBundledScriptOptions): RunBundledScriptResult;
+//# sourceMappingURL=run-bundled-script.d.ts.map

package/dist/utils/run-bundled-script.js

@@ -0,0 +1,80 @@
+/**
+ * Runner for scaffold shell bundled inside this package.
+ *
+ * The scripts this executes used to be invoked directly by skills, hooks, and
+ * other scripts. Their callers observe argv, stdin, stdout, stderr, and the exit
+ * code — so this runner's job is to be transparent on all five, and to hand the
+ * script the same environment it used to get from living inside the HQ tree.
+ *
+ * Deliberate choices:
+ *
+ *   - `stdio: "inherit"`. Not piped. Piping would buffer output that callers
+ *     stream, reorder stdout against stderr, and require re-emitting bytes we
+ *     have no reason to touch. Inheriting also means a script that reads stdin
+ *     (the hook payload pattern) gets the real fd, unbuffered and unconsumed.
+ *
+ *   - an explicit interpreter (`bash` or `node`) rather than executing the file
+ *     directly. The executable bit does survive `npm publish` for files that
+ *     carry it, but relying on it makes correctness depend on a mode that a
+ *     repack, a filesystem, or a zip round-trip can quietly drop. Naming the
+ *     interpreter removes that dependency without changing script semantics.
+ *     The interpreter is chosen by extension — two of the relocated assets are
+ *     Node programs, and running those through bash fails with a shell syntax
+ *     error on the first `const`.
+ *
+ *   - the exit code is returned, never mapped. A script that exits 2 to block a
+ *     tool call must still exit 2 through this path.
+ *
+ *   - signals are surfaced as the conventional 128+n. A caller that kills a
+ *     script needs to see termination, not a success code.
+ */
+import { spawnSync } from "child_process";
+import * as path from "path";
+import { resolveBundledAsset } from "./hq-roots.js";
+/**
+ * Which interpreter runs a bundled asset, chosen by extension.
+ *
+ * Exported so the manifest test can assert every declared asset maps to one,
+ * rather than discovering a mismatch at runtime on a user's machine.
+ */
+export function interpreterFor(asset) {
+    const ext = path.extname(asset).toLowerCase();
+    return ext === ".mjs" || ext === ".js" || ext === ".cjs" ? "node" : "bash";
+}
+/**
+ * Execute a bundled scaffold script and return its exit code.
+ *
+ * Does not throw on a non-zero exit — a non-zero code is data here, not an
+ * error, because several relocated scripts use exit codes as their interface.
+ * Throws only when the script could not be started at all.
+ */
+export function runBundledScript(opts) {
+    const script = resolveBundledAsset(opts.asset);
+    const env = { ...process.env };
+    if (opts.hqRoot) {
+        env.HQ_ROOT = opts.hqRoot;
+        env.CLAUDE_PROJECT_DIR = opts.hqRoot;
+    }
+    Object.assign(env, opts.env ?? {});
+    const result = spawnSync(interpreterFor(opts.asset), [script, ...(opts.args ?? [])], {
+        cwd: opts.cwd,
+        env,
+        stdio: "inherit",
+    });
+    if (result.error) {
+        throw new Error(`Failed to run bundled script ${opts.asset}: ${result.error.message}`);
+    }
+    if (result.signal) {
+        // Conventional shell encoding, so a caller checking for termination sees it.
+        const signals = {
+            SIGHUP: 1,
+            SIGINT: 2,
+            SIGQUIT: 3,
+            SIGKILL: 9,
+            SIGTERM: 15,
+        };
+        return { code: 128 + (signals[result.signal] ?? 0) };
+    }
+    return { code: result.status ?? 0 };
+}
+//# sourceMappingURL=run-bundled-script.js.map

package/dist/utils/vault-api.d.ts

@@ -13,6 +13,27 @@ export interface VaultApiOptions {
     query?: Record<string, string>;
     signal?: AbortSignal;
 }
+/**
+ * Map Cognito JWT paths onto parallel Bearer `hqk_` routes under `/v1/keys/…`.
+ * Returns null when no keyed route exists (caller must fail closed).
+ *
+ * The table mirrors hq-pro's gateway routes, NOT its path shapes: a rewrite is
+ * listed only where an `hqk_`-authorized route actually exists. Two surfaces
+ * are therefore unmapped ON PURPOSE, and adding a rewrite for them would turn
+ * an explicit fail-closed error into a 404/401 that reads like a login problem:
+ *
+ *   - the unversioned file ACL + share surfaces (`/files/{companyUid}/acl…`,
+ *     `/files/{companyUid}/share-session`) — hq-pro serves these under JWT
+ *     only. `/v1/keys/files/…` exists but covers the VERSIONED family
+ *     (`list`, `versions`, `versions-list`, `grants`, `tombstones`, `presign`,
+ *     `delete`, `restore`), which is a different set of handlers.
+ *   - the notify surface (`/v1/notify/dm`, `/v1/notify/thread`) behind
+ *     `hq agents message|thread` — there is no `/v1/keys/notify…` route.
+ *
+ * Both are additionally gated at the command layer so they fail before any
+ * network call; this stays the backstop for a new call site that forgets to.
+ */
+export declare function rewritePathForApiKey(path: string): string | null;
 export declare function vaultApiFetch(opts: VaultApiOptions): Promise<Response>;
 /**
  * Public (NONE-auth) GET against the vault API — no bearer token. The