@indigoai-us/hq-cli 5.314.0 → 5.315.0

package/dist/lib/company-skill-wrapper.js

@@ -62,20 +62,6 @@ function symlinkTarget(linkPath) {
 function generatedMarkerPath(wrapperPath) {
     return path.join(path.dirname(wrapperPath), WRAPPER_MARKER_DIR, `${path.basename(wrapperPath)}.json`);
 }
-function hasBoundGeneratedMarker(wrapperPath, companySlug) {
-    try {
-        const marker = JSON.parse(fs.readFileSync(generatedMarkerPath(wrapperPath), "utf8"));
-        const wrapper = fs.lstatSync(wrapperPath);
-        return (marker.version === 2 &&
-            marker.companySlug === companySlug &&
-            marker.wrapperDev === wrapper.dev &&
-            marker.wrapperIno === wrapper.ino &&
-            marker.wrapperBirthtimeMs === wrapper.birthtimeMs);
-    }
-    catch {
-        return false;
-    }
-}
 function writeGeneratedMarker(wrapperPath, companySlug, skillSlug) {
     const markerPath = generatedMarkerPath(wrapperPath);
     try {
@@ -104,21 +90,116 @@ function removeGeneratedMarker(wrapperPath) {
         // never sufficient to surface content on its own.
     }
 }
-function isGeneratedNamespacedWrapper(wrapperPath, hqRoot, companySlug) {
+const COMPANY_SKILL_WRAPPER_DIAGNOSTICS = Symbol("company-skill-wrapper-diagnostics");
+function companySkillWrapperOwnershipError(wrapperPath, diagnostics) {
+    const error = new Error(`Cannot replace '${wrapperPath}' because it is not an HQ-generated skill wrapper.`);
+    Object.defineProperty(error, COMPANY_SKILL_WRAPPER_DIAGNOSTICS, {
+        value: diagnostics,
+    });
+    return error;
+}
+export function companySkillWrapperSentryTagsFor(error) {
+    if (!(error instanceof Error))
+        return undefined;
+    const diagnostics = error[COMPANY_SKILL_WRAPPER_DIAGNOSTICS];
+    if (!diagnostics)
+        return undefined;
+    return {
+        hq_cli_skill_wrapper_kind: diagnostics.kind,
+        hq_cli_skill_wrapper_bridge_state: diagnostics.bridgeState,
+        hq_cli_skill_wrapper_marker_state: diagnostics.markerState,
+        hq_cli_skill_wrapper_link_target: diagnostics.linkTarget,
+        hq_cli_skill_wrapper_platform: diagnostics.platform,
+        hq_cli_skill_wrapper_name_encoding: diagnostics.nameEncoding,
+    };
+}
+function inspectGeneratedNamespacedWrapper(wrapperPath, hqRoot, companySlug) {
     const companySkillsRoot = path.join(hqRoot, "companies", companySlug, "skills");
-    const wrapperTarget = symlinkTarget(wrapperPath);
-    if (wrapperTarget)
-        return isWithin(companySkillsRoot, wrapperTarget);
-    const wrapper = lstat(wrapperPath);
-    if (!wrapper?.isDirectory())
-        return false;
+    const wrapperEntry = lstat(wrapperPath);
+    if (wrapperEntry?.isSymbolicLink()) {
+        const target = symlinkTarget(wrapperPath);
+        const linkTarget = target === undefined
+            ? "unavailable"
+            : isWithin(companySkillsRoot, target)
+                ? "company_skills"
+                : "outside_company_skills";
+        return {
+            owned: linkTarget === "company_skills",
+            diagnostics: {
+                kind: "symlink",
+                bridgeState: "not_applicable",
+                markerState: "not_applicable",
+                linkTarget,
+            },
+        };
+    }
+    if (!wrapperEntry?.isDirectory()) {
+        return {
+            owned: false,
+            diagnostics: {
+                kind: wrapperEntry?.isFile() ? "file" : "other",
+                bridgeState: "not_applicable",
+                markerState: "not_applicable",
+                linkTarget: "not_applicable",
+            },
+        };
+    }
     const entries = fs.readdirSync(wrapperPath).filter((entry) => !entry.startsWith("."));
-    const containsOnlyLiveBridges = (entries.length > 0 &&
-        entries.every((entry) => {
-            const target = symlinkTarget(path.join(wrapperPath, entry));
-            return target !== undefined && isWithin(companySkillsRoot, target);
-        }));
-    return containsOnlyLiveBridges || hasBoundGeneratedMarker(wrapperPath, companySlug);
+    const liveBridgeCount = entries.reduce((count, entry) => {
+        const target = symlinkTarget(path.join(wrapperPath, entry));
+        return count + (target !== undefined && isWithin(companySkillsRoot, target) ? 1 : 0);
+    }, 0);
+    const bridgeState = entries.length === 0
+        ? "empty"
+        : liveBridgeCount === entries.length
+            ? "all_live"
+            : liveBridgeCount > 0
+                ? "partial"
+                : "none";
+    const markerState = generatedMarkerState(wrapperPath, companySlug);
+    return {
+        owned: bridgeState === "all_live" || markerState === "bound",
+        diagnostics: {
+            kind: "directory",
+            bridgeState,
+            markerState,
+            linkTarget: "not_applicable",
+        },
+    };
+}
+function isGeneratedNamespacedWrapper(wrapperPath, hqRoot, companySlug) {
+    return inspectGeneratedNamespacedWrapper(wrapperPath, hqRoot, companySlug).owned;
+}
+function generatedMarkerState(wrapperPath, companySlug) {
+    let markerContents;
+    try {
+        markerContents = fs.readFileSync(generatedMarkerPath(wrapperPath), "utf8");
+    }
+    catch (error) {
+        return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT"
+            ? "missing"
+            : "unavailable";
+    }
+    let marker;
+    try {
+        marker = JSON.parse(markerContents);
+    }
+    catch {
+        return "invalid";
+    }
+    try {
+        const wrapper = fs.lstatSync(wrapperPath);
+        return marker.version === 2 &&
+            marker.companySlug === companySlug &&
+            marker.wrapperDev === wrapper.dev &&
+            marker.wrapperIno === wrapper.ino &&
+            marker.wrapperBirthtimeMs === wrapper.birthtimeMs
+            ? "bound"
+            : "unbound";
+    }
+    catch {
+        return "unavailable";
+    }
 }
 function isGeneratedLegacyEntry(legacyPath, sourceDir, skillFile) {
     const target = symlinkTarget(legacyPath);
@@ -224,8 +305,19 @@ export function surfaceCompanySkill(input) {
         const backupPath = `${stagingPath}.previous`;
         let previousMoved = false;
         if (currentWrapper) {
-            if (!isGeneratedNamespacedWrapper(wrapperPath, input.hqRoot, input.companySlug)) {
-                throw new Error(`Cannot replace '${wrapperPath}' because it is not an HQ-generated skill wrapper.`);
+            const ownership = inspectGeneratedNamespacedWrapper(wrapperPath, input.hqRoot, input.companySlug);
+            if (!ownership.owned) {
+                const runtimePlatform = process.platform;
+                const platform = win32
+                    ? "win32"
+                    : runtimePlatform === "darwin" || runtimePlatform === "linux"
+                        ? runtimePlatform
+                        : "other";
+                throw companySkillWrapperOwnershipError(wrapperPath, {
+                    ...ownership.diagnostics,
+                    platform,
+                    nameEncoding: win32 ? "percent_encoded" : "literal",
+                });
             }
             renameEntry(wrapperPath, backupPath);
             previousMoved = true;

package/dist/lib/core-utils/codex-skill-bridge.d.ts

@@ -1,4 +1,4 @@
-export type BridgeCommand = "status" | "install" | "doctor";
+type BridgeCommand = "status" | "install" | "doctor";
 export type BridgeOptions = {
     command: BridgeCommand;
     hqRoot: string;
@@ -28,4 +28,5 @@ export declare function isHqRootLike(candidate: string): boolean;
 export declare function outputStyleSlug(name: string): string;
 /** Runs one bridge command; returns the process exit code. */
 export declare function runCodexSkillBridge(options: BridgeOptions, io: BridgeIo): number;
+export {};
 //# sourceMappingURL=codex-skill-bridge.d.ts.map

package/dist/lib/core-utils/hook-timeout-debug-context-flag.d.ts

@@ -0,0 +1,20 @@
+import { type FlagClient, type FlagClientOptions } from "@indigoai-us/hq-flags-client";
+export declare const HOOK_TIMEOUT_DEBUG_CONTEXT_FLAG = "hook-timeout-debug-context";
+export declare const HOOK_TIMEOUT_DEBUG_CONTEXT_FLAG_FALLBACK = false;
+export declare const HOOK_TIMEOUT_DEBUG_CONTEXT_FLAG_TIMEOUT_MS = 150;
+type DebugContextFlagClient = Pick<FlagClient, "ready" | "isEnabled" | "close">;
+export interface HookTimeoutDebugContextFlagDependencies {
+    env?: NodeJS.ProcessEnv;
+    createClient?: (options: FlagClientOptions) => DebugContextFlagClient;
+    getToken?: FlagClientOptions["getToken"];
+    fetch?: typeof fetch;
+    reportFailure?: (error: unknown) => void;
+}
+/**
+ * Read the optional diagnostic gate with a short, cancellable hq-flags request.
+ * Missing identity/configuration and every client failure use the default-off
+ * result so a flag outage cannot delay or suppress the underlying timeout.
+ */
+export declare function hookTimeoutDebugContextEnabled(dependencies?: HookTimeoutDebugContextFlagDependencies, callerSignal?: AbortSignal): Promise<boolean>;
+export {};
+//# sourceMappingURL=hook-timeout-debug-context-flag.d.ts.map

package/dist/lib/core-utils/hook-timeout-debug-context-flag.js

@@ -0,0 +1,81 @@
+import { loadCachedTokens } from "@indigoai-us/hq-cloud";
+import { createFlagClient, } from "@indigoai-us/hq-flags-client";
+import { resolveProcessFlagCompanyContext } from "../flag-registry.js";
+import { resolveFlagRegistryEndpoint } from "../flag-registry-endpoint.js";
+export const HOOK_TIMEOUT_DEBUG_CONTEXT_FLAG = "hook-timeout-debug-context";
+export const HOOK_TIMEOUT_DEBUG_CONTEXT_FLAG_FALLBACK = false;
+export const HOOK_TIMEOUT_DEBUG_CONTEXT_FLAG_TIMEOUT_MS = 150;
+function safeErrorClass(error) {
+    const name = error instanceof Error ? error.name : "UnknownError";
+    return /^[A-Za-z][A-Za-z0-9]{0,63}$/.test(name) ? name : "UnknownError";
+}
+function reportFlagFailure(error) {
+    process.stderr.write(`HQ hook timeout debug flag lookup failed (${safeErrorClass(error)}); using default off.\n`);
+}
+function combineSignals(first, second) {
+    return first ? AbortSignal.any([first, second]) : second;
+}
+/**
+ * Read the optional diagnostic gate with a short, cancellable hq-flags request.
+ * Missing identity/configuration and every client failure use the default-off
+ * result so a flag outage cannot delay or suppress the underlying timeout.
+ */
+export async function hookTimeoutDebugContextEnabled(dependencies = {}, callerSignal) {
+    const env = dependencies.env ?? process.env;
+    const endpoint = resolveFlagRegistryEndpoint(undefined, env);
+    const { companyUid, companySlug } = resolveProcessFlagCompanyContext(env);
+    if (!companyUid) {
+        return HOOK_TIMEOUT_DEBUG_CONTEXT_FLAG_FALLBACK;
+    }
+    const deadline = AbortSignal.timeout(HOOK_TIMEOUT_DEBUG_CONTEXT_FLAG_TIMEOUT_MS);
+    const signal = callerSignal ? AbortSignal.any([callerSignal, deadline]) : deadline;
+    const doFetch = dependencies.fetch ?? globalThis.fetch;
+    let client;
+    let failed = false;
+    let failureReported = false;
+    let enabled = HOOK_TIMEOUT_DEBUG_CONTEXT_FLAG_FALLBACK;
+    const reportFailureOnce = (error) => {
+        failed = true;
+        if (failureReported)
+            return;
+        failureReported = true;
+        (dependencies.reportFailure ?? reportFlagFailure)(error);
+    };
+    try {
+        client = (dependencies.createClient ?? createFlagClient)({
+            endpoint,
+            companyUid,
+            ...(companySlug && /^[A-Za-z0-9][A-Za-z0-9-]{0,63}$/.test(companySlug)
+                ? { companyIdentifiers: [companySlug] }
+                : {}),
+            env: {},
+            getToken: dependencies.getToken ?? (() => loadCachedTokens()?.idToken ?? ""),
+            fetch: (input, init) => doFetch(input, {
+                ...init,
+                signal: combineSignals(init?.signal ?? undefined, signal),
+            }),
+            refreshIntervalMs: 0,
+            requestTimeoutMs: HOOK_TIMEOUT_DEBUG_CONTEXT_FLAG_TIMEOUT_MS,
+            onError: reportFailureOnce,
+        });
+        await client.ready();
+        if (!failed && !signal.aborted) {
+            enabled = client.isEnabled(HOOK_TIMEOUT_DEBUG_CONTEXT_FLAG, {
+                fallback: HOOK_TIMEOUT_DEBUG_CONTEXT_FLAG_FALLBACK,
+            });
+        }
+    }
+    catch (error) {
+        reportFailureOnce(error);
+    }
+    finally {
+        try {
+            client?.close();
+        }
+        catch (error) {
+            reportFailureOnce(error);
+        }
+    }
+    return failed || signal.aborted ? HOOK_TIMEOUT_DEBUG_CONTEXT_FLAG_FALLBACK : enabled;
+}
+//# sourceMappingURL=hook-timeout-debug-context-flag.js.map

package/dist/lib/core-utils/jq-json-serializer.d.ts

@@ -0,0 +1,5 @@
+/** JSON output formats used by the scaffold scripts that previously called jq. */
+export type JqJsonOutput = "compact" | "raw" | "pretty";
+/** Serialize one jq result, including jq's output newline. */
+export declare function serializeJqJson(value: unknown, output?: JqJsonOutput): string;
+//# sourceMappingURL=jq-json-serializer.d.ts.map

package/dist/lib/core-utils/jq-json-serializer.js

@@ -0,0 +1,10 @@
+/** Serialize one jq result, including jq's output newline. */
+export function serializeJqJson(value, output = "pretty") {
+    if (output === "raw" && typeof value === "string")
+        return `${value}\n`;
+    const serialized = output === "compact"
+        ? JSON.stringify(value)
+        : JSON.stringify(value, null, 2);
+    return serialized === undefined ? "" : `${serialized.replace(/\u007f/g, "\\u007f")}\n`;
+}
+//# sourceMappingURL=jq-json-serializer.js.map

package/dist/lib/core-utils/qmd-reindex-after-sync.d.ts

@@ -1,4 +1,8 @@
-import type { UtilityIo } from "./common.js";
+import { type EmbedLockDependencies } from "../search-index/embed-lock.js";
+import { type LoadGateDependencies } from "../search-index/load-gate.js";
+import { type UtilityIo } from "./common.js";
+export declare const QMD_REINDEX_STARTUP_WARNING_FLAG = "qmd.reindex-startup-warning";
+export declare const QMD_REINDEX_STARTUP_WARNING_FLAG_FALLBACK = false;
 export type QmdReindexOptions = UtilityIo & {
     cwd?: string;
     /** Test seams; default to the real search-index implementations. */
@@ -10,6 +14,15 @@ export type QmdReindexOptions = UtilityIo & {
         bin: string;
         cwd: string;
     }) => unknown;
+    sizeLimit?: (hqRoot: string) => unknown;
+    /** Test seams for the lock shared by every hq-cli QMD writer. */
+    embedLockDependencies?: EmbedLockDependencies;
+    /** Test seams for the host load gate consulted while the embed lock is held. */
+    loadGateDependencies?: LoadGateDependencies;
+    /** Test seam for the hq-flags-gated warning on qmd native startup failures. */
+    startupFailureWarningsEnabled?: () => boolean;
+    /** Test seam for the default-off shared lock around the full reindex pass. */
+    singleFlightEnabled?: () => boolean;
 };
 export declare function qmdReindexAfterSync(args?: string[], options?: QmdReindexOptions): number;
 //# sourceMappingURL=qmd-reindex-after-sync.d.ts.map

package/dist/lib/core-utils/qmd-reindex-after-sync.js

@@ -7,11 +7,24 @@
  *
  * Contract preserved verbatim: a missing qmd or a non-HQ path is a silent
  * success (a sync must never fail because indexing could not run), the lexical
- * update always runs, and embeddings rebuild only on `--embed`.
+ * update normally runs, and embeddings rebuild only on `--embed`. An enabled
+ * single-flight canary may skip a pass while another QMD writer owns the lock.
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { reconcileCollections, resolveQmdBin, runQmd } from "../search-index/index.js";
+import { reconcileCollections, resolveQmdBin, resolveQmdHome, runQmd } from "../search-index/index.js";
+import { applyIndexSizeLimit } from "../search-index/max-doc-bytes.js";
+import { defaultEmbedLockDependencies, runWithEmbedLock, } from "../search-index/embed-lock.js";
+import { LoadGateConfigurationError, checkEmbedLoad, defaultLoadGateDependencies, recordSuccessfulEmbed, } from "../search-index/load-gate.js";
+import { resolveProcessFlagGate } from "../flag-registry.js";
+import { qmdReindexSingleFlightEnabled } from "../search-index/reindex-single-flight-flag.js";
+import { isQmdNativeBindingError, QMD_NATIVE_BINDING_REMEDY, } from "../../utils/qmd-native-binding-error.js";
+import { ioFor, line } from "./common.js";
+export const QMD_REINDEX_STARTUP_WARNING_FLAG = "qmd.reindex-startup-warning";
+export const QMD_REINDEX_STARTUP_WARNING_FLAG_FALLBACK = false;
+function qmdStartupFailureWarningsEnabled() {
+    return resolveProcessFlagGate(QMD_REINDEX_STARTUP_WARNING_FLAG, { fallback: QMD_REINDEX_STARTUP_WARNING_FLAG_FALLBACK }, () => QMD_REINDEX_STARTUP_WARNING_FLAG_FALLBACK);
+}
 export function qmdReindexAfterSync(args = [], options = {}) {
     let hqRoot = "";
     let embed = false;
@@ -36,26 +49,97 @@ export function qmdReindexAfterSync(args = [], options = {}) {
         return 0;
     const reconcile = options.reconcile ?? ((root, opts) => reconcileCollections(root, opts));
     const run = options.run ?? ((argv, opts) => runQmd(argv, opts));
-    // Every qmd interaction is best-effort: the shell suffixed each with `|| true`.
-    try {
-        reconcile(hqRoot, { bin });
-    }
-    catch {
-        /* registration is advisory; an update still helps */
-    }
-    try {
-        run(["update"], { bin, cwd: hqRoot });
-    }
-    catch {
-        /* never fail a sync on index freshness */
-    }
-    if (embed) {
+    const sizeLimit = options.sizeLimit ?? ((root) => applyIndexSizeLimit(root));
+    const { stderr } = ioFor(options);
+    let startupFailureWarningShown = false;
+    const warnOnNativeStartupFailure = (error) => {
+        if (startupFailureWarningShown ||
+            !isQmdNativeBindingError(error) ||
+            !(options.startupFailureWarningsEnabled ?? qmdStartupFailureWarningsEnabled)())
+            return;
+        startupFailureWarningShown = true;
+        line(stderr, `hq: search index was not updated after sync; ${QMD_NATIVE_BINDING_REMEDY}`);
+    };
+    const updateIndex = () => {
+        // Every qmd interaction is best-effort: the shell suffixed each with `|| true`.
+        try {
+            reconcile(hqRoot, { bin });
+        }
+        catch {
+            /* registration is advisory; an update still helps */
+        }
+        // The cap has to land before the update: qmd decides what to read
+        // at glob time, so an ignore entry written afterwards saves nothing on this
+        // pass. This is the post-sync entry point, which reaches `qmd update` without
+        // going through `hq index sync` at all.
         try {
-            run(["embed"], { bin, cwd: hqRoot });
+            sizeLimit(hqRoot);
         }
         catch {
+            /* an uncapped index is worse than none, but still better than a failed sync */
+        }
+        try {
+            run(["update"], { bin, cwd: hqRoot });
+        }
+        catch (error) {
+            warnOnNativeStartupFailure(error);
+            /* never fail a sync on index freshness */
+        }
+    };
+    const runEmbed = (home, lockDependencies) => {
+        const loadGateDependencies = options.loadGateDependencies ?? defaultLoadGateDependencies(lockDependencies.env);
+        const decision = checkEmbedLoad(home, loadGateDependencies);
+        if (decision.action === "skip") {
+            line(stderr, decision.notice.trimEnd());
+            return "skipped";
+        }
+        if (decision.forced)
+            line(stderr, decision.notice.trimEnd());
+        run(["embed"], { bin, cwd: hqRoot });
+        recordSuccessfulEmbed(home, loadGateDependencies);
+        return undefined;
+    };
+    if ((options.singleFlightEnabled ?? qmdReindexSingleFlightEnabled)()) {
+        const lockDependencies = options.embedLockDependencies ?? defaultEmbedLockDependencies();
+        const home = resolveQmdHome(lockDependencies.env);
+        try {
+            const outcome = runWithEmbedLock(home, lockDependencies, () => {
+                updateIndex();
+                return embed ? runEmbed(home, lockDependencies) : undefined;
+            });
+            if (outcome === "busy") {
+                line(stderr, "hq: qmd reindex is already running; skipping this post-sync pass.");
+            }
+            if (outcome === "unavailable") {
+                line(stderr, "hq: cannot access the qmd reindex lock; skipping this post-sync pass.");
+            }
+        }
+        catch (error) {
+            if (error instanceof LoadGateConfigurationError)
+                line(stderr, `hq: ${error.message}`);
+            warnOnNativeStartupFailure(error);
             /* embeddings are deferred-cost and optional */
         }
+        return 0;
+    }
+    updateIndex();
+    if (!embed)
+        return 0;
+    const lockDependencies = options.embedLockDependencies ?? defaultEmbedLockDependencies();
+    const home = resolveQmdHome(lockDependencies.env);
+    try {
+        const outcome = runWithEmbedLock(home, lockDependencies, () => runEmbed(home, lockDependencies));
+        if (outcome === "busy") {
+            line(stderr, "hq: qmd embed is already running; skipping this pass.");
+        }
+        if (outcome === "unavailable")
+            line(stderr, "hq: cannot access the qmd embed lock; skipping this pass.");
+    }
+    catch (error) {
+        if (error instanceof LoadGateConfigurationError)
+            line(stderr, `hq: ${error.message}`);
+        warnOnNativeStartupFailure(error);
+        /* embeddings are deferred-cost and optional */
     }
     return 0;
 }

package/dist/lib/core-utils/secret-patterns.d.ts

@@ -0,0 +1,43 @@
+/** Shared secret detector patterns mirrored from the scaffold shell library. */
+export declare const SECRET_PATTERN_BOUNDARY = "(^|[^a-zA-Z0-9])";
+export declare const SECRET_PATTERNS: readonly [{
+    readonly pattern: "sk-[a-zA-Z0-9._-]{20,}";
+    readonly name: "OpenAI/Stripe key";
+}, {
+    readonly pattern: "ghp_[a-zA-Z0-9]{36,}";
+    readonly name: "GitHub PAT";
+}, {
+    readonly pattern: "AKIA[0-9A-Z]{16}";
+    readonly name: "AWS access key";
+}, {
+    readonly pattern: "xox[bpsa]-[a-zA-Z0-9-]+";
+    readonly name: "Slack token";
+}, {
+    readonly pattern: "Bearer [a-zA-Z0-9._-]{20,}";
+    readonly name: "Bearer token";
+}, {
+    readonly pattern: "-----BEGIN (RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----";
+    readonly name: "Private key";
+}, {
+    readonly pattern: "glpat-[a-zA-Z0-9_-]{20,}";
+    readonly name: "GitLab PAT";
+}, {
+    readonly pattern: "gho_[a-zA-Z0-9]{36,}";
+    readonly name: "GitHub OAuth token";
+}, {
+    readonly pattern: "github_pat_[a-zA-Z0-9_]{22,}";
+    readonly name: "Fine-grained GitHub PAT";
+}, {
+    readonly pattern: "eyJ[a-zA-Z0-9_-]{20,}\\.[a-zA-Z0-9_-]{20,}\\.[a-zA-Z0-9_-]{10,}";
+    readonly name: "JWT";
+}];
+/** Return the pattern names that match, in the shell library's declared order. */
+export declare function matchingSecretPatterns(value: string, options?: {
+    requireBoundary?: boolean;
+}): string[];
+/** Print only pattern names and paths; never include matched file content. */
+export declare function scanSecretFiles(files: readonly string[]): {
+    code: 0 | 1;
+    hits: string[];
+};
+//# sourceMappingURL=secret-patterns.d.ts.map

package/dist/lib/core-utils/secret-patterns.js

@@ -0,0 +1,34 @@
+/** Shared secret detector patterns mirrored from the scaffold shell library. */
+import * as fs from "node:fs";
+export const SECRET_PATTERN_BOUNDARY = "(^|[^a-zA-Z0-9])";
+export const SECRET_PATTERNS = [
+    { pattern: "sk-[a-zA-Z0-9._-]{20,}", name: "OpenAI/Stripe key" },
+    { pattern: "ghp_[a-zA-Z0-9]{36,}", name: "GitHub PAT" },
+    { pattern: "AKIA[0-9A-Z]{16}", name: "AWS access key" },
+    { pattern: "xox[bpsa]-[a-zA-Z0-9-]+", name: "Slack token" },
+    { pattern: "Bearer [a-zA-Z0-9._-]{20,}", name: "Bearer token" },
+    { pattern: "-----BEGIN (RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----", name: "Private key" },
+    { pattern: "glpat-[a-zA-Z0-9_-]{20,}", name: "GitLab PAT" },
+    { pattern: "gho_[a-zA-Z0-9]{36,}", name: "GitHub OAuth token" },
+    { pattern: "github_pat_[a-zA-Z0-9_]{22,}", name: "Fine-grained GitHub PAT" },
+    { pattern: "eyJ[a-zA-Z0-9_-]{20,}\\.[a-zA-Z0-9_-]{20,}\\.[a-zA-Z0-9_-]{10,}", name: "JWT" },
+];
+/** Return the pattern names that match, in the shell library's declared order. */
+export function matchingSecretPatterns(value, options = {}) {
+    const boundary = options.requireBoundary === false ? "" : SECRET_PATTERN_BOUNDARY;
+    return SECRET_PATTERNS.flatMap(({ pattern, name }) => new RegExp(`${boundary}${pattern}`).test(value) ? [name] : []);
+}
+/** Print only pattern names and paths; never include matched file content. */
+export function scanSecretFiles(files) {
+    const hits = [];
+    for (const file of files) {
+        if (!fs.existsSync(file) || !fs.statSync(file).isFile())
+            continue;
+        const contents = fs.readFileSync(file, "utf8");
+        for (const name of matchingSecretPatterns(contents)) {
+            hits.push(`secret-scan: pattern '${name}' matched in ${file}`);
+        }
+    }
+    return { code: hits.length > 0 ? 1 : 0, hits };
+}
+//# sourceMappingURL=secret-patterns.js.map

package/dist/lib/core-utils/sentry-report.d.ts

@@ -0,0 +1,114 @@
+/**
+ * `hq core sentry report` — constrained diagnostic transport for HQ hooks.
+ *
+ * The stdin event schema is deliberately closed. Hook payloads can contain
+ * commands, prompts, source content, transcript locations, and credentials, so
+ * this module accepts only a small set of scalar diagnostics plus bounded hook
+ * history and never reads a hook payload or the process environment. The
+ * owner-approved `hook_path`
+ * diagnostic is the narrow exception: it names the slow hook script and may
+ * include its company directory, but never carries the hook payload itself.
+ *
+ * Invalid top-level input and structurally rich metadata are rejected. The
+ * bounded hook sequence is the deliberate exception: it keeps only the most
+ * recent entries so diagnostics cannot expand the transport payload. Unknown
+ * scalar metadata is dropped instead: the allowlist, not a caller version
+ * match, determines what may leave the machine.
+ */
+import type { CaptureContext, SeverityLevel } from "@sentry/node";
+type SentryModule = typeof import("@sentry/node");
+export declare const DEFAULT_SENTRY_REPORT_TIMEOUT_MS = 750;
+export declare const MAX_SENTRY_REPORT_PAYLOAD_BYTES = 2048;
+export declare const MAX_SENTRY_REPORT_METADATA_VALUE_BYTES = 256;
+/**
+ * The only hook diagnostics that can be attached as metadata. The list omits
+ * command text, prompts, payloads, company names, and repositories. `hook_path`
+ * is owner-approved telemetry for the exact hook script and may include a
+ * company directory; it is never a substitute for hook input or a transcript.
+ */
+export declare const ALLOWED_SENTRY_REPORT_METADATA_KEYS: readonly ["hook_name", "hook_path", "hook_event", "hook_script", "tool_name", "session_id", "declared_timeout_ms", "elapsed_ms", "remaining_ms", "watchdog_timeout_ms", "hook_timeout_ms", "hq_version", "platform", "load_average", "spawn_ms", "slow_child", "slow_child_ms", "exit_code", "final_elapsed_ms", "bash_env_set", "cwd_kind", "shell", "nproc", "hook_sequence", "hook_timeout_debug_context"];
+export declare const MAX_SENTRY_REPORT_METADATA_KEYS: number;
+export type HookSequenceEntry = {
+    script: string;
+    event: string;
+    ms: number;
+};
+type HookTimeoutDebugPhaseTiming = {
+    phase: string;
+    elapsed_ms: number;
+};
+type HookTimeoutDebugContext = {
+    hook_name: string;
+    hook_event: string;
+    budget_ms: number;
+    elapsed_ms: number;
+    remaining_ms: number;
+    phase_timings: HookTimeoutDebugPhaseTiming[];
+    wait_point: string;
+    waiting_child_basename: string;
+    waiting_child_elapsed_ms: number;
+    load_average?: number | "unavailable";
+    spawn_ms?: number | "unavailable";
+    process_count?: number | "unavailable";
+};
+type SentryReportMetadataValue = string | number | boolean | HookSequenceEntry[] | HookTimeoutDebugContext;
+export type SentryReportMetadata = Record<string, SentryReportMetadataValue>;
+type SentryReportEvent = {
+    type: string;
+    message: string;
+    fingerprint: string;
+    level: SeverityLevel;
+    metadata: SentryReportMetadata;
+};
+export type SentryReportOptions = {
+    dryRun?: boolean;
+    /** Total time reserved for the report flush after validation. */
+    timeoutMs?: number;
+    /** Explicit live HQ root supplied by `hq core --hq-root`. */
+    hqRoot?: string;
+    /** Test seam for the bounded timeout-report stamp store. */
+    rateLimitDirectory?: string;
+    /** Test seam for deterministic rate-limit windows. */
+    rateLimitNow?: () => number;
+    /** Optional caller cancellation forwarded to the bounded flag lookup. */
+    signal?: AbortSignal;
+};
+export type SentryReportDependencies = {
+    sentry: {
+        captureMessage: (message: string, context?: CaptureContext | SeverityLevel) => string;
+        addBreadcrumb: (breadcrumb: Parameters<SentryModule["addBreadcrumb"]>[0]) => void;
+        metrics: Pick<SentryModule["metrics"], "count">;
+        flush: (timeout?: number) => PromiseLike<boolean>;
+    };
+    stdout: Pick<NodeJS.WriteStream, "write">;
+    stderr: Pick<NodeJS.WriteStream, "write">;
+    /** Test seam; production resolves the live HQ workspace tmp directory. */
+    rateLimitDirectory?: string;
+    /** Test seam; production uses Date.now. */
+    rateLimitNow?: () => number;
+    /** Test seam for the company-scoped, bounded debug-context gate. */
+    timeoutDebugContextEnabled?: (signal?: AbortSignal) => Promise<boolean>;
+};
+export type SentryReportResult = {
+    code: 0 | 1;
+    event?: SentryReportEvent;
+    droppedMetadataKeys?: number;
+};
+/**
+ * Read no more than the accepted event size. Returning early keeps a malformed
+ * pipe from making a watchdog retain an unbounded hook payload in memory.
+ */
+export declare function readSentryReportStdin(stdin: AsyncIterable<Buffer | string>): Promise<string | null>;
+/** Unknown metadata is ignored before this cap is evaluated. */
+export declare function exceedsSentryReportMetadataKeyCap(keys: Iterable<string>): boolean;
+/**
+ * Capture one validated Sentry message and wait only for the supplied bounded
+ * flush budget. A zero result means the event entered the local transport and
+ * its queue drained in time, not that ingest accepted it. Normal reports are
+ * silent on stdout; dry-runs print the same scrubbed event projection used by
+ * the live path. All failures use a generic stderr line so malformed input and
+ * transport errors cannot echo event data back to a hook.
+ */
+export declare function reportSentryEvent(stdin: string, options?: SentryReportOptions, dependencies?: SentryReportDependencies): Promise<SentryReportResult>;
+export {};
+//# sourceMappingURL=sentry-report.d.ts.map