@indigoai-us/hq-cli 5.274.1 → 5.276.0

package/dist/lib/lanes/models.d.ts

@@ -67,6 +67,8 @@ export declare function parseClaudeHelpModels(text: string): {
     aliases: string[];
     prefixes: string[];
 };
+/** Prefix of every Claude model full name, e.g. `claude-sonnet-5-5`. */
+export declare const CLAUDE_FULL_NAME_PREFIX = "claude-";
 export declare function claudeKnownModels(probe?: ProbeCommand, env?: NodeJS.ProcessEnv): KnownModels | null;
 export declare function knownModels(provider: LaneProvider, home: string, deps?: KnownModelsDeps): KnownModels | null;
 export declare function modelIsKnown(known: KnownModels, model: string): boolean;

package/dist/lib/lanes/models.js

@@ -154,6 +154,8 @@ export function parseClaudeHelpModels(text) {
     }
     return { aliases, prefixes: [...prefixes] };
 }
+/** Prefix of every Claude model full name, e.g. `claude-sonnet-5-5`. */
+export const CLAUDE_FULL_NAME_PREFIX = "claude-";
 export function claudeKnownModels(probe = defaultProbe, env = process.env) {
     const source = "claude --help";
     const result = probe("claude", ["--help"], env);
@@ -166,7 +168,10 @@ export function claudeKnownModels(probe = defaultProbe, env = process.env) {
         process.stderr.write(`hq lanes: \`${source}\` named no --model aliases (exit ${result.status ?? "spawn error"}); --model is not validated for claude\n`);
         return null;
     }
-    return { provider: "claude", ids: parsed.aliases, prefixes: parsed.prefixes, source };
+    // Every Claude model's full name starts with `claude-`. Accept it even when
+    // this help text carries no full-name example, as some releases' help does.
+    const prefixes = [...new Set([CLAUDE_FULL_NAME_PREFIX, ...parsed.prefixes])];
+    return { provider: "claude", ids: parsed.aliases, prefixes, source };
 }
 export function knownModels(provider, home, deps = {}) {
     switch (provider) {

package/dist/lib/lanes/reconcile.js

@@ -1812,7 +1812,7 @@ function resumeKeepAlive(hqRoot, lanes, questions, summary, deps, now, flagByCom
         const rechecked = deps.readKeepAliveRecheckLane?.(hqRoot, lane.lane_id) ?? readLane(hqRoot, lane.lane_id);
         // Dry-run backfills only in memory. Carry that simulated legacy timestamp
         // through the fresh read when the stored lane version has not changed.
-        const current = deps.dryRun &&
+        let current = deps.dryRun &&
             initialState === "interrupted" &&
             originalLane.interrupted_at === undefined &&
             lane.interrupted_at !== undefined &&
@@ -1907,6 +1907,19 @@ function resumeKeepAlive(hqRoot, lanes, questions, summary, deps, now, flagByCom
             recordKeepAliveSkip(hqRoot, current, currentExclusion, summary, deps);
             continue;
         }
+        if (current.keep_alive_blocked_reason === "superseded") {
+            // The fresh exclusion check found no active successor. Clear the stale
+            // reason before any later exit (backoff, queue full, retry cap, hire
+            // refusal) so the watcher keeps treating the lane as resumable.
+            const cleared = casLaneIf(hqRoot, current.lane_id, (latestLane) => latestLane.version === current.version &&
+                latestLane.state === current.state &&
+                latestLane.keep_alive === true &&
+                latestLane.keep_alive_opted_in_at === current.keep_alive_opted_in_at &&
+                latestLane.keep_alive_blocked_reason === "superseded", (latestLane) => ({ ...latestLane, keep_alive_blocked_reason: undefined }), deps.dryRun);
+            if (!cleared.changed)
+                continue;
+            current = cleared.record;
+        }
         const currentSessionId = current.provider_session_id ?? current.last_resume?.session_id;
         if (!providerSupportsSessionResume(current.provider) ||
             typeof currentSessionId !== "string" ||
@@ -1934,9 +1947,12 @@ function resumeKeepAlive(hqRoot, lanes, questions, summary, deps, now, flagByCom
             continue;
         }
         const attempt = attempts + 1;
+        // A done turn ends no later than its done envelope. Bookkeeping writes
+        // (such as clearing a stale block) move updated_at but not the envelope,
+        // so they cannot push the retry clock forward.
         const terminalAtMs = initialState === "done"
-            ? Date.parse(current.updated_at)
-            : Date.parse(current.interrupted_at ?? "");
+            ? Math.min(Date.parse(current.updated_at), currentEligibilityAtMs)
+            : currentEligibilityAtMs;
         const attemptEligibleMs = terminalAtMs + leadLaneKeepAliveBackoffMs(attempt);
         const storedNextMs = resetByHuman
             ? Number.NaN
@@ -1967,7 +1983,7 @@ function resumeKeepAlive(hqRoot, lanes, questions, summary, deps, now, flagByCom
             });
             continue;
         }
-        const resumedFrom = current.state;
+        const resumedFrom = current.state === "done" ? "done" : "interrupted";
         const resumeText = resumedFrom === "interrupted"
             ? LEAD_LANE_KEEP_ALIVE_INTERRUPTED_RESUME_TEXT
             : LEAD_LANE_KEEP_ALIVE_RESUME_TEXT;

package/dist/lib/process-flag-company-context.d.ts

@@ -0,0 +1,8 @@
+/** Company scope shared by the full flag registry and its fast-path reader. */
+export interface ProcessFlagCompanyContext {
+    companyUid?: string;
+    companySlug?: string;
+}
+/** Resolve the same company identity the process-wide flag reader uses. */
+export declare function resolveProcessFlagCompanyContext(env?: NodeJS.ProcessEnv): ProcessFlagCompanyContext;
+//# sourceMappingURL=process-flag-company-context.d.ts.map

package/dist/lib/process-flag-company-context.js

@@ -0,0 +1,67 @@
+/** Company scope shared by the full flag registry and its fast-path reader. */
+import { readMachineCompanyBinding } from "./work-context/company.js";
+import { readSessionState } from "./work-context/state.js";
+import { workContextRoot } from "./work-context/paths.js";
+import { readCompaniesManifestMap } from "./work-context/repo-remote.js";
+import { resolveDefaultHqRoot } from "../utils/hq-root-resolver.js";
+const COMPANY_UID_RE = /^cmp_[A-Za-z0-9]{3,128}$/;
+const COMPANY_SLUG_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+function normalizedCompanyUid(value) {
+    const candidate = value?.trim() ?? "";
+    return COMPANY_UID_RE.test(candidate) ? candidate : undefined;
+}
+function normalizedCompanySlug(value) {
+    const candidate = value?.trim() ?? "";
+    return COMPANY_SLUG_RE.test(candidate) ? candidate : undefined;
+}
+/** Resolve explicit, machine, or bound-session company scope without defaults. */
+function processCompanyContext(env = process.env) {
+    const explicitUid = normalizedCompanyUid(env.HQ_COMPANY_UID);
+    const explicitSlug = normalizedCompanySlug(env.HQ_COMPANY_SLUG);
+    if (explicitUid || explicitSlug) {
+        return { companyUid: explicitUid, companySlug: explicitSlug };
+    }
+    const machine = readMachineCompanyBinding(env);
+    const spawnValue = env.HQ_SPAWN_COMPANY?.trim();
+    const spawnSlug = normalizedCompanySlug(spawnValue);
+    const machineContext = spawnValue && COMPANY_UID_RE.test(spawnValue)
+        ? { companyUid: spawnValue }
+        : spawnSlug
+            ? { companySlug: spawnSlug }
+            : {
+                companyUid: normalizedCompanyUid(machine?.uid),
+                companySlug: normalizedCompanySlug(machine?.slug),
+            };
+    if (machineContext.companyUid || machineContext.companySlug)
+        return machineContext;
+    const sessionId = env.HQ_SESSION_ID?.trim();
+    if (!sessionId)
+        return {};
+    const session = readSessionState(sessionId, workContextRoot(undefined, env));
+    if (session?.contextStatus !== "bound" || session.companyConfidence === "device_default") {
+        return {};
+    }
+    return {
+        companyUid: normalizedCompanyUid(session.companyUid),
+        companySlug: normalizedCompanySlug(session.companySlug),
+    };
+}
+function companyUidForContext(context, env = process.env) {
+    if (context.companyUid)
+        return context.companyUid;
+    if (!context.companySlug)
+        return undefined;
+    const hqRoot = resolveDefaultHqRoot({ env });
+    const manifestUid = readCompaniesManifestMap(hqRoot)?.[context.companySlug]?.cloud_uid;
+    return typeof manifestUid === "string" ? normalizedCompanyUid(manifestUid) : undefined;
+}
+/** Resolve the same company identity the process-wide flag reader uses. */
+export function resolveProcessFlagCompanyContext(env = process.env) {
+    const context = processCompanyContext(env);
+    const companyUid = companyUidForContext(context, env);
+    return {
+        ...(companyUid ? { companyUid } : {}),
+        ...(context.companySlug ? { companySlug: context.companySlug } : {}),
+    };
+}
+//# sourceMappingURL=process-flag-company-context.js.map

package/dist/main.js

@@ -43,7 +43,7 @@ import { enforceVersionGate, shouldSkipGate, } from "./utils/version-gate.js";
 import { autoUpdateAndReexec } from "./utils/self-update.js";
 import { CLI_VERSION } from "./cli-version.js";
 import { findLazyCommand, registerCommandCatalog } from "./lazy-commands.js";
-import { emitCliFirstSyncNextStepOutcome, emitCliSessionStarted, takeFirstSyncStepOutcomes, maybeShowFirstSyncNextStep, } from "./utils/cli-telemetry.js";
+import { emitCliFirstSyncNextStepOutcome, emitCliSessionStarted, emitPlanLimitInviteTeammateExposure, takeFirstSyncStepOutcomes, takePlanLimitInviteTeammateExposures, maybeShowFirstSyncNextStep, } from "./utils/cli-telemetry.js";
 import { reportCliClientHealthInvocation } from "./utils/client-health.js";
 import { settleWithin } from "./utils/settle-with-timeout.js";
 import { emitPlanLimitNag } from "./lib/plan-limit-nag.js";
@@ -294,10 +294,12 @@ export async function runCli() {
             // slice even when the command itself was long-running.
             const releaseHealthTimeoutMs = foregroundNetworkBudget.timeoutFor(FINALIZATION_FOREGROUND_WAIT_MS);
             const firstSyncOutcomeFlushes = takeFirstSyncStepOutcomes().map((outcome) => emitCliFirstSyncNextStepOutcome(outcome, releaseHealthTimeoutMs));
+            const inviteTeammateExposureFlushes = takePlanLimitInviteTeammateExposures().map((companyUid) => emitPlanLimitInviteTeammateExposure(companyUid, releaseHealthTimeoutMs));
             await settleWithin([
                 refreshVersionCache({ timeoutMs: releaseHealthTimeoutMs }),
                 Sentry.flush(releaseHealthTimeoutMs),
                 ...firstSyncOutcomeFlushes,
+                ...inviteTeammateExposureFlushes,
             ], releaseHealthTimeoutMs);
         });
         // Last, so it wins over anything the (skipped) command path would have

package/dist/native-fast-route.d.ts

@@ -0,0 +1,3 @@
+/** Default-off flag check for native entrypoint routes. */
+export declare function nativeFastRouteEnabled(argv: readonly string[], env?: NodeJS.ProcessEnv): Promise<boolean>;
+//# sourceMappingURL=native-fast-route.d.ts.map

package/dist/native-fast-route.js

@@ -0,0 +1,39 @@
+/** Default-off flag check for native entrypoint routes. */
+import { localOverrideEnvVar, readLocalOverride } from "@indigoai-us/hq-flags-client";
+import { parseFastCore } from "./fast-scaffold.js";
+export async function nativeFastRouteEnabled(argv, env = process.env) {
+    const parsed = parseFastCore(argv);
+    if (!parsed || parsed.entry.kind !== "native")
+        return false;
+    const override = nativeRouteOverride(parsed.entry.flagKey, env);
+    if (override !== null)
+        return override;
+    try {
+        const [{ resolveProcessFlagCompanyContext }, { readFlagSnapshotFile }] = await Promise.all([
+            import("./lib/process-flag-company-context.js"),
+            import("./lib/flag-snapshot-file.js"),
+        ]);
+        const { companyUid } = resolveProcessFlagCompanyContext(env);
+        if (!companyUid)
+            return false;
+        return readFlagSnapshotFile(companyUid, { env })?.flags[parsed.entry.flagKey] === true;
+    }
+    catch {
+        // The new path is a rollout optimization. Any unavailable local scope or
+        // cache data leaves the established full-graph route in control.
+        return false;
+    }
+}
+/** The route's documented CLI override also accepts the conventional 1/0. */
+function nativeRouteOverride(flagKey, env) {
+    const override = readLocalOverride(flagKey, env);
+    if (override !== null)
+        return override;
+    const raw = env[localOverrideEnvVar(flagKey)];
+    if (raw === "1")
+        return true;
+    if (raw === "0")
+        return false;
+    return null;
+}
+//# sourceMappingURL=native-fast-route.js.map

package/dist/utils/cli-telemetry.d.ts

@@ -3,16 +3,39 @@ export { CLI_FIRST_SYNC_NEXT_STEP_FLAG, FIRST_SYNC_CONFIRMATION_COPY, FIRST_SYNC
 export declare const TELEMETRY_TIMEOUT_MS = 1200;
 /**
  * Exact stderr line printed once on the first signed-in TTY run that is not
- * `--json`. Keep this notice and its marker stable for the default telemetry
- * path; first-sync fields have a separate opt-in disclosure below.
+ * `--json`. Keep this notice and its marker stable for session telemetry;
+ * first-sync and feature-used fields have separate opt-in disclosures below.
  */
 export declare const TELEMETRY_DISCLOSURE_LINE = "HQ sends a usage event when you run a signed-in command (CLI version and a timestamp, never command names, file contents, or secrets) to improve the CLI. Set HQ_TELEMETRY=0 to turn this off.";
 export declare const FIRST_SYNC_TELEMETRY_DISCLOSURE_LINE = "HQ sends a usage event when you run a signed-in command (CLI version and a timestamp; when enabled, first-sync guidance shown or followed and the flag key cli.first-sync-next-step; never command names, file contents, or secrets) to improve the CLI. Set HQ_TELEMETRY=0 to turn this off.";
+export declare const CLI_FEATURE_USED_TELEMETRY_FLAG = "cli.feature-used-telemetry-v1";
+export declare const CLI_FEATURE_USED_TELEMETRY_DISCLOSURE_LINE = "HQ sends a feature-use event when you run a supported CLI feature (feature kind and outcome, plus your company UID when available; never command names, file contents, or secrets). The hq-flags key cli.feature-used-telemetry-v1 controls these events. Set HQ_TELEMETRY=0 to turn this off.";
+/** Queue one exposure after the CLI has printed the invite suggestion. */
+export declare function queuePlanLimitInviteTeammateExposure(companyUid: string): void;
+/** Drain invite-suggestion exposures for the bounded command-finalization flush. */
+export declare function takePlanLimitInviteTeammateExposures(): string[];
+export type CliFeatureKind = "secret_read" | "lane_create" | "lane_resume";
+export type CliFeatureOutcome = "success" | "failure";
+export interface CliFeatureUsage {
+    kind: CliFeatureKind;
+    outcome: CliFeatureOutcome;
+    /** Only company UIDs are accepted; names and slugs are never telemetry fields. */
+    companyUid?: string;
+}
+/**
+ * Emit one bounded, privacy-limited feature-use event with a cached identity.
+ * It never refreshes credentials or turns telemetry failure into command failure.
+ */
+export declare function emitCliFeatureUsed(usage: CliFeatureUsage, timeoutMs?: number): Promise<void>;
+/** Run one action and emit exactly one success/failure event without masking errors. */
+export declare function withCliFeatureUsed<T>(kind: CliFeatureKind, action: () => Promise<T>, companyUid?: string): Promise<T>;
 /**
  * `HQ_TELEMETRY=0` (also `false` and `off`, case-insensitive) disables every
  * CLI POST to `/v1/telemetry/events`. `HQ_TELEMETRY_TIMEOUT_MS` is unchanged.
  */
 export declare function isCliTelemetryDisabled(env?: NodeJS.ProcessEnv): boolean;
+/** Feature-use collection stays off until the HQ flag is explicitly enabled. */
+export declare function isCliFeatureUsedTelemetryEnabled(): boolean;
 export declare function telemetryDisclosureMarkerPath(): string;
 /**
  * Print the one-line disclosure at most once per machine. Returns whether
@@ -31,4 +54,5 @@ export declare function maybeDiscloseCliTelemetry(stderr?: {
 export declare function emitCliSessionStarted(timeoutMs?: number): Promise<void>;
 /** Emit one authenticated measurement for a first-sync prompt outcome. */
 export declare function emitCliFirstSyncNextStepOutcome(outcome: FirstSyncStepOutcome, timeoutMs?: number): Promise<void>;
+export declare function emitPlanLimitInviteTeammateExposure(companyUid: string, timeoutMs?: number): Promise<void>;
 //# sourceMappingURL=cli-telemetry.d.ts.map

package/dist/utils/cli-telemetry.js

@@ -1,23 +1,117 @@
+import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { CLI_VERSION } from "../cli-version.js";
-import { isExpiring, isMachineIdentity, loadCachedTokens, } from "./cognito-session.js";
+import { isExpiring, isMachineIdentity, loadCachedTokens, loadMachineCachedTokens, } from "./cognito-session.js";
+import { resolveProcessFlagGate } from "../lib/flag-registry.js";
 import { vaultApiFetch } from "./vault-api.js";
 import { firstSyncStepTelemetryProperties, isFirstSyncNextStepEnabled, isHumanInteractiveCliSession, } from "../lib/first-sync-next-step.js";
 export { CLI_FIRST_SYNC_NEXT_STEP_FLAG, FIRST_SYNC_CONFIRMATION_COPY, FIRST_SYNC_NEXT_STEP_COPY, claimFirstSyncStepMarker, firstSyncStepMarkerPaths, firstSyncStepTelemetryProperties, isFirstSyncNextStepEnabled, isHumanInteractiveCliSession, isWorkBearingSyncResult, maybeShowFirstSyncNextStep, recordFirstWorkBearingSync, shouldConfirmFirstWorkBearingSync, shouldShowFirstSyncNextStep, takeFirstSyncStepOutcomes, } from "../lib/first-sync-next-step.js";
 export const TELEMETRY_TIMEOUT_MS = 1_200;
 /**
  * Exact stderr line printed once on the first signed-in TTY run that is not
- * `--json`. Keep this notice and its marker stable for the default telemetry
- * path; first-sync fields have a separate opt-in disclosure below.
+ * `--json`. Keep this notice and its marker stable for session telemetry;
+ * first-sync and feature-used fields have separate opt-in disclosures below.
  */
 export const TELEMETRY_DISCLOSURE_LINE = "HQ sends a usage event when you run a signed-in command (CLI version and a timestamp, never command names, file contents, or secrets) to improve the CLI. Set HQ_TELEMETRY=0 to turn this off.";
 export const FIRST_SYNC_TELEMETRY_DISCLOSURE_LINE = "HQ sends a usage event when you run a signed-in command (CLI version and a timestamp; when enabled, first-sync guidance shown or followed and the flag key cli.first-sync-next-step; never command names, file contents, or secrets) to improve the CLI. Set HQ_TELEMETRY=0 to turn this off.";
+export const CLI_FEATURE_USED_TELEMETRY_FLAG = "cli.feature-used-telemetry-v1";
+export const CLI_FEATURE_USED_TELEMETRY_DISCLOSURE_LINE = "HQ sends a feature-use event when you run a supported CLI feature (feature kind and outcome, plus your company UID when available; never command names, file contents, or secrets). The hq-flags key cli.feature-used-telemetry-v1 controls these events. Set HQ_TELEMETRY=0 to turn this off.";
 const TELEMETRY_DISABLED_VALUES = new Set(["0", "false", "off"]);
 const DISCLOSURE_MARKER = "cli-telemetry-disclosed";
 const FIRST_SYNC_DISCLOSURE_MARKER = "cli-telemetry-disclosed-first-sync-v1";
+const FEATURE_USED_DISCLOSURE_MARKER = "cli-telemetry-disclosed-feature-used-v1";
 let cliSessionStartedPromise;
+const pendingPlanLimitInviteTeammateExposures = [];
+/** Queue one exposure after the CLI has printed the invite suggestion. */
+export function queuePlanLimitInviteTeammateExposure(companyUid) {
+    const normalizedCompanyUid = companyUid.trim();
+    if (normalizedCompanyUid.length === 0)
+        return;
+    pendingPlanLimitInviteTeammateExposures.push(normalizedCompanyUid);
+}
+/** Drain invite-suggestion exposures for the bounded command-finalization flush. */
+export function takePlanLimitInviteTeammateExposures() {
+    return pendingPlanLimitInviteTeammateExposures.splice(0, pendingPlanLimitInviteTeammateExposures.length);
+}
+const COMPANY_UID_PATTERN = /^cmp_[A-Za-z0-9_-]{1,128}$/;
+/**
+ * Emit one bounded, privacy-limited feature-use event with a cached identity.
+ * It never refreshes credentials or turns telemetry failure into command failure.
+ */
+export async function emitCliFeatureUsed(usage, timeoutMs = TELEMETRY_TIMEOUT_MS) {
+    try {
+        // Unit tests may run with a real cached user/agent token on the host. Never
+        // let their command fixtures write telemetry to a live account.
+        if (process.env.NODE_ENV === "test")
+            return;
+        if (isCliTelemetryDisabled() || !isCliFeatureUsedTelemetryEnabled())
+            return;
+        const machineIdentity = isMachineIdentity();
+        const cached = machineIdentity ? loadMachineCachedTokens() : loadCachedTokens();
+        if (!cached || isExpiring(cached, 120))
+            return;
+        const token = machineIdentity ? cached.idToken : cached.accessToken;
+        if (!token)
+            return;
+        const consentBasis = maybeDiscloseFeatureUsedTelemetry() ? "disclosed" : "no-consent";
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), timeoutMs);
+        const companyUid = usage.companyUid && COMPANY_UID_PATTERN.test(usage.companyUid)
+            ? usage.companyUid
+            : undefined;
+        try {
+            await vaultApiFetch({
+                token,
+                path: "/v1/telemetry/events",
+                method: "POST",
+                body: {
+                    events: [
+                        {
+                            eventName: "cli_feature_used",
+                            app: "hq-cli",
+                            source: "cli",
+                            occurredAt: new Date().toISOString(),
+                            consentBasis,
+                            schemaVersion: 1,
+                            ...(companyUid ? { companyUid } : {}),
+                            properties: { kind: usage.kind, outcome: usage.outcome },
+                        },
+                    ],
+                },
+                signal: controller.signal,
+            });
+        }
+        catch {
+            // Feature telemetry is best effort and must never affect the CLI action.
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    catch {
+        // Cached-token reads are also best effort (for example, a malformed cache).
+    }
+}
+/** Run one action and emit exactly one success/failure event without masking errors. */
+export async function withCliFeatureUsed(kind, action, companyUid) {
+    let outcome = "success";
+    try {
+        return await action();
+    }
+    catch (err) {
+        outcome = "failure";
+        throw err;
+    }
+    finally {
+        await emitCliFeatureUsed({
+            kind,
+            outcome,
+            ...(companyUid ? { companyUid } : {}),
+        });
+    }
+}
 /**
  * `HQ_TELEMETRY=0` (also `false` and `off`, case-insensitive) disables every
  * CLI POST to `/v1/telemetry/events`. `HQ_TELEMETRY_TIMEOUT_MS` is unchanged.
@@ -28,6 +122,10 @@ export function isCliTelemetryDisabled(env = process.env) {
         return false;
     return TELEMETRY_DISABLED_VALUES.has(raw);
 }
+/** Feature-use collection stays off until the HQ flag is explicitly enabled. */
+export function isCliFeatureUsedTelemetryEnabled() {
+    return resolveProcessFlagGate(CLI_FEATURE_USED_TELEMETRY_FLAG, { fallback: false }, () => false);
+}
 function hqConfigDir() {
     const home = process.env.HOME?.trim() || os.homedir();
     return path.join(home, ".hq");
@@ -38,6 +136,9 @@ export function telemetryDisclosureMarkerPath() {
 function firstSyncTelemetryDisclosureMarkerPath() {
     return path.join(hqConfigDir(), FIRST_SYNC_DISCLOSURE_MARKER);
 }
+function featureUsedTelemetryDisclosureMarkerPath() {
+    return path.join(hqConfigDir(), FEATURE_USED_DISCLOSURE_MARKER);
+}
 function wantsJsonOutput(argv = process.argv) {
     return argv.includes("--json");
 }
@@ -75,6 +176,9 @@ export function maybeDiscloseCliTelemetry(stderr = process.stderr, stdout = proc
 function maybeDiscloseFirstSyncTelemetry() {
     return maybeDiscloseTelemetry(FIRST_SYNC_TELEMETRY_DISCLOSURE_LINE, firstSyncTelemetryDisclosureMarkerPath());
 }
+function maybeDiscloseFeatureUsedTelemetry() {
+    return maybeDiscloseTelemetry(CLI_FEATURE_USED_TELEMETRY_DISCLOSURE_LINE, featureUsedTelemetryDisclosureMarkerPath());
+}
 function maybeDiscloseTelemetry(line, markerPath, stderr = process.stderr, stdout = process.stdout, argv = process.argv) {
     if (hasShownDisclosure(markerPath))
         return true;
@@ -207,4 +311,75 @@ export async function emitCliFirstSyncNextStepOutcome(outcome, timeoutMs = TELEM
         // Cached-token reads are also best effort (for example, a malformed cache).
     }
 }
+/** Emit one company-scoped event for a printed invite-teammate suggestion. */
+function logPlanLimitInviteTeammateExposureFailure(cause, status) {
+    const errorClass = cause instanceof Error ? cause.name : "unknown";
+    const result = status === undefined ? errorClass : `http_${status}`;
+    console.error(`hq: Could not send invite-teammate exposure telemetry (${result}).`);
+}
+export async function emitPlanLimitInviteTeammateExposure(companyUid, timeoutMs = TELEMETRY_TIMEOUT_MS) {
+    try {
+        if (isCliTelemetryDisabled())
+            return;
+        const cached = loadCachedTokens();
+        const machineIdentity = isMachineIdentity();
+        if (!cached ||
+            isExpiring(cached, 120) ||
+            !isHumanInteractiveCliSession({
+                stdoutIsTTY: Boolean(process.stdout.isTTY),
+                argv: process.argv,
+                env: process.env,
+                machineIdentity,
+            })) {
+            return;
+        }
+        const token = cached.accessToken;
+        if (!token)
+            return;
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const response = await vaultApiFetch({
+                token,
+                path: "/v1/telemetry/events",
+                method: "POST",
+                body: {
+                    events: [
+                        {
+                            eventName: "plan_limit_prompt_exposed",
+                            app: "hq-cli",
+                            source: "cli",
+                            occurredAt: new Date().toISOString(),
+                            consentBasis: "no-consent",
+                            schemaVersion: 2,
+                            companyUid,
+                            idempotencyKey: randomUUID(),
+                            properties: {
+                                surface: "cli_whoami_plan_limit",
+                                resourceKind: "users",
+                                presentationKind: "advisory",
+                                exposureId: randomUUID(),
+                            },
+                        },
+                    ],
+                },
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                logPlanLimitInviteTeammateExposureFailure(undefined, response.status);
+            }
+        }
+        catch (error) {
+            // This measurement is best-effort and must not affect the CLI command.
+            logPlanLimitInviteTeammateExposureFailure(error);
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    catch (error) {
+        // Cached-token reads and identity checks are best-effort too.
+        logPlanLimitInviteTeammateExposureFailure(error);
+    }
+}
 //# sourceMappingURL=cli-telemetry.js.map

package/dist/utils/hq-root-resolver.d.ts

@@ -0,0 +1,13 @@
+/** Lightweight HQ-root resolver shared by cloud commands and fast flag scope. */
+/**
+ * Resolve the HQ tree root using the same precedence as the Cognito helpers:
+ * explicit HQ_ROOT, nearest cwd root, installer records, known locations, then
+ * the historical ~/hq fallback (or an error when requested).
+ */
+export declare function resolveDefaultHqRoot(opts?: {
+    onMissing?: "throw" | "fallback";
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    home?: string;
+}): string;
+//# sourceMappingURL=hq-root-resolver.d.ts.map

package/dist/utils/hq-root-resolver.js

@@ -0,0 +1,103 @@
+/** Lightweight HQ-root resolver shared by cloud commands and fast flag scope. */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import * as yaml from "js-yaml";
+/**
+ * Resolve the HQ tree root using the same precedence as the Cognito helpers:
+ * explicit HQ_ROOT, nearest cwd root, installer records, known locations, then
+ * the historical ~/hq fallback (or an error when requested).
+ */
+export function resolveDefaultHqRoot(opts = {}) {
+    const env = opts.env ?? process.env;
+    const home = opts.home ?? os.homedir();
+    if (env.HQ_ROOT)
+        return path.resolve(env.HQ_ROOT);
+    let cur = path.resolve(opts.cwd ?? process.cwd());
+    while (cur !== path.dirname(cur)) {
+        if (isHqRoot(cur))
+            return cur;
+        cur = path.dirname(cur);
+    }
+    const fromConfig = readHqRootFromHqConfig(path.join(home, ".hq"));
+    if (fromConfig)
+        return path.resolve(fromConfig);
+    const discovered = discoverHqRootViaCoreYaml(home);
+    if (discovered)
+        return discovered;
+    if (opts.onMissing === "throw") {
+        throw new Error("Could not find HQ root. Run this command from within your HQ directory " +
+            "(must contain core.yaml AND a companies/ subdirectory), set $HQ_ROOT, " +
+            "or install HQ via the installer/menubar so ~/.hq/menubar.json records " +
+            "its location.");
+    }
+    return path.join(home, "hq");
+}
+function readHqRootFromHqConfig(hqConfigDir) {
+    const fromMenubar = readJsonStringField(path.join(hqConfigDir, "menubar.json"), "hqPath");
+    if (fromMenubar)
+        return fromMenubar;
+    return readJsonStringField(path.join(hqConfigDir, "config.json"), "hqFolderPath");
+}
+function readJsonStringField(file, field) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
+        const value = parsed[field];
+        return typeof value === "string" && value.length > 0 ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function hqDiscoveryCandidates(home) {
+    return [
+        path.join(home, "HQ"),
+        path.join(home, "hq"),
+        path.join(home, "Documents", "HQ"),
+        path.join(home, "Documents", "hq"),
+        path.join(home, "Desktop", "HQ"),
+        path.join(home, "Desktop", "hq"),
+    ];
+}
+function discoverHqRootViaCoreYaml(home) {
+    return hqDiscoveryCandidates(home).find(isValidHqRootSignature);
+}
+function isValidHqRootSignature(dir) {
+    const canonical = path.join(dir, "core", "core.yaml");
+    const legacy = path.join(dir, "core.yaml");
+    let file;
+    if (fileExists(canonical))
+        file = canonical;
+    else if (fileExists(legacy))
+        file = legacy;
+    else
+        return false;
+    try {
+        const parsed = yaml.load(fs.readFileSync(file, "utf-8"));
+        return !!parsed && typeof parsed === "object" && "version" in parsed && "hqVersion" in parsed;
+    }
+    catch {
+        return false;
+    }
+}
+function fileExists(file) {
+    try {
+        return fs.statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function isHqRoot(dir) {
+    const hasCoreYaml = fileExists(path.join(dir, "core", "core.yaml")) ||
+        fileExists(path.join(dir, "core.yaml"));
+    if (!hasCoreYaml)
+        return false;
+    try {
+        return fs.statSync(path.join(dir, "companies")).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=hq-root-resolver.js.map

package/dist/utils/scaffold-fast-import-guard.js

@@ -4,6 +4,8 @@ export function forbiddenFastPathModules(loadedModules, distDirectory) {
     const dist = path.resolve(distDirectory);
     const main = path.join(dist, "main.js");
     const commands = `${path.join(dist, "commands")}${path.sep}`;
+    const flagRegistry = path.join(dist, "lib", "flag-registry.js");
+    const coreCommand = path.join(dist, "commands", "core.js");
     return [...new Set(loadedModules.map((loaded) => {
             if (loaded.startsWith("file:")) {
                 try {
@@ -16,7 +18,10 @@ export function forbiddenFastPathModules(loadedModules, distDirectory) {
             return path.resolve(loaded);
         }))]
         .filter((loaded) => path.resolve(loaded) === main ||
-        path.resolve(loaded).startsWith(commands))
+        path.resolve(loaded).startsWith(commands) ||
+        path.resolve(loaded) === flagRegistry ||
+        path.resolve(loaded) === coreCommand ||
+        path.resolve(loaded).includes(`${path.sep}node_modules${path.sep}@sentry${path.sep}node${path.sep}`))
         .sort();
 }
 export function assertFastPathStaysCommandGraphFree(loadedModules, distDirectory) {